用途:该技能用于在任何 Node 项目运行 tsc、eslint、构建、测试或安装依赖前,先把当前 Node 版本对齐到项目声明的版本,否则验证结果不可信。
主要能力:按键 .nvmrc → .node-version → .tool-versions → package.json 的 volta.node → engines.node → CI 配置(如 .github/workflows/*.yml)的顺序探测版本声明,首个命中优先。前 1-3 项沿目录树向上查找,package.json 与 CI 配置从项目根读取。
为何必须对齐:主机默认版本(如 v22)常与 .nvmrc 固定版本(如 v14)不一致,会产生误通过(高版本更宽松,但固定版本运行时报错)、误失败(高版本破坏旧工具链)、行为漂移(旧版本缺少 structuredClone、AbortController 等 API)和依赖解析偏差(按当前 Node 安装错误的原生模块)。即便高版本碰巧通过,固定版本仍是唯一事实来源。
使用方式:确认目标版本已安装,例如 ls ~/.nvm/versions/node/ | grep <target-version>;未安装则提示 nvm install <version>。切换与执行必须在同一次命令调用中完成,例如 source ~/.nvm/nvm.sh && nvm use <target-version> >/dev/null 2>&1 && node -v && <actual-command>,因为 shell 状态不跨调用保留。切换后始终执行 node -v 确认,nvm use 可能静默失败。报告结果时需披露 Node 版本,而不只是通过与否。
无声明的情况:若整条链都未找到声明,不要静默回退默认版本或替用户猜测版本。应停止并询问用户使用哪个版本;可用只读的 detect_manager 探测本机管理器信号,据此选择声明文件类型(volta 存在则写 package.json 的 volta.node;asdf 则写 .tool-versions;fnm/nodenv 则写 .node-version;否则默认写 .nvmrc),经用户确认后再持久化,版本写完整 X.Y.Z。写入声明文件应编辑 JSON 而非覆盖,位于项目根。用户拒绝持久化时仅本次对齐。
适用场景:类型检查、lint、构建、测试、依赖安装等版本敏感命令。纯文件 I/O、git、grep 不需要对齐。
限制:SOP 假定 nvm(Unix/macOS);Windows 需手动切换并标注未自动对齐;fnm/volta/asdf 需替换为等效命令;容器/CI 由镜像固定版本,需人工确认与 .nvmrc 一致。绝不可假装已完成对齐。