3.3 tauri.conf.json：装配说明书逐项解读

工程在手，本节精读整个 Tauri 里性价比最高的一份文件：tauri.conf.json。它只有几十行，却决定窗口长相、前端来源、安全基线与出厂形态；更关键的是它在编译期被烧进二进制——读懂它，第 4 到第 8 章的每处配置改动你都知道去哪下手。调试与日志的入口也一并交代，本节是第 3 章的收束。

先建立读法：声明区与四个顶层段

v2 格式的配置文件顶层就四段，正好对应第 2 章图纸的四个零件：

图 3-3：tauri.conf.json 配置项地图

一份带批注的完整配置

{
  "productName": "travel-notes",
  "version": "0.1.0",
  "identifier": "com.example.travel-notes",
  "build": {
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:5173",
    "beforeBuildCommand": "npm run build",
    "frontendDist": "../dist"
  },
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "随身笔记",
        "width": 960,
        "height": 640,
        "minWidth": 720,
        "minHeight": 480,
        "resizable": true,
        "center": true
      }
    ],
    "security": {
      "csp": "default-src 'self'; connect-src 'self' ipc: http://ipc.localhost"
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": ["icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico"]
  }
}
​

自上而下过一遍关键项。identifier 是应用的法定身份：数据目录、系统设置里的卸载项、更新通道、商店上架全认它不认 productName，定下后别再改，改了等于换了个应用。build 段是壳与面板的接线板：dev 模式下 beforeDevCommand 负责起前端服务、devUrl 告诉 WebView 去哪加载；生产构建时 beforeBuildCommand 产出静态文件、frontendDist 指明产物目录，构建器把这批文件嵌进二进制。前端框架的端口号变了，改这里而不是改代码。app 段的 windows 数组声明初始窗口，label 是窗口的唯一代号——事件定向投递、权限按窗口生效都认这个标签；security 段放 CSP 基线，第 6 章展开。bundle 段是出厂设置，targets: "all" 表示当前平台能打的全打（第 8 章细讲）。

三个高频误配与症状对照

改了端口窗口白屏。 前端服务实际跑在 5174（5173 被占自动顺延），配置还指着 5173。症状是窗口打开但空白，控制台连不上资源。对策：端口写死在前端工具配置里，或改 devUrl 两边对齐。

identifier 用了下划线或大写。 打包阶段报"无效标识符"。规范是反向域名小写字母、数字、连字符与点。另一种死法是结尾用 .app——macOS 侧校验直接拒绝。

改了 windows 配置不生效。 你在 dev 模式外改文件却没重启进程，或改的是运行时属性对应的初值而代码里又有 set_title 覆盖。判别法：配置管"出厂初值"，代码管"运行时行为"，两边都查。

调试与日志：三个入口

备料阶段的最后一课是知道往哪看。前端调试：dev 模式窗口里右键选"检查元素"，即 WebView 开发者工具，与网页调试同构；生产包默认关闭 devtools，需要时在 Cargo.toml 给 tauri 加 devtools 特性重新编译。Rust 调试：println! 与 eprintln! 的输出在跑 dev 的终端里直接可见；上调试器则在 IDE 里把 src-tauri 当 Rust 项目起会话，断点行为与普通 Rust 程序一致。日志进文件：官方 log 插件把日志分级写进系统日志与应用目录，生产环境排查全靠它，第 7 章装插件时一并配置。

平台差异配置：同一份说明书的分册

三平台总有 differ 的需求——窗口在 macOS 要隐藏标题栏、Windows 要指定 WebView2 引导方式、Linux 要补打包依赖。做法不是在主配置里写条件判断，而是平台分册：与 tauri.conf.json 并排放置按平台命名的合并配置文件（如 tauri.macos.conf.json、tauri.windows.conf.json），构建时按当前平台自动合并进主配置。分册里只写该平台差异的段落，主配置保持三端公共的部分。这个拆法让"哪段配置只影响哪个平台"一目了然，比注释里写"仅 mac 生效"可靠得多——配置合并是构建器执行的事实，注释只是愿望。

编辑体验也值得配好：配置支持 JSON 校验，给编辑器装上对应 schema 关联后，字段名写错、类型不符会在保存时就划红线——比打包阶段报错早发现几个小时。团队里把这份 schema 关联写进编辑器工作区配置，新人就不会再犯"把 width 写成 windth 还奇怪为什么不生效"的错。

配置演进的读法：从 diff 里学新版本

Tauri 版本升级时配置结构偶有调整，最快的跟进方式是读官方迁移说明里的配置对照，再用工具校验自己的配置文件——校验器会逐项指出失效字段与新写法。养成一个习惯：升级框架版本后先跑一次构建，配置类报错集中修完再动代码，能避免"配置没跟上、代码背黑锅"的冤案。3.2 首跑排错时强调先读终端输出，同样的原则在版本升级时再兑现一遍。

本节要点回顾

• 四段一身份：产品身份、build、app、bundle 四段，加段外的 identifier；
• identifier 法定不可改：数据目录、更新、商店全认它，命名用小写反向域名；
• build 段是接线板：devUrl 接开发服务，frontendDist 接构建产物，端口对不上就白屏；
• 配置管初值、代码管运行时：改了 conf 重启或重构建生效；
• 调试三入口：WebView 工具、终端输出、log 插件进文件。

第 3 章收工：环境齐、工程立、说明书通读。下一章进装配车间第一道工序——装壳：前端接入、invoke 通信、窗口定制。