用 npm 安装 AI 编程工具前，Node.js 环境要怎样准备和检查

Pi、DeepSeek Harness 走 npm/npx 路线，Codex CLI 和 OpenCode 的 npm 安装路线也一样，都要求终端里先有一套可用的 Node.js。装不上工具的时候，问题多半出在环境核对，而不是安装命令本身。先把这一层理顺，再回到工具的安装页，就能省下不少时间。

先说清一件事：node --version 能输出版本号，只说明终端找到了可执行文件，不等于就满足了某个工具的最低版本要求。这两件事要分开检查，后面会分别给出命令。

另一个需要先想清楚的问题：不是所有工具都依赖 Node.js，可以先花一分钟分清这一点。提供独立安装器、Homebrew 或安装脚本的工具，优先按它自己的页面装；不走 npm 路线就不用准备这套环境。

装之前：确认路线、安装、核对三个版本

确认你的安装路线是否需要 Node.js

四个常见工具的前置条件不一样：

• Pi 的 npm 包声明需要 Node.js >=22.19.0，这是四个里面要求最明确的；
• DeepSeek Harness 通过 npx 运行，发布包目前没有声明最低版本，这也不代表所有旧版 Node.js 都能正常运行它；
• Codex CLI 和 OpenCode 只在选择 npm 安装路线时才需要 Node.js，走独立安装器就不依赖系统里的 Node.js。

工具页没有给出版本要求时，一般用 Node.js 官方当前仍在维护的 LTS 版本。旧版本线一旦停止安全更新，再遇到兼容性问题往往就不会有修复了；选定的版本还是要对照工具页的最低要求，比如 >=22.19.0 就比一些旧教程仍在推荐的 LTS 版本要高。

安装 Node.js

从 Node.js 官方下载页选择和当前操作系统、处理器架构匹配的安装方式。下载页会同时列出 LTS 和 Current 两条发布线，日常使用优先 LTS 就够了；不要照抄旧教程里的固定版本号，以官方页面当前显示的为准。

用官方安装程序时，npm 会随 Node.js 一起装好，npx 由 npm 提供，不用单独去下载这两样。

• Windows / macOS：下载官方安装程序，按向导完成就行。装完后记得关掉原来的终端窗口，再开一个新窗口：PATH 是终端启动时读取的，已经开着的窗口拿不到新目录。
• Linux：按 Node.js 官方包管理器说明选择当前发行版对应的方式，也可以用官方二进制包。apt、dnf 这些命令互不通用，照抄别的发行版的步骤，常见的结果就是装失败，或者装进一套发行版仓库里的旧版本。
• WSL：工具准备跑在 WSL，就在 WSL 终端里装、在 WSL 终端里查。Windows PowerShell 和 WSL 是两个环境，各自可能装着不同版本的 Node.js，一边的结果代替不了另一边。反过来也一样：工具准备在 PowerShell 里跑，就只看 Windows 侧的结果。

在同一个终端核对三个版本

在准备安装和运行工具的同一个终端里执行：

node --version
npm --version
npx --version

三条都输出版本号就说明 Shell 在 PATH 中找到了这三个命令，实际数值类似下面这样：

v22.x.x
10.x.x
10.x.x

到这里环境这关就算过了，接下来要确认四件事：

1. node --version 不低于目标工具要求的最低版本；
2. npm 和 npx 都能正常运行；
3. 当前终端就是之后安装和运行工具的环境；
4. Windows 与 WSL 的检查没有互相代替。

装之后：工具命令找不到时先查全局目录

按工具页完成安装后，先跑它自己的版本命令；命令名以工具页为准，通常就是 <工具命令> --version 这种形式。

<工具命令> --version

npm 明明报告安装成功，随后却提示找不到工具命令，这是 PATH 问题里最常见的一种情况。先看看 npm 把全局可执行文件放在了哪里：

npm prefix -g

然后重开终端，再跑一次工具命令。还是找不到，就检查 npm prefix -g 输出的目录是否在当前 Shell 的 PATH 里。这个位置没有固定值，随操作系统和 Node.js 安装方式变化，无论哪套环境都以命令输出为准，不用假设某个固定目录。

同一台机器装过多个 Node.js 的话，还有一步路径检查，能确认当前终端实际用的是哪一套：

Get-Command node, npm, npx | Select-Object Name, Source

command -v node
command -v npm
command -v npx

如果显示的路径不是预期的安装位置，就说明当前 Shell 通过 PATH 找到的，大概率还是旧版本或另一套 Node.js。改过 PATH、重装或切换版本之后，都要新开终端再查一遍，旧窗口里的环境变量是不会变的。

装不上：从 registry 查到权限

先看 registry 和网络

npm 装不上包时，先看当前用的 registry：

npm config get registry

官方 registry 通常是下面这个地址：

https://registry.npmjs.org/

再测它当前是否可达：

npm ping

npm ping 失败时，原因可能出在网络、DNS、代理、防火墙、证书，也可能出在 registry 自身的状态，不一定说明 Node.js 装错了。这时可以先换个网络或关掉代理再测一次，就能区分问题在本地还是在外部链路。

临时切第三方镜像

当前网络访问官方 registry 不稳定时，可以临时改用 npmmirror 镜像。它是第三方服务，和 npm 官方 registry 无关；镜像同步通常有延迟，具体时长官方未说明。

Bash、Zsh 或 WSL 里的话，只为当前这条命令临时指定：

npm_config_registry=https://registry.npmmirror.com npm install -g <package-name>

PowerShell 里分三步，用完记得移除变量：

$env:npm_config_registry = "https://registry.npmmirror.com"
npm install -g <package-name>
Remove-Item Env:npm_config_registry

<package-name> 要换成工具页给出的包名，不要直接复制占位符执行。

AI 编程工具更新快，镜像一旦没同步到最新，就会出现这些现象：找不到工具包、找不到刚发布的版本、装到的版本比工具页所示的低、镜像返回异常。遇到其中任何一条，就切回官方 registry 重试，先排除镜像的因素。镜像同步一旦滞后，装不到新版本往往会被误判成工具本身的问题，多绕一轮才发现。之前持久改过 registry 的，可以恢复成官方地址：

npm config set registry https://registry.npmjs.org/
npm config get registry
npm ping

另外提醒一句：切换 npm registry 只影响 npm 包的下载。安装过程如果还要访问 GitHub 或工具厂商网站，这些地址的连接问题不会随 registry 切换消失。

权限错误不要用 sudo 硬绕

全局安装报权限错误时，别默认用下面这种方式绕过去：

sudo npm install -g <package-name>

root 用户和普通用户混用 npm 全局目录，代价就是全局目录、缓存或文件所有权混乱，之后普通用户安装、更新会反复报错。最好先确认工具是否提供其他推荐安装方式，再检查当前 Node.js 与 npm 安装目录的权限归属。

registry 可达但工具还是装不上

依次跑过 npm config get registry 和 npm ping 都正常，工具还是装不上时，就回到目标工具页核对四件事：npm 包名是否正确、安装命令是否仍然有效、Node.js 版本是否满足要求、当前安装方式是否仍被官方支持。必要时再参考 npm 官方安装与故障排查文档。

常见问题速查

node 找不到：回 Node.js 官方下载页确认安装确实完成了，关掉重开终端；仍然找不到的话，就按上面的路径检查当前 Shell 的 PATH。

版本低于工具要求：按工具页标出的最低版本升级 Node.js，重开终端再对照 node --version。再旧的版本也能正常输出版本号，光凭这个判断版本达标是靠不住的。

PowerShell 和 WSL 输出不一样：这是正常情况，两边本来就是不同的环境。在实际运行工具的那一侧重查一遍，用那一侧的结果往下走就行。

完成条件与下一步

三条版本命令都通过、Node.js 版本满足目标工具的要求、检查就是在实际运行工具的环境里完成的，到这里环境就算准备好了，可以回到对应工具的安装页继续。本篇不处理 Git 和 WSL 2 本身的安装，也不涉及 API Key、模型选择和登录认证，这些在工具页按需展开就行。

参考文档

• Node.js 与 npm 环境完整教程（Muze Wiki）：持续更新，覆盖 PowerShell 与 WSL 的更多检查细节。