跨平台二进制构建与发布流水线
跨平台二进制构建与发布流水线
学习目标
- 理解 11 个平台变体的 optionalDependencies 分发模式
- 掌握 postinstall 脚本的自动解压和路径设置
- 识别 musl vs glibc 的兼容性陷阱
项目实践
11 个平台变体
Oh-My-OpenAgent 通过 optionalDependencies 分发预编译二进制：
| 平台变体 | 架构 | 说明 |
|---|---|---|
oh-my-opencode-darwin-arm64 | Apple Silicon | M1/M2/M3 Mac |
oh-my-opencode-darwin-x64 | Intel Mac | |
oh-my-opencode-darwin-x64-baseline | Intel Mac (旧 CPU) | 不支持 AVX2 的旧 CPU |
oh-my-opencode-linux-arm64 | ARM64 Linux | 包括 glibc 和 musl |
oh-my-opencode-linux-arm64-musl | ARM64 Alpine Linux | musl libc |
oh-my-opencode-linux-x64 | x64 Linux (glibc) | |
oh-my-opencode-linux-x64-baseline | x64 Linux (旧 CPU) | 不支持 AVX2 |
oh-my-opencode-linux-x64-musl | x64 Alpine Linux | |
oh-my-opencode-linux-x64-musl-baseline | x64 Alpine (旧 CPU) | |
oh-my-opencode-windows-x64 | Windows x64 | |
oh-my-opencode-windows-x64-baseline | Windows (旧 CPU) |
optionalDependencies 按需安装
npm 的 optionalDependencies 机制确保用户只下载自己平台的包：
{ "optionalDependencies": { "oh-my-opencode-darwin-arm64": "4.5.1", "oh-my-opencode-linux-x64": "4.5.1", // ... 其他平台 }}安装时，npm/npm/yarn 只下载与当前操作系统和架构匹配的包。
构建流程
# 编译原生二进制bun run script/build-binaries.ts
# 输出到 packages/oh-my-opencode-*/# 每个平台一个目录postinstall 脚本
postinstall.mjs 在 npm install 后自动执行：
- 检测当前平台（
process.platform+process.arch） - 从对应的 optionalDependency 包中解压二进制
- 设置可执行权限
- 验证二进制完整性
Baseline 变体
部分平台提供 -baseline 变体，针对不支持 AVX2 等高级 CPU 指令集的旧硬件：
- Bun 编译时通过 CPU 特性标志控制
- 用户无需手动选择，npm 按平台自动安装
问题与规避
musl vs glibc 兼容性
问题：在 Alpine Linux（musl）上安装 glibc 二进制文件会失败。
规避：为 musl 提供独立平台变体（linux-x64-musl、linux-arm64-musl），npm 按 process.platform 和 libc 类型自动选择。
postinstall 失败
问题：某些环境下 postinstall 脚本无执行权限或被安全策略阻止。
规避：
- postinstall 失败时记录警告而非终止安装
- 提供手动安装二进制的 fallback 指南
doctor命令检测二进制安装状态
设计取舍
optionalDependencies vs 单包 + 运行时下载
| 方案 | 优势 | 代价 |
|---|---|---|
| optionalDependencies | 安装即完成、无需额外下载 | 包列表长（11 个）、npm install 略慢 |
| 单包 + 运行时下载 | 包列表简洁 | 首次运行需要联网下载、可能失败 |
Oh-My-OpenAgent 的选择：optionalDependencies，因为用户期望 npm install 后直接使用，无需首次运行时额外下载。