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

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

【免费下载链接】Pake🤱🏻 Turn any webpage into a desktop app with one command.项目地址: https://gitcode.com/GitHub_Trending/pa/Pake

本文基于 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:配置可以看到完整表单字段，下表逐一说明：

对照 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：

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 的输入与内置表单略有不同，字段更少：

输出为一个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时留意即可。

【免费下载链接】Pake🤱🏻 Turn any webpage into a desktop app with one command.项目地址: https://gitcode.com/GitHub_Trending/pa/Pake