原生依赖安装策略¶

普通 pnpm install 仅安装当前操作系统和 CPU 的可选原生依赖。这适用于本地开发以及根项目的 CI 任务，包括使用 .github/actions/install-node-dependencies 的任务。具有自身工作区配置的移动和云项目则单独处理。

仓库中唯一的跨目标构建是 macOS：pnpm build:mac 和四个 macOS 打包工作流会从 arm64 runner 同时生成 x64 和 arm64 产物。在为其他架构打包之前，扩大 CPU 集合：

pnpm install:release

这会运行 pnpm install --frozen-lockfile --cpu=current,x64,arm64。它从不扩大 OS 集合：每个打包任务都在与其目标匹配的 runner 上运行，因此永远不需要跨 OS 安装。macOS 工作流直接传递 --cpu=current,x64,arm64；Windows 和 Linux 打包任务使用普通的主机专用 pnpm install --frozen-lockfile。在列表中保留 current 可在目标资源旁边保留主机构建工具。针对其他目标的安装本身不会交叉编译原生插件。

打包防护¶

electron-builder 仅对缺失的 extraResources 源记录警告并继续，因此如果没有检查，其他架构切片就会静默地以损坏状态发布。因此，config/electron-builder.config.cjs 中的 beforePack 会调用 config/packaged-runtime-node-modules.cjs 中的 assertPackagedNativeVariantsInstalled，当目标平台/架构的原生变体未安装时使构建失败：sherpa-onnx-*、@parcel/watcher-*，以及在 Windows 上的 node-gyp 插件 @vscode/windows-process-tree。错误会列出每个缺失的包，并给出合适的补救方法：其他架构的变体来自 pnpm install:release，Windows 插件则不是（见下文）。

Windows 打包需要 Windows 主机。@vscode/windows-process-tree 是一个 os: win32 npm 插件，因此它只会在匹配该条件的主机上安装；@orca/windows-registry 是一个工作区包，它在每台主机上都会链接，但其原生二进制文件仍只在 Windows 上编译。两者都只由 config/scripts/rebuild-native-deps.mjs 中仅限 Windows 的重建编译（pnpm-workspace.yaml 中的 allowBuilds 阻止 pnpm 本身为它们运行 node-gyp）。该防护只检查 @vscode/windows-process-tree，因为工作区链接在所有地方都存在，不能证明任何问题。pnpm install:release 在 macOS 或 Linux 上无济于事，因为它不会扩大 OS 集合。

检查已安装 Windows 插件及其打包闭包的测试在 Windows 上运行，因为这些依赖在那里是必需的。PR 的 Windows 通道明确包含它们。加载打包配置可以容忍缺失的 Windows 插件；只有 beforePack 会在它们安装之前拒绝 Windows 打包。补丁源断言、fixture 测试以及隔离的真实补丁安装测试继续在其他主机上运行。

现有检出¶

收窄的增量安装可能会留下先前安装的变体。停止使用此检出的开发进程，删除此检出的 node_modules，然后运行 pnpm install --frozen-lockfile 以获得新的主机安装。不要使用 --force：pnpm 12 文档说明，即使其 OS/CPU/libc 不匹配，它也会安装可选包。共享的 pnpm 下载存储是独立的；此更改不会清除它。

测量：macOS arm64，pnpm 12.0.0¶

于 2026-09-12 在两个全新的安装目录中测量，使用相同的包清单、lockfile、补丁文件和现有下载存储，两者均使用 --frozen-lockfile --ignore-scripts --offline。一个使用早先的宽泛策略（--os=current,darwin,linux,win32 --cpu=current,x64,arm64）；另一个使用 --os=current --cpu=current。数字是虚拟存储中的逻辑文件字节，不是唯一磁盘占用：pnpm 硬链接和 APFS 克隆可能共享存储。

两次试验中均不包含 Electron 下载和原生重建输出。单组热缓存计时对不能证明加速，且未测量 Linux/Windows 结果；不要将 macOS 数字表述为 CI 节省。