安装
可通过 npm、pnpm 或 yarn 安装 Nudo 工具。覆盖面:CLI(nudojs)、VS Code 扩展(nudo-vscode)、Zed 扩展,以及 Vite 插件(vite-plugin-nudo)。
前置要求
- 运行发布版 CLI:Node.js >= 22(各发布包
engines;Node 20 已 EOL) - 开发本仓库:Node.js >= 22(CI 使用 Node 24)
发布包以编译后的 ESM dist/ 发布(files: ["dist"]),不是 TypeScript 源码。没有额外运行时要装 —— CLI 就是普通 Node。
CLI
# 全局安装 —— 得到 `nudo` 命令
npm install -g nudojs
# 或作为项目依赖安装
npm install nudojs
# 或
pnpm add nudojs
# 或
yarn add nudojs
然后观察并门禁你的代码:
npx nudojs check path/to/file.js # 签名 + 契约门禁
npx nudojs test path/to/file.js # 调用点 case 报告
# 若已全局安装,命令就是 `nudo`
一级动词:check / test / contract / export / health。没有 infer 动词——观察来自 check 签名、test 用例与 IDE hover。
| 安装方式 | 命令形态 | 适用 |
|---|---|---|
全局(npm i -g nudojs) | nudo check … | 日常本地工作、shell 脚本 |
项目依赖(pnpm add nudojs) | npx nudojs check … | CI、与代码同仓锁定版本 |
一次性(npx nudojs …) | 不安装 | 决定引入依赖前先试用 |
npx
npx nudojs check src/ 是标准 CI 调用 —— 有项目本地安装时解析本地版本,否则临时下载。流水线里优先用项目依赖(加锁文件),把分析器版本钉死。
Monorepo / pnpm workspaces
在 workspace 根装一次 nudojs,或在需要门禁的每个包里各装一份。用 nudo.analysis.include / exclude 圈定 IDE 分析范围,让 JS 包走 Nudo、TS 包留在 tsc:
{
"nudo": {
"analysis": {
"mode": "exports",
"include": ["packages/js-lib/src/**"],
"exclude": ["**/*.test.ts", "packages/ts-lib/**"]
}
}
}
细节:与 TypeScript 共存 · Recipes —— monorepo。
VS Code 扩展
安装 nudo-vscode 扩展可获得内联类型提示和诊断信息:
- 从 最新 GitHub Release 下载
nudo-vscode.vsix - VS Code → 扩展(Ctrl+Shift+X / Cmd+Shift+X)→
…菜单 → 从 VSIX 安装… - 选择刚下载的文件
code --install-extension nudo-vscode.vsix
扩展同时发布到 VS Code Marketplace 与 Open VSX(wmzy.nudo-vscode)——如果你的编辑器能在扩展视图里搜到它,直接安装等价:
code --install-extension wmzy.nudo-vscode # 列表可达时可用
上架是发布产物而非承诺:GitHub Release 上的 .vsix 才是真源,市场 token 可能过期(发布任务只警告、不失败)。也可以随时从源码构建:pnpm --filter nudo-vscode run build && pnpm --filter nudo-vscode run package。
vsix 自包含:扩展捆绑了语言服务器,无需另装 @nudojs/lsp 扩展即可启动。激活事件是 onLanguage:javascript / onLanguage:typescript;缓冲区是否被分析由 nudo.analysis.mode 门禁决定。完整面:VS Code 指南。
Zed
nudo Zed 扩展把 Nudo 语言服务器作为副语言服务器挂到 JavaScript / TypeScript 缓冲区(与 vtsls 并列)。它在独立仓库(nudojs/nudo-zed),需要 @nudojs/lsp ≥ 0.5.0 在项目本地、全局,或经 Zed 的 npm 回退可用。
Vite 插件
使用 vite-plugin-nudo 在开发或构建时运行 Nudo:
npm install vite-plugin-nudo --save-dev
# 或
pnpm add -D vite-plugin-nudo
在 vite.config.js 中:
import { defineConfig } from "vite";
import nudo from "vite-plugin-nudo";
export default defineConfig({
plugins: [nudo()],
});
构建过程中,插件按 nudo.analysis.mode 筛选文件(出厂默认 "exports"),并将 Nudo 诊断——求值器问题加契约门禁违例(nudo:constraint-violated、nudo:assign-mismatch、nudo:arg-structure)——报告为构建警告;设置 failOnError 后变为构建错误。参见 Vite 插件指南。
验证安装
Nudo 通过执行目标代码来分析(Abs 语义,进程内求值)。不要对不可信代码运行 nudo check / nudo test;在 CI 里这与跑项目测试是同一信任级别。为何以执行为模型:语言语义。
在任意小 JS 文件上对 CLI 做冒烟测试:
npx nudojs check path/to/file.js
成功与失败时都应看到 signatures 被打印 —— check 不是静默的。退出 0 表示门禁通过;退出 1 表示有 error 级诊断(L1 契约或 L2 入口 may-throw)。接着在 VS Code 或 Zed 里打开同一文件并 hover 导出:推断签名应与 CLI 一致。
若 npx nudojs 缺失或解析失败,检查 Node 版本(node -v ≥ 20),以及包名是 nudojs(npm 包名),而二进制是 nudo / nudojs。