每个装了 Node 又被坑过的人大概率都见过这样一行红字npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本第一次见这行字的时候我正打算跑npm install结果命令行直接罢工我一度以为是 Node 装坏了。后来才发现Node 本身装得一点毛病没有是 Windows 默认的 PowerShell 执行策略把 npm 的脚本给拦了。今天这篇就把 NodeJS 安装与配置这件事从头到尾拆开讲清楚从版本选择、安装步骤、环境变量到各种高频报错怎么解一次讲透。1. 装之前先想清楚版本选错等于白装很多人看到 NodeJS 官网第一反应是“直接点那个最大的按钮下载”结果装完用了两周就遇到某些依赖装不上、某个包跟你说只支持更高版本。所以在双击安装包之前我建议你先花两分钟想清楚自己要装哪个版本。1.1 LTS、Current 和 nvm怎么搭配才省心NodeJS 官网会提供两个大版本的下载入口LTS长期支持版和 Current当前版。LTS 追求稳定官方会持续维护适合生产环境和绝大多数日常开发Current 则包含最新特性版本号更新快适合想尝鲜或者搞技术调研的人。给新手的建议很简单无脑选 LTS别犹豫。再往后只要你做的项目多了就会遇到“这个老项目要用 Node 14那个新项目要用 Node 20”的尴尬局面。这时候千万不要反复卸载重装直接在装 Node 之前先装一个版本管理工具 nvm会让后续的配置过程省掉大量不必要的折腾。Windows 上用nvm-windowsmacOS 或 Linux 上直接用nvm后面我会单独讲这部分实操。1.2 64 位还是 32 位、安装包格式怎么选Windows 用户下载时还会看到.msi和.zip两种格式。.msi是图形化安装包适合绝大多数人会自动帮你写环境变量、关联文件类型省心。.zip是绿色解压版适合有洁癖、想手动控制一切的人。我日常推荐前者不是说 zip 不好而是 msi 对新手更友好安装路径和环境变量都是引导式配置不容易出问题。至于 32 位还是 64 位先看一眼自己系统的位数。现在绝大多数电脑都是 64 位直接选 x64 就行。只有非常老的机器还在跑 32 位系统时才需要选 x86。另外提醒一下如果你已经从官网下载好了安装包先看一眼文件大小一般 x64 的 msi 安装包在 20MB 以上十几 MB 的反而要留个心眼别从第三方下载站点拿到被改动过的包能去官网就去官网。1.3 安装前先想清楚的一个问题你是否需要多版本共存我问过很多同事装 Node 时最悔恨的操作是什么十有八九都会说“没早点用 nvm”。如果你有多个项目、涉及多个技术栈或者后面想玩 Vite、Webpack、Next.js 之类的框架不同版本对 Node 版本的要求是不一样的。你今天只装一个 LTS 可能短期够用但三个月后一定会遇到版本冲突的痛点。所以我的建议是如果是新机器第一次装直接用 nvm 来装 Node既解决了当前需求又给以后留了后路。2. Windows 实操安装从下载到“下一步”的完整记录以 Windows 11 为例完整走一遍.msi安装的流程。这个流程在 Windows 10 上几乎一模一样我写的每一步都是实际验证过的。2.1 下载安装包时的几个“坑位”提醒打开 NodeJS 官网nodejs.org后首页就有两个按钮左边 LTS右边 Current。我前面说了优先 LTS。点击下载后官网会根据你的操作系统自动推荐.msi安装包但我建议你手动去 Windows Installer (.msi) 里选一下具体的 x64 版本避免下载到奇怪的历史版本。下载过程中唯一需要注意的点是不要在下载工具比如某些下载器里选“加速模式”。Node 安装包不大普通浏览器直接下载就行。如果下载速度很慢再去考虑换镜像源这个点我在后面第 5 章详细说。2.2 安装过程中的关键选项解析双击.msi安装包后第一个界面是欢迎页直接 Next。然后是用户协议勾上 I accept 后继续。真正要留意的是下面这步Destination Folder安装路径选择Custom Setup自定义安装组件默认安装路径是C:\Program Files\nodejs\。我的建议是要么保持默认要么改成一个没有空格、没有中文的路径比如D:\dev\nodejs。不要安装到有中文名或者带空格的目录后面很多命令行工具解析路径时会出各种匪夷所思的 bug。虽然现在新版本 Node 对空格容忍度提高了但顺手规避掉这个风险点能省很多闹心事。Custom Setup 里你可以选择安装哪些组件。不熟悉的话保持默认全选即可。特别提醒npm package manager 这个组件一定要保留它默认是勾上的千万别为了“精简”把它取消掉不然装完 Node 你就发现自己连 npm 都没有。安装时还有一个选项是勾选“Add to PATH”默认就是勾上的保留。如果你不小心取消了这个勾装完后你会发现命令行里输入node -v会提示“不是内部或外部命令”因为系统不知道去哪里找 node.exe。虽然事后可以通过手动加环境变量补救但没必要多走一步。2.3 安装完成后会得到什么安装完成后在安装目录里最核心的是node.exe和npm.cmd。前者是 Node 运行时本身后者是 npm 的命令行入口。还要注意有个node_modules目录npm 全局包默认不会装到这里但在某些特殊情况下你会看到它存在比如你用 npm 全局安装某些带二进制依赖的包时它会临时解压到这个目录。这个细节后面讲全局模块路径时会用到。装完后先在 PowerShell 里敲node -v npm -v如果输出了版本号比如v20.18.0和10.8.2说明安装成功基础环境已经可用。如果这里就报错了先别急大概率是 PATH 环境变量没有生效或者终端窗口没重开。这个问题在第 3 章里详细解。3. 环境变量配置才是“安装成功”的真正分水岭很多新手以为安装完成就等于配置完成等到输入npm install -g某个包然后发现全局命令用不了才意识到环境变量没那么简单。我单独开一章把环境变量相关的事情讲清楚。3.1 PATH 变量与全局模块目录Node 安装时自动写入 PATH 的基本就是 Node 安装目录本身也就是node.exe所在的目录。系统在执行命令时会按照 PATH 里配置的目录顺序挨个去查找可执行文件。所以只要你把C:\Program Files\nodejs\加进 PATH就能在任意路径下执行node命令。但npm install -g package安装的全局包默认会装到一个独立目录 —— 前缀 Prefix。默认情况下这个目录是C:\Users\用户名\AppData\Roaming\npm。所以全局包里的可执行文件比如vue.cmd、yarn.cmd、pnpm.cmd会被放到这个目录里。如果你发现npm install -g vue装完后在终端里输入vue --version却提示找不到命令十有八九就是这个目录没在 PATH 里。查看当前全局模块目录的命令是npm prefix -g npm config get prefix如果输出的路径不在 PATH 里你需要手动把它加进用户变量。具体操作右键“此电脑” → 属性 → 高级系统设置 → 环境变量在“用户变量”里找到 Path点击编辑新增一行填入上面命令输出的路径。改完后重新打开终端vue --version这类命令就生效了。3.2 npm 启动脚本为什么会报“禁止运行脚本”回到开头的那个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这个错和 Node 本身半毛钱关系没有是 PowerShell 的执行策略Execution Policy默认限制住了.ps1脚本的运行。npm 的入口命令在 PowerShell 里走的是npm.ps1而 Windows 默认不允许执行它结果就炸了。解决办法有两种。第一种以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned这条命令允许本机脚本和已签名的远程脚本运行。输入Y确认即可。之后重新打开终端npm 就能正常执行了。这是最常用、也最省事的方式。第二种如果因为某些原因你不想修改执行策略级别也可以在 PowerShell 里直接用命令行的替代入口npm.cmd 命令比如npm.cmd install vue。因为.cmd文件不受.ps1执行策略限制。但不推荐长期这么干还是把执行策略改到 RemoteSigned 更符合日常使用习惯。这里提醒一个细节改了执行策略之后建议重新启动一次 PowerShell或者干脆重启终端让配置彻底生效。我遇到过几次只开着旧窗口测试以为没改成功空折腾了十分钟。3.3 环境变量顺序和重启终端的坑配置 PATH 时还有个容易忽略的问题环境变量修改后已经打开的命令行窗口不会自动重新加载新的环境变量。你需要关掉所有终端窗口重新开一个。如果改的是系统变量有些情况下还需要重启一次资源管理器甚至重启电脑。顺序问题则是这样如果你的 PATH 里有多个目录包含同名命令系统会按顺序从上到下找找到第一个就执行。所以如果你电脑里曾经装过老版本 Node后来换了新版本注册表或 PATH 里可能有几个残留的 Node 路径。排查问题时要留意where node命令它会告诉你系统实际用的是哪个目录的 node.exe。where.exe node where.exe npm输出结果里如果有多个路径去检查哪个真正存在并调整 PATH 顺序让目标版本排在最前面。否则你明明装了新版 Node执行node -v却还是旧版这情况特别容易让人误判是升级失败。4. 验证安装和第一个 Node 程序配置完环境变量之后正式验证一下整个 Node 环境是否可用。除了node -v和npm -v建议再做几个更贴近实际使用的验证避免“带了半天发现装了个寂寞”。4.1 用 npm 配置信息确认环境在终端里执行npm config list你会看到一堆配置项包括registry、prefix、cache等等。这一步的关键点是确认registry是不是默认地址https://registry.npmjs.org/。如果之前装过某些代理工具或者配置过镜像这里可能已经变成了别的地址。在国内很多人会主动换成国内镜像源这本身没问题但如果你发现某些包装不上、下载慢第一步就是先看 registry 配置很多时候是镜像没同步全导致的。4.2 用一个小脚本测试完整链路光看版本号还不够建议你真正跑一次 Node 脚本。新建一个文件比如hello.jsconst os require(os); const path require(path); console.log(Hello from Node.js); console.log(temp dir:, os.tmpdir()); console.log(global prefix:, path.resolve(__dirname));然后在终端执行node hello.js如果能正常输出三行内容说明 Node 的核心功能、常用模块和路径解析都正常。这也算是给新手一个初步的“Node 能跑”的感知比只敲一句node -v有意义得多。4.3 顺手验证 npm 是否能正常安装包再进一步在任意空白目录里执行npm init -y npm install lodashnpm init -y会生成一个默认的package.jsonnpm install lodash会把 lodash 安装到当前目录的node_modules里并写入依赖声明。能看到added 1 package这样的输出说明 npm 的核心工作流拉包、解压、写入全部正常。这条链路验证通过之后你的 Node 环境才是真正“能干活”的状态。5. 常见报错与排查实录实操中报错是难免的我把自己踩过、以及帮别人排查过的几类高频问题整理成实录每条都给你可操作的解决路径。5.1 npm 报错 EACCES / EPERM权限不足这类报错在 WordPress 时代就经常出现在 Node 上也很常见。典型场景是在某些目录下执行npm install -g提示EACCES: permission denied。Windows 上很多时候是因为当前终端不是管理员身份或者目录权限被锁死了。解决思路分三步换用管理员身份打开终端再执行如果是某个项目目录的node_modules损坏删掉node_modules和package-lock.json重新执行npm install如果全局目录权限混乱可以查看并重置全局目录npm config get prefix npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm最后一步相当于把全局目录指到一个用户级目录避免操作系统级目录的权限限制。5.2 报错“无法加载文件 npm.ps1”这个就是第 3.2 节讲的执行策略问题。再补充一个场景有些公司电脑被域策略锁住了普通用户没有权限去修改执行策略。这时候可以在当前用户作用域下设置Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser加上-Scope CurrentUser就不需要管理员权限只对当前用户生效既安全又有效。如果连这也被禁止那极可能是系统级策略非常严格建议联系管理员处理同时在日常中使用npm.cmd作为临时替代方案。5.3 安装进程卡在“downloading”或超时这在国内网络环境下尤其常见。npm 默认的 registry 地址在国外下载速度时快时慢严重时会直接超时。推荐把 registry 切换为国内镜像源比如npmmirror.com原淘宝 npm 镜像npm config set registry https://registry.npmmirror.com验证是否生效npm config get registry切换后大部分包的下载速度会明显提升。不过有些企业级私有包仍需要走公司内部 registry所以切换前先确认自己有没有公司私有 npm 源。另外如果某个包本身自带二进制安装脚本比如sharp、canvas这类它下载二进制文件时可能不走 npm registry而是走 GitHub Releases。这种情况下切换 registry 不一定能解决问题更实用的方法是配置镜像的环境变量。以sharp为例官方文档通常会给出对应的镜像配置方式。遇到具体报错时先搜索包名 镜像配置通常都能找到解法。5.4 npm 版本过旧或过新导致的问题Node 版本和 npm 版本往往绑定在一起。新版 Node 自带新版 npm但如果你手动升级过 npm用的npm install -g npmlatest可能会出现最新版 npm 和当前 Node 版本不兼容的情况。报错通常长这样error: Unsupported engine或者TypeError: ... undefined解决方法很直接把 npm 降级回与 Node 匹配的版本。默认情况下LTS 版 Node 自带的 npm 版本是最稳定的。查看可用版本npm view npm versions --json然后安装指定版本npm install -g npm10.8.25.5 中文路径或空格路径导致的奇怪问题前面第 2.2 节提醒过安装路径不要带中文和空格这里再说一个项目目录层面的问题。如果你的项目路径本身包含中文比如C:\Users\张三\project部分原生模块在编译时可能会因为路径编码问题报错。解决办法是尽量把项目放在纯英文路径下。同类问题还包括项目目录名带有空格。有些构建工具的配置文件会解析出错。这两类问题排查起来非常隐蔽但一旦遇到最好的解法就是先把路径改干净再重新执行安装。5.6 删除 node_modules 时 Windows 提示文件被占用开发中经常要删除node_modules但 Windows 会经常提示“文件正在使用”或“操作无法完成”。这是因为某些进程比如 Vite、Webpack、Node 的 watch 模式还在占用这些文件。解决办法很简单先停掉所有 Node 相关进程再删除。命令行里可以用taskkill /F /IM node.exe这条命令会强制结束所有 node 进程。注意如果你本地还有其他 Node 服务在跑比如后端接口服务或者工具链也会一并被关掉所以执行前先确认没有正在跑的重要任务。之后再用文件管理器删除node_modules或者用rimraf这个跨平台删除工具会更顺手。5.7 清理 npm 缓存有时候安装报错是缓存损坏导致的。npm 的缓存目录默认在C:\Users\用户名\AppData\Local\npm-cache如果遇到莫名其妙的报错可以尝试清理npm cache clean --force清完之后再重新npm install。这一步在很多疑难杂症里反而是最有效的。不过别指望它解决所有问题本质上它只清理缓存不改变依赖版本和配置。6. 进阶配置与个人经验分享到这里基础的 NodeJS 安装与配置已经完整走通了。接下来再聊几个能明显提升日常体验的方向都是我实际用下来觉得值得投入几分钟配置的内容。6.1 用 nvm 管理多个 Node 版本前面提过 nvm这里给一个精简的实操流程。Windows 用户先去下载nvm-windows的安装包安装时注意nvm 的安装路径不要和 Node 的安装路径重合而且要确保电脑上之前没有残留的 Node 安装否则可能因为注册表残留导致 nvm 无法接管版本切换。装好 nvm 后执行nvm install 20.18.0 nvm install 18.20.4 nvm use 20.18.0 node -v这样你会发现本机同时存在多个 Node 版本随时可以切换。切到某个版本后对应的 npm 也会自动切换。这个体验用过的都说回不去了。注意事项nvm-windows 和nvm原版在实现机制上有差异。Windows 版是通过路径符号链接来实现版本切换的所以你在 nvm 安装目录里能看到v20.18.0这种子目录。如果安装后切换版本无效检查一下 PATH 里是否还有原来的 Node 路径把它去掉确保只保留 nvm 相关路径。6.2 设置 npm 全局依赖安装路径的心得有段时间我喜欢把全局包都装到一个统一目录方便管理和备份。做法是npm config set prefix D:\dev\npm-global npm config set cache D:\dev\npm-cache设置好之后再手动把D:\dev\npm-global加进 PATH。其实不这么做也没问题系统默认方案已经足够可靠。我这样做的唯一原因是“想统一管理开发工具”但如果你才刚刚入门建议先用默认配置等真正遇到问题了再调整不要一上来就把自己搞成一个复杂的配置灾难。6.3 配好镜像源之后选哪个包管理器国内的话配好 registry 镜像之后npm本身速度已经可以接受。不过日常开发里很多团队会选用pnpm或yarn。pnpm的特色是节省磁盘空间依赖安装速度更快而且对 monorepo 项目支持很好。yarn则胜在经典、稳定很多老项目还在用它。安装pnpm非常简单npm install -g pnpm然后你就可以用pnpm install替代npm install。但有一点要提醒同一个项目建议团队统一一种包管理器不要混用 npm、yarn、pnpm因为它们的 lock 文件机制不同混用容易把依赖树搞乱严重的会导致装出来的环境不一致。6.4 npm 脚本和 Node 服务的日常提醒配置好环境、能正常npm install了接下来大概率会接触package.json里的scripts字段。写脚本时有个小坑在 Windows 上用 npm 执行脚本时如果脚本里涉及到export设置环境变量会直接报错。因为 Windows 不识别export。解决方案是使用cross-env这个第三方包npm install -D cross-env然后在 script 里写{ scripts: { start: cross-env NODE_ENVproduction node app.js } }这类环境差异问题在跨平台开发时几乎一定会遇到提前了解能少走不少弯路。6.5 关于“安装完 Node 把其他工具带崩”的典型坑最后分享一个我很早就遇到的坑Node 安装后自带 npm 会把一些包全局安装了比如某些版本的grunt-cli、gulp-cli。之后再升级 Node 大版本可能发现这些全局命令失效了。原因很简单全局包目录和 Node 版本绑定切换或升级 Node 后全局包所依赖的二进制文件可能已经不适合当前新版 Node。解决方案就是活下去的日常习惯全局工具能不装就不装能用npx用npx。npx会临时下载并执行某个包不污染全局环境。比如你要用 Vite 创建项目直接npx create-vite省去全局安装和后续清理的麻烦。我在实际使用中对这个点的感触很深很多同事总喜欢npm install -g xxx装得多了哪天一些工具莫名其妙就起不来了其中一半是这个“全局包和版本不匹配”的问题。我现在全局里只留两三个高频工具其余全部交给npx或者项目级依赖来管。6.6 升级 Node 的时机与操作建议Node 升级不需要频繁LTS 版本内的小版本更新可以跟着官方节奏走。如果你是用 nvm 管理版本的升级非常轻量新版本安装 切换即可。如果不是用 nvm那 Windows 上的升级通常是直接覆盖安装新版.msi。覆盖安装时旧版全局 npm 包大概率会被保留但个别原生模块可能需要重新编译这个要注意。还有一个经验卸载 Node 时要检查环境变量里是否残留了旧路径以及AppData\Roaming\npm和AppData\Local\npm-cache里是否有旧数据。很多人升级完 Node 后发现 npm 还是老版本就是因为这些残留数据没有被清理。这个内容到这里已经足够接地气了剩下的就是动手去装。纸上谈兵永远看不出来问题真正把安装包跑到一半、遇到报错、再查资料解决之后你对 Node 环境配置的理解会完全不一样。按我这几年的实操经验只要你把版本选择、环境变量、npm 镜像源和执行策略这四个关键点搞明白后面无论装什么基于 Node 的工具链都能少踩一半的坑。