ChangeSUS今天下午有个前同事发来截图，Node.js刚从官网下载完、双击安装、一路Next，结果在PowerShell里敲npm -v，直接弹出一行红字：“npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本”。他问我要不要重装系统。我说，你先别慌，这不是你电脑坏了，是npm和node的安装与配置里最常见的两个坑之一，另一个就是“npm不是内部或外部命令”。
很多教程把安装Node.js写成“下载-双击-下一步-完成”，然后把锅甩给“环境变量没配好”就结束了。但真正让人头疼的从来不是安装过程，而是装完之后一连串环境变量、PowerShell执行策略、多版本冲突、镜像源和奇怪报错。这篇文章我就按实际踩坑顺序，把从零配置到日常使用的完整链路捋一遍。适合刚入门的前端、刚转向Node后端，以及在公司新电脑上第一次配环境的人。
1. 先搞清楚“Node装好了但npm用不了”这句话到底错在哪
1.1 你装的从来不是“一个node”，而是三个组件
很多人以为从官网下载的Node.js安装包装完只是个“编译器”之类的东西，其实装上的是一个运行时加一堆工具的组合体。Windows下典型的安装目录里包含这几类东西：
- node.exe：真正的JavaScript运行时，底层是V8引擎加libuv事件循环库。你在命令行里敲
node命令，跑的就是它。 - npm：一套用Node.js写的包管理CLI，它的真实代码存放在安装目录下的
node_modules\npm里，入口脚本在Windows下是npm.cmd（给CMD用）和npm.ps1（给PowerShell用）。 - npx：附带的一个工具，用来执行项目
node_modules/.bin目录里的命令。 - corepack：用来管理pnpm、yarn等包管理器版本的工具（新版本自带）。
所以“安装npm”并不是一个独立操作，而是Node.js安装包自带的一部分。官方.msi安装包默认都带这些，你根本不用单独再装一遍npm。
但这里有一个冷门但真实的现象：如果你从网上某个“绿色版”“精简版”压缩包解压的Node，解压完目录里只有一个node.exe，没有npm.cmd，也没有node_modules\npm。这种环境下node -v能正常输出版本号，但npm -v一定会报“不是内部或外部命令”。所以遇到“node能跑、npm不能跑”的时候，先别急着怀疑环境变量，先看一眼安装目录里到底有没有npm.cmd这个文件。
1.2 PATH环境变量的作用链：为什么命令行找不到npm
Windows系统在你输入命令时，并不是全局搜索整个硬盘，而是按照环境变量Path里的目录列表，一个一个目录去找同名可执行文件。你输入node，系统按顺序找node.exe；输入npm，系统找的是npm.cmd或npm.exe。
安装Node.js时向导里有一项“Add to PATH”，如果这个选项被勾选，安装程序会把node安装目录（比如C:\Program Files\nodejs\）写进当前用户的Path变量里。如果你没勾选、或者用的是zip包手动解压，那么系统根本不知道该去哪里找你刚装好的node和npm。
手动添加的方式也很简单：在“系统属性-环境变量”里找到用户变量中的Path，点击编辑，新增一行node所在目录。这里有一个大多数人都会踩的细节：改完环境变量后，必须把所有已经打开的终端窗口全部关掉，再重新打开一个。因为终端进程在启动的时候只会读取一次环境变量，启动之后不会自动刷新。你改了配置却还在旧终端里敲命令，当然还是提示找不到。
还有个很容易被忽略的点：PATH里有两个目录和npm相关。一个是node安装目录，负责node命令；另一个是npm全局包目录，默认在C:\Users\你的用户名\AppData\Roaming\npm，负责npm install -g xxx之后生成的全局命令（比如后面要讲的codex）。“npm不是内部或外部命令”通常和第一个目录有关，“全局命令找不到”通常和第二个目录有关。这两件事混在一起排查，最容易绕晕。
1.3 用三条命令验证安装状态，而不是瞎猜
环境出问题时，我一般不靠猜，直接三条命令定位：
bash复制node -v
npm -v
where node
where npm
where命令非常关键，它会把系统在PATH里能找到的所有同名文件列出来。正常情况下会显示类似这样的结果：
text复制C:\Program Files\nodejs\node.exe
C:\Program Files\nodejs\npm
C:\Program Files\nodejs\npm.cmd
如果where npm输出的路径不在node安装目录里，说明PATH被其他工具污染了。我见过有人在电脑上装过两套Node，一套在C盘、一套在D盘，结果where node同时列出两个路径，命令行实际调用的是旧版本，新版本怎么都不生效。这种情况单纯重装解决不了，必须把PATH里多余的node目录清理掉。
另外建议顺手执行一下npm config list，它会显示registry、prefix、cache等关键配置。很多时候你以为当前用的是官方源，实际上某个版本的npm安装包已经在全局配好了镜像源，这个问题在第五章会展开说。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Windows上“npm.ps1禁止运行”不是报错，是PowerShell在拦截
2.1 为什么CMD能跑，PowerShell却报“禁止运行脚本”
继续看开头那个同事的报错：node -v没问题，npm -v却提示无法加载npm.ps1，因为在此系统上禁止运行脚本。
这个问题的关键词是“PowerShell执行策略”（Execution Policy）。PowerShell为了安全，默认不允许直接运行未经签名的脚本文件。npm.ps1本质上是npm官方提供的一个PowerShell脚本，它属于“本地未签名脚本”，在默认策略下会被拦截。
这也是为什么同样一条npm -v，在CMD窗口里能跑，在PowerShell窗口里却报错的原因。CMD执行的是npm.cmd，Windows系统不拦批处理文件；PowerShell执行的是npm.ps1，PowerShell的安全机制要拦脚本。不是npm文件坏了，也不是你装错了，是PowerShell的安全策略在起作用。
2.2 用RemoteSigned来放开，而不是Restricted或AllSigned
解决办法不是把策略改成完全开放，而是设置成“本地脚本可运行、从网络下载的脚本需要签名”的模式。在PowerShell里执行：
powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
这里有三个关键点。
第一个，RemoteSigned的含义：本地创建的.ps1脚本可以运行，从互联网下载且未签名的脚本会被拦截。这比Restricted（完全不执行任何脚本）宽松，但比AllSigned（所有脚本必须签名）实用得多，因为你自己写的大量脚本并没有数字签名。日常开发配置到RemoteSigned就足够了，不建议设置为Unrestricted或Bypass，尤其是开发以外的电脑。
第二个，-Scope CurrentUser表示只对当前用户生效，不需要打开管理员PowerShell，也不会影响系统其他用户。这是最稳妥的作用域。有些教程会让你用管理员权限执行Set-ExecutionPolicy RemoteSigned，那是系统级修改，其实没必要。
第三个容易忽略的点：如果你的电脑装了PowerShell 7（pwsh），它的执行策略和Windows自带的PowerShell 5.1是互相独立的，两边需要分别设置一遍。很多人设置完5.1，切到终端默认的pwsh外壳又报同样错误，就是这个原因。
2.3 VSCode终端里同样报错，顺手解决的方案
这个报错在VSCode里出现频率尤其高，因为VSCode在Windows上的默认集成终端就是PowerShell。你在VSCode里敲npm命令报错，在CMD窗口却没有，会误以为VSCode配置有问题。其实VSCode只是调用PowerShell来执行命令罢了。
如果只是临时要用，可以在VSCode终端右下角或顶部的下拉箭头切换到“Command Prompt”或“Git Bash”，绕开PowerShell。但这不是根治方案，因为下次打开终端它又变回PowerShell，命令还是跑不通。最省心的做法还是执行一次上面的Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，一次配置，之后所有终端（CMD、PowerShell、VSCode、Windows Terminal）通吃。
顺带提一个实战小经验：如果公司电脑有组策略锁定了执行策略，Set-ExecutionPolicy会提示“被组策略阻止”。这种情况不要自己研究怎么绕过，直接联系管理员处理就行。另外，在继续后续配置之前，最好重开一次终端窗口，让环境变量和策略都重新加载，避免“我刚设了策略为什么还报错”的误区。
3. 多版本Node共存才是生产环境的正确姿势：nvm-windows实操
3.1 为什么直接官网下载最新版装全局，项目一多就翻车
很多教程推荐“去官网下载最新LTS版本”就完事，但实际项目里，版本冲突几乎是不可避免的。老项目可能锁死在Node 14，新项目要求Node 20以上，团队里某个CLI工具的文档明确写着“Node 18+”才能运行。这时候如果电脑上只有一个全局Node，你就只能在“卸载重装”和“不同项目来回切”之间反复折腾。
更麻烦的是，直接卸载重装过程中，旧版本残留的环境变量、全局包、npm缓存并不会自动清理，装完新版本后全局命令可能还指向旧目录，问题越积越乱。所以我个人强烈建议：所有做前端的、用Node开发的人，甚至只是偶尔跑一下构建脚本的，都要装Node版本管理工具。
Windows下不能直接装Linux那个nvm，对应的项目是nvm-windows，习惯上也叫nvm。它和Unix系nvm是两个不同项目，命令却大同小异，所以网上的教程常常混着写，踩坑时要注意区分。
3.2 安装流程与settings.txt的镜像配置
nvm-windows的安装步骤不复杂，但有两点必须注意。
第一点，安装之前先把电脑上已有的Node.js卸载干净，包括删除环境变量里手动添加的node相关路径。如果系统里已有一个node安装目录，nvm创建符号链接的时候会冲突，装完之后nvm use经常报错。
第二点，安装时会让你选两个目录。一个是nvm根目录，默认在C:\Users\你的用户名\AppData\Roaming\nvm，存放nvm程序和settings.txt；另一个是node链接目录，默认是C:\Program Files\nodejs，它其实是一个指向当前用版本的符号链接。安装完成后，检查一下系统环境变量，确认NVM_HOME和NVM_SYMLINK都已被正确添加。
装完后还有一个必做的操作：配置镜像源。不配置的话，nvm install会直接从Node官网下载，在国内网络环境下经常慢到超时。打开nvm根目录下的settings.txt，在末尾添加两行：
text复制node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/
随后在管理员终端里执行：
bash复制nvm install 18.20.4
nvm use 18.20.4
注意nvm install的参数是明确版本号，不像npm install那样可以写latest。版本号可以通过nvm list available查看可用的版本列表。
3.3 nvm use失败与node版本切换不生效的排查
用nvm-windows最常见的问题有两个。
第一个是nvm use报错，比如返回exit code 1或提示“Could not find node.exe”。原因通常是nvm要以管理员权限创建或删除C:\Program Files\nodejs这个符号链接，而你的普通终端没有这个权限。解决方法是所有nvm相关命令都在“以管理员身份运行”的CMD或PowerShell里执行。这不算什么安全问题，就是Windows权限设计如此。
第二个是nvm list已经显示当前版本切换到了新版，但node -v还是旧版本号。这基本可以断定不是nvm的问题，而是where node找到了另一个node路径。常见诱因：以前手动安装过Node，残留了一个C:\nodejs或D:\nodejs目录，且这个路径在PATH里的优先级高于nvm创建的符号链接目录。此时打开where node看真实调用的路径，然后从PATH里删掉多余的旧路径。
还有一点值得提：切换Node版本后，npm -v显示的版本也会跟着变，因为nvm会把npm链接一并切到对应版本。这是正常行为，不是配置错了。但全局安装的CLI工具不会跟着自动迁移，切完版本后可能需要重新全局安装一遍，这就引出第四章的全局包管理问题。
4. 全局安装的包“命令找不到”：prefix、cache与环境变量的三方博弈
4.1 命令找不到，先分清是哪一种“找不到”
npm install -g @openai/codex这类全局安装命令跑完，然后执行codex却提示“不是内部或外部命令”，这个场景在热搜词里出现得极其频繁。站在排查角度，我先把这个“找不到”分成三种情况，建议你对照一下自己的输出：
| 情况 | 特征 | 排查方向 |
|---|---|---|
| A | 安装过程没有报错，最后提示“added xxx packages”，但命令找不到 | npm全局bin目录不在PATH里 |
| B | 安装过程报错，比如EACCES权限问题、网络超时、版本不兼容 | 安装根本没成功 |
| C | 安装成功，命令也找到了，但执行时是旧版本或报模块错误 | 电脑里有多个Node/全局目录，路径覆盖 |
很多人一看到“命令找不到”就以为是安装失败，其实情况A最常见，而解法也最简单：把npm全局包的bin目录加到PATH里。
先执行npm config get prefix，看一下当前全局目录在哪。Windows默认是C:\Users\你的用户名\AppData\Roaming\npm。如果这个目录不在PATH变量里，任何npm install -g装出来的全局命令都调用不到。我帮人排查时遇到最典型的对话是：“全局装成功了，但是不生成命令” —— 其实是生成了，只是系统不知道去哪里找。
4.2 推荐把npm全局目录移到你完全可控的路径
默认全局目录在C盘用户目录下，正常情况下够用。但如果你遇到两种情况，就要考虑改全局目录了。
一种是node装在C盘Program Files下，全局安装需要管理员权限，每次都弹UAC，甚至直接报EACCES。另一种是你在公司电脑上被安全软件限制，用户目录下的文件被频繁扫描，全局命令偶尔出现“卡顿”或“被杀”。这时候把prefix和cache挪到一个完全可控的目录是更稳的。
比如在D盘建两个目录：
bash复制npm config set prefix "D:\nodejs\node_global"
npm config set cache "D:\nodejs\node_cache"
然后手动把D:\nodejs\node_global加入用户PATH，重开终端。
这里要特别说明两点。第一，改了prefix之后，以前装过的全局包不会自动迁移，需要重新npm install -g一遍。第二，这个操作只是路径调整，不要顺手去删node_modules目录或cache目录。经常有人搞混：明明只是全局包找不到，却把项目里的node_modules删了重装，折腾半天没解决问题。先确认prefix和cache的真实位置，再决定要不要动。
4.3 以@openai/codex为例，完整演示“装完找不到命令”的排障闭环
以@openai/codex为例，把排障闭环走一遍。
第一步，安装：
bash复制npm install -g @openai/codex
如果这步直接报syntaxerror: the requested module 'node:util' does not provide an export named...，等下，先不要继续。这个报错不是命令找不到，是node版本和依赖不兼容，切到某个Node LTS版本后再重新装。具体原因在第五章讲。
第二步，安装成功后执行：
bash复制codex --version
如果提示“codex不是内部或外部命令”，按第一节的思路排查。执行npm config get prefix，确认全局目录路径，再看这个目录是否在PATH里。
第三步，检查目录里有没有生成命令文件。Windows下全局CLI通常会生成一个codex.cmd，在全局目录下：
bash复制dir C:\Users\你的用户名\AppData\Roaming\npm\codex*
如果文件存在但没有加入到PATH，那问题就清楚了。把目录加入PATH，重开终端，再执行where codex，应该能看到具体路径了。这时候再跑codex命令就通了。
如果文件不存在，说明安装过程出了问题。不急着重装，先看npm install -g的完整日志，是权限问题、网络问题，还是node版本过低导致的模块编译失败。修复底层原因后，再进行一次干净安装。
5. 从卡在“npm install”到奇怪的module报错：镜像源、缓存与版本兼容
5.1 镜像源配置：别把所有项目都圈死在全局registry上
在国内网络环境下，npm install卡住、超时、报各种网络错误是家常便饭。最常见的解决思路是把registry从官方源切到npmmirror镜像源：
bash复制npm config set registry https://registry.npmmirror.com
npm config get registry
这样设置之后，所有npm安装请求都会走镜像源，速度和稳定性会明显改善。这个操作本身没问题，但“全局永久改源”有一个隐患：如果公司有内部私有npm源，你沿用镜像源会导致公司内部的私有包装不上。我不建议在个人电脑上盲目全局改源，更推荐用项目级.npmrc：
在项目根目录创建.npmrc文件，写入：
text复制registry=https://registry.npmmirror.com
这样只有这个项目使用镜像源，其他项目不受影响。如果只是某一次安装想让镜像源生效，也可以临时指定：
bash复制npm install --registry=https://registry.npmmirror.com
排查配置时，用npm config ls -l可以列出所有生效配置项；用npm config get registry只看当前源。如果你发现某个项目“明明改了源，但还是走官方源”，检查一下项目根目录和用户目录下是否存在.npmrc文件，这个文件的优先级高于你手动执行的npm config set。
5.2 “node:util does not provide an export named”这类报错到底怎么回事
热搜词里的syntaxerror: the requested module 'node:util' does not provide an export named，看起来像源码问题，实际上绝大多数情况是Node版本和依赖包版本不兼容。
node:util这种带node:前缀的模块写法，是Node.js在较新版本里对内置模块的显式引用方式。它告诉Node“我要的是内置的util模块，不是node_modules里那个叫util的第三方包”。理论上这不是问题，但如果某个工具依赖的第三方包版本太旧，模块内部还是老式的CommonJS写法，或者它同时引用了一个与内置模块同名的包，Node在解析ESM时就会报“does not provide an export named”。
典型场景是：你刚用nvm切到一个很新的Node版本（比如某个非LTS的激进版本），然后去启动一个几年前的老项目，或者全局安装一个老工具，就会遇到这个报错。处理步骤按优先级排列：
- 如果是项目依赖问题，升级出问题的依赖包到兼容版本，然后重新安装。
- 如果是全局CLI，用
nvm use切回Node官方LTS版本，再重新全局安装。 - 删除项目根目录的
node_modules和package-lock.json，执行npm install重新构建依赖。
这里真正想强调的排查思路是：遇到这种带node:前缀的模块报错，先看你的Node版本和包本身的兼容性要求，别在单个文件里找问题。版本组合导致的“玄学错误”，十有八九靠切换Node版本或升级依赖能解决。
5.3 清理缓存与重建依赖的正确顺序
还有一个高频问题是npm install安装到一半网络中断，之后重试老是报哈希校验失败、或者某些包一直被跳过。这时候需要清理npm缓存并重建依赖。
我推荐的执行顺序是：
bash复制# Windows下删除node_modules，务必在管理员终端执行
rmdir /s /q node_modules
# 删除lockfile，避免旧版本限制重新安装
del package-lock.json
# 清理npm缓存
npm cache clean --force
# 重新安装
npm install
这里有一个实操经验：rmdir /s /q node_modules在Windows上偶尔会提示某个文件被占用，常见原因是你的编辑器（VSCode、IDE）正在索引或监听这个目录。先把编辑器关掉再删，大概率就好了。如果还是删不掉，重启一次电脑再删，比手动右键疯狂尝试有效得多。
另外，npm cache clean --force并不是越频繁越好。npm 5以后的缓存机制很成熟，自己会校验完整性，正常安装不需要手动清理。只有确认“半包”或缓存损坏时才值得执行。执行一次相当于清空缓存重新下载，下一次install会明显变慢，没必要当日常操作。
最后分享一个我觉得收获很大的小习惯：每次在新电脑上配完Node环境，我都会把用到的命令（nvm安装、Node版本、npm config、执行策略设置）整理成一个文档丢进团队Wiki。因为你会发现，半年后换电脑、换公司，这些坑还会原封不动再踩一遍。这份文档能让你从“配置一小时”直接缩到“十分钟搞定”。环境配置这件事，经验不值钱，被验证过的流程才值钱。