rust-npm-publish

Rust npm 发布

使用 optionalDependencies 平台包模式，将 Rust 二进制文件分发到 npm。

何时使用此技能

满足以下任一条件时启用：

• 将 Rust 二进制文件发布到 npm，或调试发布流水线故障
• 设置 publish.config.ts、bin.js 或平台包清单
• 管理工作区包与 Cargo.toml 之间的版本同步
• 使用 workspace:* 协议或 prepare/restore 脚本
• 存在匹配 *publish*、*platform*、*version* 或 *sync* 的脚本

决策树

What does the user need?

Setting up publishing for the first time?
  → The Pattern section + Configuration + Templates

Running the publish pipeline?
  → Publish Pipeline section
  → Full details: references/publish-pipeline.md

Adding a new platform?
  → Adding a New Platform section
  → Platform reference: references/platform-matrix.md

Version sync / bump?
  → Versioning section
  → Full strategy: references/version-strategy.md
  → workspace:* details: references/workspace-protocol.md

Debugging a failure?
  → references/troubleshooting.md

模式

@scope/my-tool                    ← main package (thin JS wrapper + bin.js)
├── optionalDependencies:
│   ├── @scope/my-tool-darwin-arm64   ← macOS ARM (M-series)
│   ├── @scope/my-tool-darwin-x64     ← macOS Intel
│   ├── @scope/my-tool-linux-x64      ← Linux x86_64
│   └── @scope/my-tool-windows-x64    ← Windows x86_64

每个平台包仅包含该目标平台的预编译二进制文件。npm 安装时只会安装与用户操作系统／CPU 匹配的包。

SWC、Turbopack、esbuild 等工具也采用相同的方法。

配置

每个仓库都提供一个 publish.config.ts（参见 examples/）：

export default {
  scope: '@myorg',
  binaries: [{ name: 'my-cli', scope: 'cli', cargoPackage: 'my-cli-rs' }],
  platforms: ['darwin-x64', 'darwin-arm64', 'linux-x64', 'windows-x64'],
  mainPackages: [{ path: 'packages/cli', name: 'my-cli' }],
  cargoWorkspace: 'Cargo.toml',
  repositoryUrl: 'https://github.com/myorg/my-project',
};

发布流水线

sync-versions → generate-manifests → add-platform-deps → copy-binaries
→ validate-binaries → prepare-publish → validate-workspace → publish-platforms
→ wait-propagation → publish-main → restore-packages

关键顺序：必须先发布并传播平台包，再发布主包，因为主包会通过 optionalDependencies 引用这些平台包。

分步详情请参见 references/publish-pipeline.md。

主包包装器（bin.js）

主 npm 包是一个精简的 JS 包装器——bin.js 用于解析平台二进制文件并启动它。模板请参见 templates/wrapper/。

要点：

• process.platform 返回 win32（而非 windows）——将 win32-x64 映射为 @scope/cli-windows-x64
• 使用 require.resolve('pkg/package.json') 查找平台包，然后读取 main 获取二进制文件名
• 使用 execFileSync，并转发 Rust 进程的退出码
• 主包没有 os／cpu 字段——它会在所有平台安装。只有平台包使用这些字段。

平台包清单

每个平台包都需要 os／cpu 字段和用于 chmod 的 postinstall.js：

{
  "name": "@scope/cli-darwin-arm64",
  "os": ["darwin"],
  "cpu": ["arm64"],
  "main": "my-cli"
}

平台矩阵

平台	Rust 目标	os	cpu	二进制扩展名
darwin-arm64	aarch64-apple-darwin	darwin	arm64	（无）
darwin-x64	x86_64-apple-darwin	darwin	x64	（无）
linux-x64	x86_64-unknown-linux-gnu	linux	x64	（无）
windows-x64	x86_64-pc-windows-msvc	win32	x64	.exe

有关添加新平台的信息，请参见 references/platform-matrix.md。

添加新平台

1. 将平台添加到 publish.config.ts 中的 platforms 数组
2. 添加 Rust 目标：rustup target add <target-triple>
3. 将平台添加到发布工作流的 CI 矩阵中
4. 重新生成清单：pnpm tsx scripts/generate-platform-manifests.ts

版本管理

根目录的 package.json 是唯一可信来源。切勿在其他位置手动编辑版本。

root package.json (version: "0.2.15")
  ├── packages/cli/package.json  → 0.2.15  (via sync-versions.ts)
  ├── Cargo.toml                 → 0.2.15
  └── platform-packages/*/      → 0.2.15  (via generate-manifests)

版本同步流程

npm version patch                     # Bump root: 0.2.15 → 0.2.16
pnpm tsx scripts/sync-versions.ts     # Propagate to all packages + Cargo.toml

开发构建

CI 计算版本：0.2.15 → 0.2.16-dev.{github_run_id}。使用 --tag dev 发布。安装命令：npm install my-cli@dev

开发构建时，Cargo.toml 保持基础版本（0.2.15）不变——Cargo 对预发布版本的处理方式与 npm 不同。

版本升级指南

变更	命令	示例
破坏性 API 变更	npm version major	1.0.0 → 2.0.0
新功能	npm version minor	0.2.0 → 0.3.0
Bug 修复	npm version patch	0.2.15 → 0.2.16
CI／测试	自动（CI）	0.2.15 → 0.2.16-dev.123

workspace:* 协议

pnpm 在开发期间使用 workspace:* 表示内部依赖。发布前替换，发布后恢复：

pnpm tsx scripts/prepare-publish.ts                  # Replace workspace:* → real versions
pnpm tsx scripts/validate-no-workspace-protocol.ts   # Safety gate
npm publish
pnpm tsx scripts/restore-packages.ts                 # Restore workspace:*

详情请参见 references/workspace-protocol.md。完整策略请参见 references/version-strategy.md。

故障排除速查

问题	可能原因	修复方法
Unsupported platform	bin.js 中缺少平台	添加平台键映射
npm 上找不到平台 pkg	注册表传播延迟	等待；检查发布日志
已发布的 pkg 中包含 workspace:*	未运行 prepare-publish	运行 prepare-publish.ts
二进制文件不可执行	未运行 postinstall	对二进制文件运行 chmod +x
版本不匹配	忘记同步	运行 sync-versions.ts

详细诊断请参阅references/troubleshooting.md。

模板

目录	内容
templates/scripts/	全部 11 个发布流水线脚本
templates/wrapper/	bin.js + 主包 package.json
examples/	使用项目中的真实 publish.config.ts

设置与激活

npx skills add -g onsager-ai/dev-skills --skill rust-npm-publish -a claude-code -y

满足以下条件时自动激活：存在 publish.config.ts，存在匹配 *publish* 或 *platform* 的脚本，或用户提及“发布”“平台包”或“版本同步”。