GitHub Action

actions/setup-node 的直接替代品。交换一行，你的工作流继续工作：

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
  - uses: nubjs/setup-nub@v0
  - run: nub install
  - run: nub run test

之后的一切解析到项目固定的 Node——与 setup-node 相同的约定。后续步骤中的裸 node、npm 和 npx 运行固定版本，因为该 action 将该 Node 的 bin 目录放在 runner 全局 PATH 的前方。完整的 actions/setup-node 文档描述了此 action 镜像的接口。

- uses: actions/checkout@v4
- uses: nubjs/setup-nub@v0
- run: node --version   # 项目固定的 Node，不是 runner 默认值
- run: nub install

工作原理

该 action 安装 nub CLI，然后在设置步骤期间急切地将项目固定的 Node 提供到 Nub 的缓存中——在任何步骤运行之前下载并就绪，从不在构建中途懒加载。固定从项目的 Node 版本来源解析，按此顺序：

1. package.json#/devEngines/runtime
2. .node-version
3. .nvmrc
4. package.json#/engines/node

该解析的 Node 的 bin 目录被添加到全局 PATH，所以裸 node/npm/npx 和每个后续步骤看到固定版本——与 setup-node 给出的相同 PATH 保证。无固定的项目没问题：急切步骤干净跳过，Nub 在运行时提供。

因为固定位于仓库中，actions/checkout 必须在此 action 之前运行。

所有 actions/setup-node 输入都被接受，所以交换总是机械的——Nub 无法遵守的输入被接受并忽略而非报错。

输入

setup-node 输入 check-latest、architecture、mirror 和 mirror-token 被接受并忽略——存在以使交换从不出错，无效果。version 输入是 nub-version 的弃用别名并发出警告。

nub-version

固定要安装的 CLI 版本——npm 理解的任何 semver 范围。默认最新发布：

- uses: nubjs/setup-nub@v0
  with:
    nub-version: ^0.1.0

node-version

为此次运行在 PATH 前方放置特定版本而非项目固定。该 action 在设置期间提供它并放到全局 PATH 上，所以下游的裸 node 是此版本：

- uses: nubjs/setup-nub@v0
  with:
    node-version: {{NODE_VERSION}}

当作为 nub 调用时，Nub 仍运行项目声明的固定，所以如果此输入与该固定不同，action 会警告。省略它让 Nub 自动解析和提供项目固定。

node-version-file

从文件读取 Node 版本，然后提供并放到 PATH 前方。接受 .node-version、.nvmrc 和 package.json（读取 devEngines.runtime，然后 engines.node）：

- uses: nubjs/setup-nub@v0
  with:
    node-version-file: .node-version

cache

缓存默认开启——当项目看起来可安装时自动启用，镜像 setup-node。自动检测在锁文件或声明 packageManager 或 devEngines 的 package.json 上触发。显式设置输入以覆盖：

- uses: nubjs/setup-nub@v0
  with:
    cache: true   # 强制开启；`false` 强制关闭

包管理器名称（npm/pnpm/yarn/bun）为 setup-node 兼容性被接受并视为开启——Nub 无论包管理器如何都保持一个存储。

缓存键从项目的锁文件和 Node 固定派生，锁文件按此顺序自动检测：

1. pnpm-lock.yaml
2. package-lock.json
3. bun.lock
4. bun.lockb
5. yarn.lock

package-manager-cache

上方自动缓存的禁用旋钮。设为 false 以关闭缓存而不设置 cache：

- uses: nubjs/setup-nub@v0
  with:
    package-manager-cache: false

cache-dependency-path

覆盖自动检测的锁文件用于缓存键控——锁文件路径、glob 或换行分隔的列表：

- uses: nubjs/setup-nub@v0
  with:
    cache-dependency-path: |
      app/pnpm-lock.yaml
      packages/*/pnpm-lock.yaml

restore-keys 梯子在锁文件更改时给出部分热命中。

cache-key-prefix

将前缀注入缓存键（nub-<os>-<arch>-<prefix>-<hash>）以独立于锁文件限定或清除缓存：

- uses: nubjs/setup-nub@v0
  with:
    cache-key-prefix: v2

working-directory

从子目录而非 checkout 根解析 Node 固定和锁文件——用于 package.json/.node-version 位于根下方的 monorepo：

- uses: nubjs/setup-nub@v0
  with:
    working-directory: apps/web

registry-url

设置认证注册表访问。该 action 通过 NPM_CONFIG_USERCONFIG 写入临时用户级 .npmrc 并将认证令牌连接到 NODE_AUTH_TOKEN：

- uses: nubjs/setup-nub@v0
  with:
    registry-url: https://registry.npmjs.org
- run: nub install
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

对于 GitHub Packages，指向注册表，scope 默认为仓库所有者：

- uses: nubjs/setup-nub@v0
  with:
    registry-url: https://npm.pkg.github.com
- run: nub install
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

scope

scope 注册表的 scope。对 npm.pkg.github.com 回退到仓库所有者。registry-url 写入的 .npmrc 遵循与 setup-node 相同的约定，所以现有认证设置不变移植。

always-auth

将 always-auth=true 写入 .npmrc 以在每个注册表请求上认证。

token

解析 Nub 版本范围时 GitHub API 速率限制缓解的令牌（和 GHES 上的 Node 下载）。在 github.com 上默认为 github.token——大多数工作流不需要显式设置它。

输出

与 setup-node 的差异

直接替代是机械的，所以差异很小且很少出现：

• cache 输入是布尔值而非包管理器名称。包管理器名称仍有效（视为开启），因为 Nub 无论包管理器如何都保持单个存储。
• 注册表 .npmrc 新写入到 $RUNNER_TEMP 并通过 NPM_CONFIG_USERCONFIG 指向，而非合并到用户 .npmrc 中。两者由 npm 和 Nub 的包管理器相同解析。

相关

• Node 管理器 — Nub 如何提供和固定 Node 版本。
• 包管理器 — action 的注册表认证供给的安装接口。