人人都会AI编程

7.1 tauri.conf.json 配置详解

更新时间：2026-07-11

tauri.conf.json 是每个 Tauri 项目的核心配置文件，你几乎所有的打包、窗口、安全、启动行为都在这里定义。它位于项目根目录，创建项目时自动生成，使用 JSON 或 JSON5 格式书写（支持注释和尾逗号）。一个完整的配置通常分为 build、package、plugins 和 app 四大区域，下面逐一说明最常用的部分。

1. build：构建流程控制

控制 Tauri CLI 如何与你的前端项目协作。

"build": {
  "beforeBuildCommand": "npm run build",   // 构建 Rust 应用前需要执行的命令（比如打包前端资源）
  "beforeDevCommand": "npm run dev",       // 启动开发服务器前执行的命令
  "devUrl": "http://localhost:5173",       // 开发模式下前端运行的地址（Vite 默认端口）
  "frontendDist": "../dist"                // 生产模式时前端构建产物的目录（相对 tauri 目录）
}
  • 关键点：frontendDist 指向 Vite/Webpack 打包后的静态资源文件夹，Tauri 会内嵌该目录作为前端 UI。
  • 实用技巧：如果你的前端构建输出固定，可以使用 "dist"；如果使用 monorepo，需要调整相对路径。

2. app：应用本体行为

这是最核心的部分，窗口、托盘、安全策略都在这里。

app.windows：窗口配置

每个窗口都是一个配置对象，可以定义多个窗口。

"windows": [
  {
    "title": "我的应用",
    "width": 800,
    "height": 600,
    "resizable": true,
    "fullscreen": false,
    "decorations": true,        // 是否显示标题栏和边框（false 可实现无边框窗口）
    "alwaysOnTop": false,
    "center": true,             // 启动时居中
    "url": "index.html",        // 窗口加载的路径（相对于 frontendDist）
    "label": "main"             // 窗口唯一标识，用于程序内部控制
  }
]
  • 可以添加 "visible": false 来创建隐藏窗口，适合托盘应用。
  • 多窗口：直接在这个数组中添加多个对象，每个都有独立 label，用 Rust 代码动态控制。

app.security：安全策略（关键）

Tauri 的安全模型核心，默认全部拒绝。

"security": {
  "csp": null,                  // 可自定义 Content-Security-Policy 字符串
  "dangerousDisableAssetCspModification": false,  // 不要随便开启，会降低安全性
  "assetProtocol": {            // 限制哪些资产可以被加载
    "enable": true,
    "scope": ["**"]
  }
}
  • 通常情况下不需要修改，除非你需要加载外部资源或特殊 CSP 配置。
  • 如果你的前端需要加载远程图片/脚本，需要在 security.dangerousRemoteDomainIpcAccess 中声明域名白名单（慎用）。

app.tray：系统托盘（可选）

"tray": {
  "iconPath": "icons/32x32.png",   // 托盘图标路径（相对于 tauri 目录）
  "iconAsTemplate": true,          // macOS 模板图标
  "menuOnLeftClick": false
}

启用后，可以在 Rust 侧动态设置菜单。

3. bundle：安装包和分发配置

控制最终产物的格式、图标、升级器等。

"bundle": {
  "active": true,
  "targets": "all",                // 或者 ["msi", "nsis", "dmg", "deb", "appimage"]
  "icon": [
    "icons/32x32.png",
    "icons/128x128.png",
    "icons/icon.icns",            // macOS 专用
    "icons/icon.ico"              // Windows 专用
  ],
  "windows": {
    "wix": {},                     // MSI 配置（需要 WiX Toolset）
    "nsis": {
      "installMode": "currentUser",
      "languages": ["English", "SimpChinese"]
    }
  },
  "macOS": {
    "frameworks": [],
    "minimumSystemVersion": "10.14"
  },
  "linux": {
    "deb": {
      "depends": ["libwebkit2gtk-4.1-dev"]
    }
  },
  "createUpdaterArtifacts": true   // 生成更新所需的签名文件
}
  • active 设为 false 可以临时禁用打包（开发时无所谓）。
  • targets 可以字符串 "all" 或数组，精准控制输出格式。
  • 图标：必须提供各平台所需的特定格式和尺寸，Tauri CLI 在构建时会校验。

4. plugins：插件声明（Tauri v2）

声明应用所使用的官方或社区插件，比如窗口定制、单实例、全局快捷键等。

"plugins": {
  "shell": {
    "open": true                    // 允许用系统默认程序打开 URL/文件
  },
  "global-shortcut": {
    "shortcuts": []                 // 全局快捷键配置（空数组或不配置则启用插件）
  }
}
  • 所有需要启用系统 API 的插件必须在 plugins 中声明，否则 Rust 侧无法使用。
  • 大多数官方插件都已内建，只需按需开启权限。

5. 其他常用字段

  • productName（顶级字段）：应用名称，影响包名和注册表名称。
  • version：应用版本，和 Cargo.toml 的版本保持一致。
  • identifier：反向域名的唯一标识，例如 com.mycompany.myapp，用于系统级别识别。
  • build.distDir（旧版）已被 frontendDist 替代，注意你的 Tauri 版本。

配置文件示例摘要（最小可用）：

{
  "productName": "MyTool",
  "version": "0.1.0",
  "identifier": "com.example.mytool",
  "build": {
    "frontendDist": "../dist",
    "devUrl": "http://localhost:5173",
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev"
  },
  "app": {
    "windows": [
      {
        "title": "MyTool",
        "width": 900,
        "height": 600
      }
    ],
    "security": {
      "csp": null
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/icon.ico",
      "icons/icon.icns"
    ]
  }
}

实用建议

  • 配置分离：你可以把不同平台的配置放在 .tauri/tauri.prod.conf.json 等文件中，通过 CLI 参数 --config 加载，避免一个文件过于庞大。
  • 版本迁移：从 Tauri v1 升级到 v2 时，配置结构有较大变化（如 tauri 部分拆成 app 和 plugins），务必查看官方迁移指南。
  • 使用 JSON5：将文件扩展名改为 .json5，可以添加注释，便于团队协作。

掌握了 tauri.conf.json，你就掌握了 Tauri 项目的“方向盘”——从窗口行为到打包格式，从安全边界到插件权限，全部一目了然。