nubjs/nub · 上手攻略

仓库：nubjs/nub
链接：https://github.com/nubjs/nub
分类：Node.js 工具链
作者：Tom
更新：2026-07-15

它是什么

nubjs/nub（简称 nub）是一个用 Rust 编写的 Node.js 工具包，旨在替代你最常用的那些 Node.js 开发工具——而不需要你换运行时、换框架、或引入任何供应商锁定的 API。它 Augments Node.js，而不是替换它。

一句话概括：Bun 的开发体验（DX），跑在原生 Node.js 上。

核心定位： - 不发明新运行时 → 你仍然用 Node.js，只是运行得更快 - 不发明新 API → 所有命令与 node / npm / pnpm flag-for-flag 兼容 - 不发明新生态 → 兼容现有 node_modules、package.json、.npmrc 等一切存量资产

解决什么问题

Node.js 生态的问题是：工具链太慢。每次 npm run dev 要忍受数百毫秒的冷启动；npx esbuild --version 要等两百毫秒把 Node 本身 bootstrap 起来；装包动不动几秒。 Bun 和 Deno 想解决这个问题，但代价是需要完全迁移运行时和放弃 npm 生态。

nub 在不离开 Node.js 的前提下，把每一层工具换成 Rust 实现：

痛点	原有方案	nub 方案
运行 .ts 文件	ts-node / tsx / node + 编译	`nub <file>.ts` — 原生支持，2.9× 更快
运行 scripts	npm run（329ms）/ pnpm run（442ms）	`nub run`（14.7ms）——快 22-30×
npx 临时命令	npx / pnpm exec（200ms+）	`nubx`（11ms）——快 17-19×
安装依赖	npm（5.3s）/ pnpm（3.2s）	`nub install`（171ms）——快 4-31×
监听文件变化	nodemon / tsx watch	`nub --watch` — 自动追踪依赖图，无需 glob
Node 版本管理	fnm / n / volta	`nub node` — 自动解析 .nvmrc/.node-version

快速安装

# macOS / Linux（推荐）
curl -fsSL https://nubjs.com/install.sh | bash

# Windows PowerShell
irm https://nubjs.com/install.ps1 | iex

# Homebrew
brew install nubjs/tap/nub

# npm 全局安装
npm install -g @nubjs/nub

# mise
mise use -g nub

验证：

nub --version

⚠️ nub 安装后不需要创建新项目或修改现有项目，任何已有的 Node.js 项目直接可用。

核心用法

1. 运行 TypeScript 文件（最常用）

nub index.ts                    # 支持 .ts/.tsx/.jsx/.mjs/.cjs
nub --watch src/server.ts       # 监听模式，自动重启

支持特性： - 🦆 完整 TypeScript（含 enum、namespace、装饰器） - 🧭 路径别名（tsconfig.json#paths） - ⚛️ JSX / TSX - 🔐 自动加载 .env* 文件（与 Vite/Next.js 行为一致） - 🗂️ 内置 .yaml/.toml/.jsonc/.json5 加载器 - 🌐 自动 polyfill：Temporal、URLPattern、WebSocket、node:sqlite

⚠️ 注意：装饰器支持依赖 emitDecoratorMetadata，部分严格 TS 项目可能需要调整 tsconfig。

2. 脚本运行器（替代 npm run / pnpm run）

nub run build
nub run dev
nub run -r --filter "@org/*" test   # pnpm workspace 兼容

⚠️ --filter 语法与 pnpm 完全一致，与 npm 不兼容。

3. 临时命令执行（替代 npx / pnpm exec）

nubx eslint . --fix              # 本地 bin（快 17-19×）
nubx -y cowsay@1.5.0 "hi"        # -y 自动批准registry下载

4. 安装依赖（替代 npm / pnpm install）

nub install                       # 快 4-31×，自动阻断 postinstall 脚本
nub ci                           # CI 场景
nub add -E -D react              # 兼容 pnpm flags

⚠️ nub 会默认阻断 postinstall，这对安全性有益，但部分有合法 postinstall 的包（如 node-gyp 编译）需要主动放行：nub install --ignore-scripts=false

5. Node 版本管理

nub node install 26              # 安装指定版本
nub node ls                      # 列出已安装版本
nub node pin 22                  # 写入 .node-version

nub 会自动检测项目需要的 Node 版本（优先级：NODE_EXECUTABLE > package.json#devEngines > .node-version > .nvmrc > package.json#engines），无需手动指定。

6. 替代 Corepack

nub pm shim                      # 注册 npm/yarn/pnpm 全局 shims
# 之后无论在哪个项目，运行的都会自动使用项目指定的版本

典型适用场景

TypeScript 开发——不想装 ts-node/tsx，又想要完整 TS 支持（含装饰器、路径别名）
脚本密集型项目——monorepo、CI pipeline，npm run 延迟感知明显
依赖安装频繁——频繁 npm install 的开发流程（nub install 171ms vs pnpm 3.2s）
微前端 / 多 workspace——--filter 跨包运行测试、构建
Node 版本切换——不想装 fnm/n，又想项目间隔离 Node 版本
轻量化 CI——GitHub Actions 用 nubjs/setup-nub 替代 actions/setup-node

坑与注意

坑	说明
`.nvmrc` 不自动触发安装	只读取；版本不存在时 nub 会自动安装（需联网），离线环境请先用 `nub node install` 预装
`--filter` 是 pnpm 语法	和 npm 不兼容，切忌在纯 npm 项目里当 npm run 的等价替代
装饰器需 tsconfig 支持	确认 `"experimentalDecorators": true` 和 `"emitDecoratorMetadata": true`
Windows 兼容性	核心 CLI 完整支持，但 Aube 安装引擎在 Windows 上稳定性略逊于 macOS/Linux
Triton 依赖	部分功能（如某些 Rust 扩展）依赖 triton，仅支持 Linux/WSL，Windows/Mac 不支持
postinstall 被阻断	多数情况下是好事，但 node-gyp 类包需要 `nub install --ignore-scripts=false`
`nub install` 自动检测 packageManager	如果项目同时有 pnpm-lock.yaml 和 package-lock.json，优先级取决于 package.json#packageManager 字段

与同类对比

工具	核心理念	是否新运行时	npm 生态兼容	安装速度	适合人群
nub	Rust 工具 + Node 运行时	❌ 否	✅ 完全兼容	极快（171ms）	不想换 Runtime 的 Node 开发者
Bun	新运行时 + 工具链	✅ 是	✅ 兼容	极快	愿意迁移运行时的人
Deno	新运行时 + 新生态	✅ 是	❌ 不兼容	较快	愿意放弃 npm 生态的人
tsx	TS runner（Node wrapper）	❌ 否	✅ 兼容	一般	只需 tsx 单一功能的人
pnpm	高效包管理器	❌ 否	✅ 兼容	快（3.2s）	只需要更好包管理的人
nodemon	文件监听	❌ 否	✅ 兼容	N/A	只需要 watch 的人

nub 的核心优势：在不离场 Node.js 的前提下，工具层全面提速。适合"我知道 Bun 很快但我不想换"的用户。

一句话推荐结论

如果你在用 Node.js 开发，想要 Bun 的速度但不想换运行时，nub 是目前最无缝的方案——一个命令替换 npm/npx/nodemon/fnm，安装不过三行，现有项目零改造。