8.1 构建流水线：从源码到安装包

交付日第一关：点下构建命令之后到底发生了什么。本节把 tauri build 拆成四个阶段，讲每阶段的输入输出与高频报错，再补两块交付工程——静态资源如何被嵌入二进制、CI 如何一次产出三平台安装包。读完本节，流水线报错你能按阶段归因，出包不再是碰运气。

四阶段拆解

npm run tauri build 依次经过四个阶段，每一阶段出错的症状与查法不同：

阶段一：执行构建前命令。 读配置 build 段的 beforeBuildCommand，跑前端生产构建（如 Vite 产出 dist 目录）。报错全是前端报错——TS 类型错、依赖缺失、环境变量没配。验证方法：单独跑该命令能否通过。

阶段二：Rust release 编译。 cargo 以 release 配置编译 src-tauri，链接你登记的全部插件与代码。首次最慢（全量优化编译），报错在此阶段的特征是 cargo 风格——缺特性、版本冲突、链接失败。3.1 的平台依赖没备齐，也多在这阶段发作。

阶段三：资源嵌入与上下文生成。 generate_context 宏在编译期读配置、图标与前端产物，资源被压缩嵌入二进制。此阶段的报错极好认：图标缺失或尺寸不对、frontendDist 指向的目录不存在、配置字段写错——都直接点名文件。前端产物必须是静态可用的：路径引用错（绝对路径、大小写错）在这一阶段不报错，而是运行时白屏——这类"构建成功但打开空白"最迷惑人，查法是本地起静态服务打开 dist 目录验证。

阶段四：打包器出安装包。 按平台调用打包器（Windows 的 WiX 或 NSIS、macOS 的 bundle 工具、Linux 的 AppImage 与 deb 工具），产出安装包与更新产物。签名（6.4）在此阶段执行；报错多为证书、公证与打包器自身的配置问题。

图 8-1：构建流水线四阶段

资源嵌入与自定义协议的关系

阶段三把前端产物嵌进二进制后，生产环境里壳怎么"加载"这些文件？答案是自定义协议：Tauri 在运行时注册一个应用内协议，WebView 用它请求嵌入资源——于是页面源是一个受控的虚拟源，CSP 的 'self' 指的就是它。这带来两个推论：其一，应用不依赖文件系统上的前端文件，安装目录里没有散装网页，一切都在二进制里；其二，前端代码里的资源引用要用相对路径——构建器的 base 配置没设对（Vite 要设相对基路径），资源在协议下解析不到，症状又是白屏。阶段三的白屏问题十有八九是 base 配置，第二处就是绝对路径引用。

CI：一次提交出三平台包

三平台安装包要在各自系统上构建（交叉编译桌面应用不现实），标准解法是 CI 矩阵：三个虚拟机环境各跑一份构建。社区维护的现成 Action 封装了"装依赖、构建、签名、发发布"全套流程，配置骨架：

# 思路示意（非完整可运行文件），实际以所用 Action 的文档为准
jobs:
  build:
    strategy:
      matrix:
        include:
          - { os: windows-latest, target: x86_64-pc-windows-msvc }
          - { os: macos-14, target: aarch64-apple-darwin }     # Apple Silicon
          - { os: macos-13, target: x86_64-apple-darwin }      # Intel
          - { os: ubuntu-22.04, target: x86_64-unknown-linux-gnu }
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm run tauri build        # 或调用 tauri-action 顺带发布
        env:
          # 签名与公证凭据经仓库密钥注入，绝不写进文件
          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
​

配置要点四条：macOS 出双架构——Apple Silicon 与 Intel 各一个 runner（或用 universal 目标合并，包更大但单包通用）；Linux runner 上补装 3.1 的 WebKitGTK 依赖（CI 系统是裸的，备料清单在云上也要走一遍）；凭据全走密钥注入——签名证书、公证账号、更新密钥都经 CI 的 secrets 机制进环境变量；产物上传与发布——把安装包与更新产物（8.3 的清单文件）一并归档，发布动作与更新清单更新放同一作业，避免"包发了、清单没更"的断链。

一次真实故障的定位走查

阶段归因的价值要用故障验证。走一遍随身笔记第十四次发版时的真实卡壳：本地 build 一路绿灯，CI 的 Linux runner 上却反复失败，日志末尾是一长串链接错误，提及若干未定义的引用。按四阶段定位法走：症状是 cargo 风格的链接错——归阶段二；阶段二的差异只在 CI 与本地之间——那么问题是"本地链接得着、CI 链接不着"的东西，十有八九是系统库。核对备料清单：CI 镜像里 WebKitGTK 的开发包版本比本地旧，而某个插件的依赖声明要求更新版本。在 CI 作业里补一步"按清单安装指定版本的系统依赖"，故障消失。

这次排查的解读有两层。表层教训是CI 环境是 3.1 备料清单的复考场——本地装过的东西容易在云上被想当然，备料清单要写成 CI 可执行的脚本而不是文档。深层教训是日志要按阶段读：链接错误的文本本身毫无指向（几十行未定义引用），但"它出现在阶段二"这一位置信息立刻把搜索空间从全流水线压缩到编译链接环节。日常练习方法很简单：每次构建失败，先在日志里找阶段边界（前一段是哪个命令的输出），再读错误——这个习惯能把平均排查时间从小时级压到分钟级。

本节要点回顾

• 四阶段归因：前端错、链接错、嵌入错、签名错，各有查法；
• 自定义协议供资源：产物嵌入二进制，页面源受控，CSP 的 self 指它；
• 白屏双查：Vite 相对 base、绝对路径引用，十有八九在此；
• CI 矩阵三平台：macOS 双架构、Linux 补依赖、凭据走密钥；
• 发布与清单同作业：防"包发了清单没更"的断链。

流水线通了。下一关细看出包本身：三平台安装格式、体积账与瘦身清单。