Tauri 的 tauri.conf.json 配置文件有哪些核心字段？

Tauri 是基于 Rust 的跨平台应用框架，用 Web 技术构建桌面端（及移动端）应用，打包体积比 Electron 小 90% 以上。tauri.conf.json 是 Tauri 项目的核心配置文件，位于 src-tauri/ 目录下，由 tauri init 命令生成。它控制构建流程、窗口行为、打包策略和插件集成，配置不当会导致编译失败或运行时异常。本文基于 Tauri v2 解析各核心字段。

build：构建命令与开发服务器

build 对象定义前端代码的编译和开发服务器参数：

• beforeDevCommand：执行 tauri dev 前运行的命令，通常用于启动前端开发服务器，如 "npm run dev" 或 "vite"。
• beforeBuildCommand：执行 tauri build 前运行的命令，用于编译前端产物，如 "npm run build" 或 "vite build"。
• devUrl：开发模式下前端开发服务器的地址，如 "http://localhost:5173"。Tauri 在开发时将 WebView 指向此地址。
• distDir：前端构建产物的目录路径，相对于 tauri.conf.json 所在目录，如 "../dist" 或 "../build"。

json
{
  "build": {
    "beforeDevCommand": "vite",
    "beforeBuildCommand": "vite build",
    "devUrl": "http://localhost:5173",
    "distDir": "../dist"
  }
}

如果使用 Vite，devUrl 的端口需与 vite.config.ts 中的 server.port 一致。distDir 必须指向包含 index.html 的目录，否则 Tauri 打包后会出现白屏。

app：应用标识与窗口

Tauri v2 将窗口等配置放在 app 对象下，不再使用顶层 windows 字段。

app.windows

windows 是数组，每个元素定义一个窗口实例：

• label：窗口标识符，必须为字母数字和连字符，用于在代码中通过 WebviewWindow.getByLabel() 获取窗口引用。
• title：窗口标题栏文本。
• url：窗口加载的页面，可以是相对路径（如 "settings.html"）或外部 URL。
• width / height：窗口初始尺寸（像素），默认 800 x 600。
• resizable：是否允许用户拖拽调整窗口大小，默认 true。
• fullscreen：是否以全屏模式启动，默认 false。
• decorations：是否显示操作系统原生标题栏和边框，设为 false 可实现无边框窗口。
• transparent：是否允许窗口背景透明，配合无边框窗口使用。

json
{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "My App",
        "width": 1024,
        "height": 768,
        "resizable": true,
        "decorations": true
      }
    ]
  }
}

创建多窗口应用时，每个窗口的 label 必须唯一。启动时默认只显示数组中的第一个窗口，其他窗口需要用 Rust 或 JS API 手动创建。

app.security

安全配置是 Tauri v2 的重要部分：

• csp：内容安全策略（Content-Security-Policy），控制 WebView 可加载的资源来源。
• capabilities：内联的能力声明（通常放在 src-tauri/capabilities/ 目录下单独管理更清晰）。

json
{
  "app": {
    "security": {
      "csp": "default-src 'self'; script-src 'self'"
    }
  }
}

bundle：打包与分发

bundle 控制应用如何打包成安装程序：

• active：布尔值，是否在 tauri build 时生成安装包。设为 false 则只编译可执行文件。
• icon：数组，指定各尺寸图标文件路径，用于生成不同平台的图标格式。Windows 需要 .ico，macOS 需要 .icns，Linux 需要 .png。
• publisher：发布者名称。
• copyright：版权信息。
• category：应用分类（macOS App Store 用），如 "DeveloperTool"、"Productivity"。
• windows / macOS / linux：各平台特定配置。

json
{
  "bundle": {
    "active": true,
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ],
    "publisher": "MyCompany",
    "category": "DeveloperTool"
  }
}

icon 必须是数组格式，不能是字符串。缺少对应平台的图标会导致打包失败。建议使用 tauri icon 命令从一张 1024x1024 的 PNG 源图自动生成所有尺寸。

plugins：插件配置

Tauri v2 的插件配置结构与 v1 不同，每个插件是一个独立的配置对象：

json
{
  "plugins": {
    "updater": {
      "pubkey": "YOUR_PUBLIC_KEY",
      "endpoints": ["https://example.com/updater/{{target}}/{{current_version}}"]
    },
    "sql": {
      "preload": {
        "db": "sqlite:myapp.db"
      }
    }
  }
}

Tauri v2 不再使用 v1 的 allowlist 白名单机制，而是引入了能力系统（Capabilities）。权限声明放在 src-tauri/capabilities/ 目录下的 JSON 文件中，与 tauri.conf.json 分离管理。

一个典型的能力文件 src-tauri/capabilities/default.json：

json
{
  "identifier": "default",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:read-files",
    "fs:write-files",
    "dialog:default",
    "shell:allow-open"
  ]
}

core:default 包含一组基础权限，开发者按需添加具体插件权限。这种分离设计比 v1 的集中式白名单更灵活，也更容易在 CI 中审计权限变更。

platform-override：平台特定配置

Tauri 支持平台级配置覆盖，创建独立文件：

• tauri.linux.conf.json
• tauri.windows.conf.json
• tauri.macos.conf.json
• tauri.android.conf.json
• tauri.ios.conf.json

这些文件与主配置按 JSON Merge Patch 规范合并。例如，仅在 Windows 上使用不同的窗口标题：

json
// tauri.windows.conf.json
{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "My App - Windows"
      }
    ]
  }
}

平台覆盖文件只需写差异部分，不需要重复主配置已有的字段。这在处理平台专属的打包参数（如 Windows 的 NSIS 安装器配置、macOS 的 Info.plist 字段）时非常实用。

配置格式与校验

tauri.conf.json 默认使用 JSON 格式，也支持 JSON5（需在 Cargo.toml 启用 config-json5 feature）和 TOML（需启用 config-toml feature）。主流 IDE 安装 Tauri 扩展后，可根据 Tauri 提供的 JSON Schema 实现自动补全和校验。

配置校验的常见问题：

• JSON 格式错误（末尾多余逗号、缺少引号）会导致 tauri dev 直接报错退出。
• 字段名拼写错误（如 beforeBuild 误写为 beforeBuildCommand 的 v1 写法）不会报错，但配置不会生效，排查困难。
• 使用 JSON5 或 TOML 格式时，需在 Cargo.toml 的 [build-dependencies] 和 [dependencies] 中同时启用对应 feature，否则编译失败。

常见配置错误与排查

1. devUrl 端口不匹配：前端开发服务器端口变了但配置没更新，tauri dev 打开后白屏。检查 devUrl 与实际服务器端口是否一致。
2. distDir 路径错误：指向了不含 index.html 的目录，打包后白屏。确认 distDir 指向包含入口 HTML 的目录。
3. 图标格式缺失：bundle.icon 数组中缺少某个平台所需的格式，打包时报错。使用 tauri icon 一次性生成所有格式。
4. 窗口 label 重复：多窗口配置中 label 相同会导致冲突，运行时只能创建一个实例。
5. 权限未声明：代码中调用了文件系统 API 但未在 capabilities 中添加 fs:read-files 等权限，运行时报权限拒绝错误。

掌握 tauri.conf.json 的核心字段和常见陷阱后，配置 Tauri 项目会顺畅很多。遇到不确定的字段，优先查阅 Tauri v2 官方配置文档，避免参考过时的 v1 教程导致配置无效。