企业官网建设流程全解析

如何让脚本或 AI Agent 用 --json 与 --config 稳定调用 Pake 打包？

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

当脚本或 AI Agent 需要自动完成 Pake 打包——把一个 URL、本地 HTML 文件或静态构建目录变成 macOS / Windows / Linux 桌面安装器时，交互式提示和人工阅读终端输出都不可靠。Pake CLI 为此提供了两个面向自动化的特性：--config从声明式 JSON 配置文件加载参数（未知字段、错误类型、越界数值都会快速失败），--json把所有日志移到 stderr 并让 stdout 恰好输出一个可解析的 JSON 结果对象。本文按仓库文档说明，给出安装 CLI、编写配置、脚本化调用，以及用退出码与 JSON 结果判定成败的完整路径。

1. 准备环境与安装 CLI

docs/cli-usage.md 列出的前置条件：

• Node.js ≥20.0.0，推荐 22.0 或更高（llms.txt中给出的版本线为 20.9+）；
• Rust ≥1.85.0，缺失时 CLI 会自动安装；
• macOS / Linux 上依赖系统的curl、wget、file、tar用于依赖管理。

安装命令（任选其一）：

pnpm install -g pake-cli # 或 npm install -g pake-cli

遇到权限问题时，文档给出两条替代路径：用npx免全局安装运行，或永久修改 npm 全局前缀：

# 方式一：免全局安装（[url] [options] 为占位符，替换为实际参数） npx pake-cli [url] [options] # 方式二：永久修改 npm 全局安装前缀 npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

注意：方式二会修改当前用户 shell 的全局 npm 前缀与 shell 配置文件，影响所有全局安装的 npm 包，确认遇到权限问题后再执行。

安装后用文档中列出的版本选项验证：

pake --version

2. 编写声明式配置文件 app.json

--config从 JSON 配置文件加载参数，字段为 CLI 选项的 camelCase 名称，另外支持url。完整字段、类型与取值范围见 schema/pake.schema.json（JSON Schema draft-07，additionalProperties: false）。一个最小配置（文档中的示例）：

{ "url": "https://example.com", "name": "MyApp", "width": 1280, "hideTitleBar": true }

文档示例中还展示了可选的$schema字段，指向 Pake 配置 schema（该 schema 文件即本仓库的 schema/pake.schema.json），用于编辑器校验，不影响打包行为。

对自动化调用而言，下面这些规则决定了失败是否会提前暴露，均来自文档与仓库测试 tests/unit/config-file.test.ts 的断言：

• 显式 CLI 参数永远覆盖配置字段，脚本可以不改文件做一次性覆写；
• 未知字段快速失败，报错会指明字段名，例如name拼成nmae会得到Unknown config field "nmae"；
• 类型错误按期望类型报错，例如basicAuth写成字符串时报"basicAuth" must be of type boolean；
• 越界数值被拒绝，例如zoom允许 50–200，zoom: 1000报"zoom" must be a finite number (50-200)，width: -5（下限 0）同样失败；
• 配置文件不存在或 JSON 损坏时，以INVALID_INPUT错误快速失败；
• 调用类标志--json、--config、--version仅限命令行使用，写进配置文件（如"json": true）会被拒绝；
• 相对路径的url相对于当前工作目录解析，而不是配置文件所在目录。脚本中应确保启动目录符合预期，或在配置里写绝对路径；
• 位置参数形式的url会覆盖配置中的url字段（schema 中的描述）。

这些快速失败意味着配置写错时脚本得到的是退出码 2（INVALID_INPUT），而不是一个参数错误的包——这正是用--config而不是在脚本里拼接一长串 flag 的主要收益。

3. 在脚本中调用

主路径就是一条命令：

pake --config app.json --json

--json的行为契约（docs 与llms.txt的 Agent contract 一致）：

• stdout 恰好输出一个 JSON 结果对象。仓库测试 tests/unit/json-output.test.ts 断言 stdout 只有一次写入、内容可被JSON.parse解析且以换行结尾；
• 所有日志走 stderr，stdout 可以直接管道给解析器；
• 交互式提示被禁用；当 stdin 不是 TTY 时提示同样不会发生，Agent 不会因等待输入而挂起。

需要临时覆写某个参数时，直接在命令行追加显式参数即可，例如把窗口宽度改成 1400：

pake --config app.json --width 1400 --json

由于“显式 CLI 参数永远覆盖配置字段”，覆写是确定性的。全部选项可用pake --help查看，完整参考见 docs/cli-usage.md。

4. 结果验证：JSON 结果与退出码

成功时 stdout 的 JSON 结构（下面为文档示例，其中的path、sizeBytes为文档中的示例值，不是固定预期）：

{ "ok": true, "name": "MyApp", "platform": "darwin", "arch": "arm64", "outputs": [{ "path": "/abs/MyApp.dmg", "sizeBytes": 5242880, "format": "dmg" }], "warnings": [], "error": null }

失败时error携带{code, message, hint}，其中hint说明修复方式（文档示例）：

{ "ok": false, "error": { "code": "ENV_MISSING", "message": "...", "hint": "..." } }

退出码（docs 原文）：

错误码集合为INVALID_INPUT、ENV_MISSING、BUILD_FAILED、UNEXPECTED，外加NETWORK（保留；当前版本把网络失败归到阶段码下报告，例如ENV_MISSING或BUILD_FAILED）。

脚本可以据此断言：退出码 0 表示成功；非 0 时解析 stdout 的 JSON，按error.code分支处理，并把error.hint记入日志或交给 Agent 自行修复。

Linux 多目标构建的特殊情况：当使用--targets deb,appimage这类多格式构建时，ok可以为 true 而outputs少于请求的格式——某个目标失败而其他成功时，失败目标出现在warnings中，不算整体失败。因此请求多个格式时，脚本应对照outputs[].format与请求的格式列表核验，而不是假设一一对应。

5. 平台注意点与限制

• macOS 默认产出 DMG 安装器；自动化测试若需要.appbundle 以避免用户交互，设置环境变量PAKE_CREATE_APP=1（docs 中的说明）。
• 首次打包会因环境配置耗时较长，脚本的超时设置应预留余量（docs 原文提醒 first packaging might take some time）。
• 输出格式由--targets指定：Linux 为deb/appimage/rpm/zst及对应-arm64变体，Windows 为x64/arm64，macOS 为intel/apple/universal/app/dmg，默认取平台安装器格式。
• 该契约由仓库测试固化：tests/unit/json-output.test.ts 断言退出码映射、stderr 日志路由与单行 JSON 输出，tests/unit/config-file.test.ts 断言配置校验行为。升级 pake-cli 版本后，可参考这两个测试确认契约是否变化。

如果还需要确认某个字段是否可用，以pake --help的输出和 docs/cli-usage.md 为准；配置字段的类型与范围以 schema/pake.schema.json 为准。

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