Pake GitHub Actions 构建指南：免本地环境在线打包网页桌面应用

本文基于 Pake 仓库的官方文档 GitHub Actions 使用指南 展开，讲解如何不安装任何本地开发工具，直接在 GitHub Actions 云端用一条工作流把任意网页打包成 Windows / macOS / Linux 桌面应用。读完本文，你将掌握完整的 Fork-触发-下载产物三步流程、工作表单的每个参数与底层 CLI 选项的对应关系、产物按平台拆分的具体规则，以及缓存机制对构建时长的影响；如果你还想在自己的仓库里以 uses 的方式复用 Pake，文末会给出基于 action.yml 的独立 Action 用法。

一、方案定位：为什么用 GitHub Actions 打包

GitHub Actions 使用指南 开宗明义：Build Pake apps online without installing development tools locally——无需本地安装 Rust、Node.js 等开发工具链，把整个编译打包过程放到 GitHub 的云端 Runner 上完成。

这与本地 CLI 方式形成互补：

• 本地方式适合日常开发调试，完整命令参考见 CLI 使用文档；
• 云端方式适合一次性出包、无开发环境的机器（比如只有浏览器的环境），或者希望复现官方构建环境（Node 22 + stable Rust 工具链 + 官方系统依赖集）的场景。

需要说明的是，云端构建本质上是把仓库中 pake-cli 的完整构建链搬到了 Runner 上执行：先构建出 dist/cli.js，再以 node dist/cli.js [url] [options] 的形式运行，参数语义与 CLI 选项表 完全一致。

二、快速上手：Fork、Run Workflow、Download App

1. Fork 仓库

在 GitHub 上 Fork 本仓库（Fork 时选择本项目的 Fork 入口即可）。Fork 之后你就拥有了完整的 .github/workflows/ 目录，其中 pake-cli.yaml 就是文档中提到的那个可手动触发的工作流。

2. 运行工作流

1. 进入你 Fork 仓库的 Actions 标签页；
2. 选择名为 Build App With Pake CLI 的工作流；
3. 在 Run workflow 表单中填写参数（与 CLI options 同名同义）；
4. 点击 Run Workflow 启动构建。

该工作流通过 workflow_dispatch 触发，即只能手动运行，不会在 push/PR 时自动执行。从 pake-cli.yaml 的 on: 配置可以看到完整表单字段，下表逐一说明：

参数	类型	默认值	说明
platform	choice	macos-latest	构建平台，可选 windows-latest / macos-latest / ubuntu-24.04，同时决定 Runner 类型和产物格式
url	必填	无	要打包的网站 URL
name	必填	无	应用名（Linux 下建议使用小写，因为 CLI 会把多词名称转成连字符小写形式）
icon	可选	空	图标 URL；留空时 CLI 自动抓取网站图标
width	可选	1200	窗口宽度（px）
height	可选	780	窗口高度（px）
min_width	可选	空	窗口最小宽度（px），对应 CLI 的 --min-width
min_height	可选	空	窗口最小高度（px），对应 CLI 的 --min-height
app_version	可选	1.0.0	打包应用的版本号，对应 --app-version
fullscreen	boolean	false	启动时进入全屏，对应 --fullscreen
hide_title_bar	boolean	false	沉浸式标题栏（仅 macOS 生效），对应 --hide-title-bar
new_window	boolean	false	允许网站打开新窗口，对应 --new-window
multi_arch	boolean	false	构建 macOS 通用二进制（Intel + Apple Silicon），对应 --multi-arch
targets	可选	deb	Linux 包格式，逗号分隔：deb,appimage,rpm,zst，对应 --targets

对照 pake-cli.yaml 的 “Build App (Linux/macOS)” 步骤可以看到，表单字段并不是直接透传，而是逐项拼接到 ARGS 数组里再交给 node dist/cli.js "${ARGS[@]}" 执行；空值参数（如 icon）会被自动跳过，布尔值按 "true" 字符串判断后追加 --fullscreen / --hide-title-bar / --new-window / --multi-arch 等开关。Windows 分支则用 PowerShell 以相同语义拼装参数（见 pake-cli.yaml），构建结束后会执行 git checkout -- src-tauri/Cargo.lock 还原被 Tauri 修改的锁文件，避免污染后续缓存步骤的判定。

3. 下载产物

• 工作流显示绿色对勾 = 构建成功；
• 点击工作流名称进入运行详情页；
• 在 Artifacts 区域找到并下载你的应用安装包。

产物并非一个大包，而是按平台拆成多个独立 artifact（见 pake-cli.yaml 的上传步骤），命名规则为 <name>-<平台/格式>，保留期 retention-days: 3：

平台	Artifact 名称	上传路径	说明
macOS	<name>-macOS	<name>.dmg	固定产出 DMG
Linux	<name>-Linux-deb	<name>.deb	找不到文件时静默跳过（if-no-files-found: ignore）
Linux	<name>-Linux-AppImage	<name>.AppImage	同上
Linux	<name>-Linux-rpm	<name>.rpm	同上
Linux	<name>-Linux-zst	<name>-*.pkg.tar.zst	Arch 系包，通配匹配
Windows	<name>-Windows	<name>.msi	固定产出 MSI

Linux 侧之所以是四个独立上传步骤且带 ignore，是因为 targets 输入允许多选格式，未选中的格式不产出文件，跳过上传即可；而 targets 仅在 runner.os == "Linux" 时才会被拼入 CLI 参数（pake-cli.yaml），Windows/macOS 分支分别固定产出 MSI/DMG。

4. 构建时长预期

• 首次运行：约 10～15 分钟（需要完整建立缓存）；
• 后续运行：约 5 分钟（命中缓存）；
• 完整缓存体积：约 400～600 MB。

这个时长差异来自工作流里的多层缓存设计，下面一节会具体拆解。

三、工作流内部机制：一次云端构建到底做了什么

官方文档只给出“点击 Run Workflow”这一层，真正的工程细节藏在 pake-cli.yaml 与它调用的复合 Action 里。结合源码可以还原出完整的构建调用链：

1. 环境准备

• Checkout：actions/checkout@v6 拉取仓库；
• Rust：dtolnay/rust-toolchain@stable 安装 stable 工具链；
• Node + 系统依赖：调用仓库自带的复合 Action setup-env，mode: build 模式下它会按平台完成一整套准备工作：
  • pnpm 10.26.2 + Node 22，并执行 pnpm install --frozen-lockfile；
  • Linux 上安装 Tauri/WebKitGTK 所需的系统库（libwebkit2gtk-4.1-dev、libgtk-3-dev 等，见 setup-env）；
  • Windows 上安装并缓存 WiX Toolset v3.11（MSI 打包必需）；
  • macOS 上额外 rustup target add x86_64-apple-darwin aarch64-apple-darwin 以支持 multi_arch 通用二进制；
  • 启用 sccache（RUSTC_WRAPPER=sccache）加速 Rust 编译。

2. 构建 CLI 本体

pnpm run cli:build 通过 rollup 把源码打包为 dist/cli.js（对应 package.json 中的 cli:build 脚本）。后续的打包动作全部由这个产物驱动，而不是直接调用某个独立二进制——这与仓库测试脚本 PAKE_CREATE_APP=1 node tests/index.js 的运行方式一致。

3. Rust 编译缓存（三层）

构建时长“首跑 10-15 分钟、后续约 5 分钟”的体验，主要依赖 pake-cli.yaml 中的缓存组合：

1. actions/cache/restore + save：手动缓存 ~/.cargo/bin、registry index/cache、src-tauri/target/ 编译产物，缓存键为 ${{ runner.os }}-cargo-pake-${{ hashFiles('**/Cargo.lock') }}——即按操作系统 + Cargo.lock 哈希分桶，依赖不变则整包命中；
2. swatinem/rust-cache（在 setup-env 中，workspaces: "src-tauri -> target"，shared-key: pake-<OS>）：跨工作流共享的增量编译缓存；
3. sccache：编译级缓存，进一步压缩重复构建时间。

这也解释了文档 Tips 里“首次运行要耐心等待缓存建完整”“构建失败可删缓存重试”两条建议：缓存键绑定 Cargo.lock 的哈希，若某次构建在中途污染了 src-tauri/target/，删除对应缓存后重跑即可恢复。

4. 平台差异化构建

• Linux 分支使用 bash 拼装参数并调用 node dist/cli.js，且仅在 Linux 上启用 mold 链接器（rui314/setup-mold@v1）加速链接；
• 每个构建步骤均设置 timeout-minutes: 25 作为硬性超时；
• Windows 分支结束后执行 git checkout -- src-tauri/Cargo.lock 还原锁文件，保证下一次缓存键计算不受影响。

四、实战建议（Tips）

这些建议直接继承自 官方指南：

1. 首次运行要耐心：让缓存完整建立后再评估后续运行速度；
2. 保持稳定的网络连接：构建过程需要下载 Rust crates、npm 依赖和系统包；
3. 需要弹窗登录的站点，记得开启 new_window：当网站在登录、考试等流程中会在独立窗口中打开时，把表单中的 Allow sites to open new windows 设为 true。注意这只是“允许新窗口”，并不能保证所有提供方的嵌入式 WebView 登录都能成功（参见 CLI 文档对 --new-window 的说明）；
4. 构建失败时删除缓存重试：在 Actions 运行页删除该平台的缓存条目（或等待缓存键因 Cargo.lock 变化而失效）后重新 Run Workflow；
5. Linux 下应用名建议用小写，工作流表单对 name 的描述也标注了 lowercase for Linux，这与 CLI 的多词名称处理规则（Linux 自动转小写连字符）保持一致。

五、进阶：把 Pake 当作 GitHub Action 在自己的仓库中使用

除了 Fork 后使用内置工作流，仓库根目录还提供了一个 composite Action 定义 action.yml（配合说明文档 Pake Action），可以 uses: <your-fork>/... 的方式引入自己的工作流。该 Action 的输入与内置表单略有不同，字段更少：

输入	必填	默认值	说明
url	是	无	目标 URL
name	是	无	应用名
output-dir	否	dist	产物输出目录
icon	否	空	自定义图标 URL 或路径
width	否	1200	窗口宽度
height	否	780	窗口高度
debug	否	false	调试模式

输出为一个 package-path，指向生成的安装包路径。

从 action.yml 的执行逻辑看，它由两个 composite 步骤组成：

1. Setup Environment：npm install 安装依赖；若 dist/cli.js 不存在则 npm run cli:build 构建 CLI；若 cargo 不存在则通过 rustup 脚本静默安装并写入 $GITHUB_PATH——这意味着即使宿主工作流没有预装 Rust 也能跑通；
2. Build Pake App：把输入映射为环境变量并拼成 CLI 参数（含 --name / --icon / --width / --height / --debug），设置 PAKE_CREATE_APP=1（macOS 下强制产出 .app 以避免 DMG 挂载交互），执行 node dist/cli.js，然后在 src-tauri/target 下依次查找 *.deb / *.exe / *.msi / *.dmg 文件，找不到再回退查找 .app 目录，最后移动到 output-dir 并通过 $GITHUB_OUTPUT 写回 package-path。

其中还有两处安全细节值得注意：脚本在入口处校验 INPUT_OUTPUT_DIR 与最终 PACKAGE_PATH 不得包含换行符（防止通过参数注入多行 GITHUB_OUTPUT），并在使用 printf '%q' 打印实际执行的命令，便于排查。多平台产物可以用 matrix 策略同时构建（参考 docs/pake-action.md 的示例：runs-on: ${{ matrix.os }} 覆盖 ubuntu / macos / windows）。

六、延伸阅读

• CLI 使用文档：完整命令行参数参考，云端表单参数的完整语义以此为准；
• 进阶使用：注入自定义 CSS/JS 等定制能力；
• Pake Action：以 Action 形式复用到自有项目的示例；
• 工作流源码：pake-cli.yaml（内置手动触发工作流）、setup-env（环境准备复合 Action）、action.yml（对外发布的 composite Action）。

适用前提小结：云端构建依赖 GitHub 提供的 Runner 额度与网络环境，产物保留 3 天需及时下载；multi_arch 仅对 macOS 有效，targets 仅对 Linux 有效，hide_title_bar 仅对 macOS 生效——这些平台限制与 CLI 行为一致，在表单里选择对应 platform 时留意即可。