rust-node-ci

Rust+Node.js CI/CD

适用于 Rust+Node.js 混合项目的 GitHub Actions 工作流和复合操作。

何时使用此技能

符合以下任一条件时启用：

• 在同时包含 Cargo.toml 和 package.json 的仓库中处理 .github/workflows/
• 设置、修复或扩展 CI/CD 流水线
• 将复合操作安装到项目中
• 用户提到“CI”“工作流”“GitHub Actions”“交叉构建”或“构件”

决策树

What does the user need?

Set up CI from scratch?
  → Copy templates/workflows/ into .github/workflows/
  → Install composite actions from templates/actions/ into .github/actions/
  → Customize platform matrix for your targets

Fix a failing CI job?
  → Node job → CI Jobs section
  → Rust build/cross-compile → Composite Actions section + references/troubleshooting.md
  → Publish workflow → see rust-npm-publish skill

Add a new platform to the build matrix?
  → Publish Workflow Matrix section
  → Full platform reference → see rust-npm-publish skill

Understand dev vs release versioning in CI?
  → Dev Versioning section

工作流架构

┌─────────────┐     ┌──────────────────┐
│  Node Build  │     │   Rust Build     │
│  (test/lint) │     │  (per platform)  │
└──────┬──────┘     └────────┬─────────┘
       │                     │
       │   ┌─────────────┐   │
       └──►│  Artifacts   │◄──┘
           └──────┬──────┘
                  │
           ┌──────▼──────┐
           │   Publish    │
           └─────────────┘

工作流

工作流	触发条件	执行内容
ci.yml	PR、推送到 main	Node 构建、测试和 lint；Rust fmt、clippy 和测试
publish.yml	发布、dispatch	交叉构建 → 发布到 npm
copilot-setup-steps.yml	repository_dispatch	Copilot Agent 入门设置

模板：templates/workflows/

CI 作业

Node 作业

steps:
  - uses: ./.github/actions/setup-workspace
  - run: pnpm build
  - run: pnpm test
  - run: pnpm typecheck

Rust 作业

steps:
  - uses: actions/checkout@v4
  - uses: dtolnay/rust-toolchain@stable
    with:
      components: clippy, rustfmt
  - run: cargo fmt --all -- --check
  - run: cargo clippy --workspace -- -D warnings
  - run: cargo test --workspace

复合操作

安装到项目中的 .github/actions/<name>/action.yml，然后通过 uses: ./.github/actions/<name> 引用。

模板：templates/actions/

操作	安装路径	用途
setup-workspace	.github/actions/setup-workspace/	Checkout + pnpm + Node.js + 缓存 + 安装
rust-cross-build	.github/actions/rust-cross-build/	为目标平台构建 Rust 二进制文件
compute-version	.github/actions/compute-version/	计算开发版/发布版版本号 + npm 标签
wait-npm-propagation	.github/actions/wait-npm-propagation/	轮询 npm，直到平台软件包可见

发布工作流矩阵

strategy:
  matrix:
    include:
      - { os: macos-latest,   target: x86_64-apple-darwin,      platform: darwin-x64 }
      - { os: macos-latest,   target: aarch64-apple-darwin,     platform: darwin-arm64 }
      - { os: ubuntu-22.04,   target: x86_64-unknown-linux-gnu, platform: linux-x64 }
      - { os: windows-latest, target: x86_64-pc-windows-msvc,   platform: windows-x64 }

每个矩阵条目都会运行 rust-cross-build，并将二进制文件上传为构件。

构件流转

# Upload from build job (one per platform)
- uses: actions/upload-artifact@v4
  with:
    name: binary-${{ matrix.platform }}
    path: target/${{ matrix.target }}/release/my-cli${{ matrix.platform == 'windows-x64' && '.exe' || '' }}
    retention-days: 1

# Download in publish job (all platforms)
- uses: actions/download-artifact@v4
  with:
    pattern: binary-*
    path: artifacts/
    merge-multiple: false

缓存

工具	方式
pnpm	actions/setup-node@v4，并设置 cache: 'pnpm'
Rust	Swatinem/rust-cache@v2，并设置 shared-key: ${{ matrix.platform }}
Turbo	使用 actions/cache@v4 缓存 .turbo 路径

CI 中的开发版本号

非发布构建会计算唯一的预发布版本号：

base version: 0.2.15
compute-version (is-release: false) → 0.2.16-dev.{github_run_id}
npm-tag: dev

使用 compute-version 操作：

- uses: ./.github/actions/compute-version
  id: version
  with:
    base-version: ${{ steps.pkg.outputs.version }}
    is-release: ${{ github.event_name == 'release' }}
# outputs: version, npm-tag, is-dev

故障排除

问题	修复方法
Rust 在 macOS ARM 上构建失败	使用 macos-latest；运行 rustup target add aarch64-apple-darwin
pnpm 锁文件不匹配	在 CI 中使用 --frozen-lockfile；在本地重新生成
Cargo 缓存过大	为 rust-cache 添加 shared-key；仅在 main 上使用 save-if
下游找不到构件	检查 needs: 链；确认构件名称匹配

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

模板

目录	内容
templates/workflows/	ci.yml、publish.yml、copilot-setup-steps.yml
templates/actions/	4 个包含 action.yml 和 README 的复合操作

设置与启用

npx skills add -g onsager-ai/dev-skills --skill rust-node-ci -a claude-code -y

自动启用条件：Rust+Node.js 仓库中存在 .github/workflows/ 目录，或用户提到“CI”“工作流”“GitHub Actions”“交叉构建”。