Pake GitHub Actions 在线构建指南：无需本地环境，一条工作流出桌面应用安装包

本篇介绍如何使用 Pake 仓库内置的 Build App With Pake CLI 工作流，在 GitHub Actions 上免安装本地工具链、纯在线构建 Pake 桌面应用安装包。读完后你将掌握：如何 Fork 仓库并运行表单化工作流、工作流每个表单参数与 CLI 选项的对应关系、底层缓存机制为何让二次构建从 10–15 分钟缩短到约 5 分钟，以及构建产物（Artifacts）的命名规则与下载位置。

快速步骤

官方文档将在线构建流程概括为三步：Fork 仓库、运行工作流、下载应用（见 github-actions-usage_CN.md）。下面逐步拆解，并结合 工作流定义文件 说明每个环节实际发生了什么。

1. Fork 仓库

将 Pake 仓库 Fork 到自己的账号下。工作流运行在你 Fork 的仓库中，构建出的安装包会作为该仓库的 Artifacts 保留。

2. 运行工作流

1. 前往你 Fork 的仓库的 Actions 页面；
2. 选择 Build App With Pake CLI 工作流；
3. 填写表单（参数与 CLI 选项 相同）；
4. 点击 Run Workflow。

该工作流由 pake-cli.yaml 定义，仅在 workflow_dispatch（手动触发）时激活，表单输入即为工作流的 inputs。

表单参数说明

以下参数与工作流定义中的 inputs 一一对应，其中 url 与 name 为必填项：

参数	说明	默认值	必填
platform	构建平台，可选 windows-latest / macos-latest / ubuntu-24.04	macos-latest	是
url	要打包的网站地址	—	是
name	应用名称（Linux 平台要求小写）	—	是
icon	图标 URL，留空则自动抓取网站图标	空（自动获取）	否
width	窗口宽度（px）	1200	否
height	窗口高度（px）	780	否
min_width	窗口最小宽度（px）	无	否
min_height	窗口最小高度（px）	无	否
app_version	应用版本号	1.0.0	否
fullscreen	启动时是否全屏	false	否
hide_title_bar	沉浸式标题栏（仅 macOS 生效）	false	否
new_window	允许网站打开新窗口	false	否
multi_arch	构建 Universal 二进制（仅 macOS 生效）	false	否
targets	包格式，逗号分隔：deb、appimage、rpm、zst（仅 Linux 生效）	deb	否

这些表单字段最终会被拼装成 Pake CLI 的命令行参数。从 工作流源码 看，Linux/macOS 构建步骤会把非空输入逐个追加为 --icon、--width、--height、--min-width、--min-height、--app-version、--fullscreen、--hide-title-bar、--new-window、--multi-arch、--targets 等参数，然后执行 node dist/cli.js "${ARGS[@]}" 完成构建；Windows 侧有等价的 PowerShell 版本逻辑。因此工作流表单与 CLI 使用指南 中的选项语义完全一致——表单里没暴露的选项（如 --incognito、--debug、--camera 等）在本地 CLI 中仍可用，只是不在这套在线表单中提供。

3. 下载应用

• 绿色勾号 = 构建成功；
• 点击工作流运行名称查看详情；
• 在 Artifacts 部分下载应用安装包。

Artifacts 的命名由 上传步骤 决定，可按名称区分平台与格式：

Artifact 名称	平台	包格式
<name>-macOS	macOS	.dmg
<name>-Linux-deb	Linux	.deb
<name>-Linux-AppImage	Linux	.AppImage
<name>-Linux-rpm	Linux	.rpm
<name>-Linux-zst	Linux	.pkg.tar.zst
<name>-Windows	Windows	.msi

注意 retention-days: 3 的配置：所有 Artifact 仅保留 3 天，请在构建成功后及时下载，逾期将被 GitHub 自动清理。

4. 构建时间

• 首次运行：约 10–15 分钟（建立缓存）；
• 后续运行：约 5 分钟（使用缓存）；
• 缓存大小：完成时为 400–600MB。

工作流内部发生了什么

理解构建流程有助于排障。整个 build Job 的步骤链如下：

1. Checkout 仓库：actions/checkout@v6 拉取代码。
2. 安装 Rust：dtolnay/rust-toolchain@stable 安装稳定版工具链。
3. 设置 Node 环境：调用仓库内的复合 action setup-env（mode: build）。它会安装 pnpm 10.26.2 + Node 22、执行 pnpm install --frozen-lockfile、按平台配置 Rust 交叉编译 target（macOS 会额外添加 x86_64-apple-darwin 与 aarch64-apple-darwin 以支持 Universal 构建），并安装平台系统依赖——Linux 需要 WebKitGTK 相关库（libwebkit2gtk-4.1-dev、libjavascriptcoregtk-4.1-dev 等），Windows 需要 WiX Toolset 3.11（用于生成 .msi）。同时启用 sccache（通过 RUSTC_WRAPPER=sccache）与 swatinem/rust-cache 做编译加速。
4. 构建 CLI：执行 pnpm run cli:build，即 package.json 中定义的 cross-env NODE_ENV=production rollup -c，产出 dist/cli.js。
5. （Linux）配置 mold 链接器：rui314/setup-mold@v1，加速 Rust 链接阶段。
6. 恢复 Rust 缓存：actions/cache/restore 按 key ${{ runner.os }}-cargo-pake-${{ hashFiles('**/Cargo.lock') }} 恢复 ~/.cargo/ 下的二进制、registry 索引/缓存、git 依赖库，以及关键的 src-tauri/target/ 编译产物目录——这就是“二次构建快 3 倍”的来源。缓存 key 依赖 Cargo.lock 的哈希，依赖树不变时即可命中。
7. 构建应用：按前述参数拼装 CLI 命令，超时限制 25 分钟。
8. 上传 Artifact：按平台与格式分别上传，保留 3 天。
9. 保存 Rust 缓存：actions/cache/save，仅在缓存未命中（cache-hit != 'true'）时执行，把本次构建的 target/ 产物写回缓存，供下次运行复用。

从源码结构看，这套“restore + save 分离、以 cache-hit 为开关”的写法避免了并行运行时的缓存保存冲突，也解释了官方文档中“首次运行建立缓存、后续运行命中缓存”的时间差异。

实用提示

• 首次运行需要耐心等待，让缓存完全建立；
• 保持网络连接稳定：构建过程需要下载 Rust 依赖与系统包；
• 登录/考试类网站：当目标网站通过新窗口打开登录、考试或其他流程时，请启用表单中的 Allow sites to open new windows（对应 CLI 的 --new-window）。该选项能帮助依赖弹窗授权窗口的网站，但不能保证一定能在应用内完成登录——某些认证提供方（尤其是 Google）仍可能阻止在嵌入式 WebView 中完成认证；
• 构建失败时：删除缓存后重试。可删除 Actions 页面中对应平台前缀的缓存条目（key 形如 Linux-cargo-pake-* / macOS-cargo-pake-*），下一次运行会重新建立；
• 平台选择：ubuntu-24.04 上可通过 targets 组合出 deb、appimage、rpm、zst 等多种 Linux 包格式，各上传步骤均配置了 if-no-files-found: ignore，未产出的格式不会导致 Job 失败；
• 应用名称：Linux 上会自动转换为小写并用连字符连接（如 Google Translate → google-translate），表单中填写 name 时需注意这一点。

在自己的仓库中使用 Pake Action

如果你不想 Fork 整个仓库，而是希望在自己的项目 CI 中构建网页应用，可以把 Pake 作为 GitHub Action 引用（uses: tw93/Pake@v3）。Action 定义见仓库根目录的 action.yml，完整用法见 Pake Action 文档。

基础用法示例：

- name: Build Pake App
  uses: tw93/Pake@v3
  with:
    url: "https://example.com"
    name: "MyApp"

Action 的输入/输出如下：

参数	说明	必填	默认值
url	要打包的目标 URL	是	—
name	应用名称	是	—
output-dir	输出目录	否	dist
icon	自定义应用图标 URL/路径	否	—
width	窗口宽度	否	1200
height	窗口高度	否	780
debug	启用调试模式	否	false

输出 package-path 指向生成的安装包路径，可在后续步骤中继续处理。

从 action.yml 的实现看，该 composite action 分两步工作：先检查环境中是否已有 dist/cli.js 与 cargo，缺失时自动构建 CLI 并安装 Rust 工具链；随后把输入参数拼装成 CLI 命令执行，并在 src-tauri/target 下查找 .deb/.exe/.msi/.dmg 或 .app 目录，移动到 output-dir 后通过 GITHUB_OUTPUT 暴露 package-path。此外它对 output-dir 做了换行符注入校验，避免工作流参数污染文件系统。

多平台构建可借助矩阵策略，一次触发同时产出三大平台安装包：

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: tw93/Pake@v3
        with:
          url: "https://example.com"
          name: "CrossPlatformApp"

各平台的产物形态为：Linux 产出 .deb（Ubuntu runner）、macOS 产出 .app/.dmg、Windows 产出 .exe/.msi。

相关链接

• CLI 使用指南：完整的命令行参数参考，工作流表单选项的语义均以此为准；
• 高级用法：更多定制选项；
• 工作流源码：Build App With Pake CLI 的完整定义，可用于对照参数与上传逻辑；
• 环境准备复合 Action：节点/Rust/系统依赖的统一安装逻辑；
• Pake Action 文档：把 Pake 作为 Action 集成到自己项目 CI 的指南。