1. 为什么 Node.js 在 Windows 上的安装值得单独写一篇
很多人第一次接触 Node.js 都是在 Windows 上，下载一个 msi 安装包，一路 Next，装完之后打开命令行敲node -v能出版本号，就以为万事大吉了。结果真正开始跑项目的时候，各种问题就冒出来了：npm命令找不到、全局包装了却调不出来、npm.ps1报"禁止运行脚本"、切换 Node 版本要卸载重装、node_modules装到一半卡死……这些坑几乎每一个 Windows 开发者都踩过。
这篇内容就是把这些年我在 Windows 上装 Node.js、配环境、调 npm 的经验完整梳理一遍。不管你是刚入门的前端新手，还是需要给团队统一开发环境的负责人，都能从里面找到可以直接抄作业的步骤。核心关键词就几个：windows、node.js、npm、安装配置、环境变量，围绕这几个点把整条链路讲透。
需要先说明一点：Node.js 的安装本身并不复杂，复杂的是"装完之后怎么让它在 Windows 这套环境变量体系里乖乖听话"。Windows 和 macOS、Linux 最大的区别就在于环境变量的管理方式，PATH 的拼接逻辑、用户变量和系统变量的优先级、PowerShell 的执行策略，这些都会直接影响 Node.js 和 npm 能不能正常工作。所以这篇内容不会只讲"点下一步"，而是把每一步背后的原因讲清楚，让你遇到问题时知道该往哪个方向排查。
适合阅读的人群：完全没装过 Node.js 的 Windows 用户、装过但 npm 用不顺的开发者、需要批量配置开发机的运维同学，以及想搞清楚环境变量到底怎么回事的进阶学习者。下面从整体思路开始拆。
2. 安装方案的整体设计与选型思路
2.1 三种主流安装方式的取舍
在 Windows 上装 Node.js，常见的有三条路：官网 msi 安装包、nvm-windows 版本管理器、以及包管理器（如 winget、scoop、chocolatey）。这三条路没有绝对的好坏，关键看你的使用场景。
官网 msi 安装包是最直接的方式，双击、下一步、完成，适合只用一个 Node 版本、不想折腾的初学者。它的优点是稳定、官方维护、自带 npm，缺点是版本切换极其麻烦，想换版本基本就是卸载重装，而且卸载不一定干净，残留的目录会影响下一次安装。
nvm-windows 是社区维护的版本管理工具，可以同时装多个 Node 版本，用一条命令切换。做前端的人几乎都会用到它，因为不同项目依赖的 Node 版本经常不一样，老项目可能还卡在 Node 14，新项目已经上 Node 20 了。它的缺点是需要先卸载已有的 Node.js，安装过程稍微多几步。
包管理器方式适合喜欢命令行、追求自动化的用户。winget 是 Windows 自带的，winget install OpenJS.NodeJS一条命令搞定；scoop 和 chocolatey 需要先装它们本身。这种方式的好处是升级方便，坏处是版本管理不如 nvm 灵活。
我的建议很明确：如果你只学一个版本，用 msi；如果你要做前端或者需要维护多个项目，直接上 nvm-windows。下面两种方式都会讲，你可以按需选择。
2.2 为什么环境变量是绕不开的核心
Windows 上所有命令行工具能被调用，靠的都是 PATH 环境变量。当你在 cmd 里敲node，系统会去 PATH 里列出的每一个目录里找node.exe，找到第一个就用它。Node.js 安装程序会自动把安装目录写进 PATH，但问题往往出在几个地方。
第一，安装时如果勾选了"Add to PATH"，但你的 PATH 已经很长或者有重复项，可能会出现顺序问题，导致调用的不是你刚装的那个版本。第二，用户变量和系统变量里可能同时存在 Node 的路径，优先级是系统变量在前、用户变量在后，如果两边版本不一致就会混乱。第三，卸载 Node 后 PATH 里的残留路径不会自动清理，下次装新版本时旧路径还在，就会出现"明明装了新版，node -v还是旧版"的诡异现象。
所以理解环境变量不是为了炫技，而是为了在出问题时能自己定位。后面每个实操环节我都会告诉你这一步对环境变量做了什么改动。
2.3 npm 与 Node.js 的绑定关系
很多人以为 npm 是单独安装的，其实不是。从 Node.js 0.6 版本开始，npm 就随 Node.js 一起分发了。你装完 Node.js，npm 就已经在node_modules\npm目录里躺着了，命令行能直接调用是因为安装程序同时创建了npm.cmd和npm这两个可执行入口。
这里有个细节值得注意：npm 的全局包安装目录默认在%APPDATA%\npm，这个目录也会被写进 PATH。如果你发现全局装的工具（比如vue-cli、create-react-app）敲不出来，八成是这个目录没进 PATH，或者进了但顺序不对。理解这层关系，后面排查 npm 问题就有方向了。
3. 官网 msi 安装包的完整实操
3.1 下载与版本选择
打开 Node.js 官网的下载页，会看到两个版本：LTS（长期支持版）和 Current（最新特性版）。生产环境和学习一律选 LTS，因为 LTS 有稳定的维护周期，bug 少，社区支持好。Current 版本虽然新，但可能引入不兼容的改动，新手没必要去当小白鼠。
下载时注意选对架构。现在的电脑基本都是 64 位，选x64的 msi。如果你的机器是 ARM 架构（比如某些 Surface），要选arm64。选错了装上去可能跑不起来，或者性能打折。
下载下来的文件名类似node-v20.11.0-x64.msi，版本号会随时间变化。建议下载完先看一眼文件大小，正常在 30MB 左右，如果只有几 KB 那多半是下载中断了。
3.2 安装过程中的关键勾选项
双击 msi 进入安装向导，前面几步都是常规的许可协议和安装路径。安装路径建议保持默认，也就是C:\Program Files\nodejs\，不要图省事装到中文路径或者带空格的路径下，某些老工具对这类路径处理不好。
真正关键的是最后一步的 Custom Setup 界面，里面有几个选项：
- Node.js runtime：核心运行时，必装。
- npm package manager：npm 包管理器，必装。
- Online documentation shortcuts：在线文档快捷方式，可装可不装。
- Add to PATH：这个必须选，它决定了你能不能在任何目录下敲
node命令。 - Automatically install the necessary tools：这个选项会额外装 Python 和 Visual Studio Build Tools，用于编译原生模块。如果你不打算用
node-gyp编译 C++ 扩展，可以不勾，勾了会多下载几百 MB。
我个人的习惯是只勾前两项和 Add to PATH，其他都不勾，保持环境干净。装完之后打开一个新的命令行窗口（注意必须是新开的，旧窗口读不到新的 PATH），敲：
node -v npm -v能分别出版本号就说明装好了。如果node -v有输出但npm -v报错，往下看第 5 节的排查部分。
3.3 验证安装与目录结构确认
装完之后建议去安装目录看一眼，默认在C:\Program Files\nodejs\，里面应该有这些关键文件：
| 文件名 | 作用 |
|---|---|
| node.exe | Node.js 主程序 |
| npm.cmd | npm 的 cmd 入口 |
| npx.cmd | npx 的 cmd 入口 |
| node_modules\npm | npm 的源码目录 |
| node_modules\corepack | corepack 工具目录 |
同时打开"系统属性 - 高级 - 环境变量"，在系统变量的 Path 里应该能看到C:\Program Files\nodejs\这一条。如果没看到，说明安装时 Add to PATH 没勾上，需要手动加。
手动加的方法：在 Path 里新建一条，填入C:\Program Files\nodejs\，确定保存后重开命令行。这一步看着简单，但很多人卡在这里，因为改完不重开窗口是不生效的。
4. nvm-windows 多版本管理的配置方法
4.1 安装前的清理工作
nvm-windows 和已有的 Node.js 是冲突的，因为它要接管 PATH 里的 Node 路径。所以第一步是彻底卸载已有的 Node.js。注意"彻底"两个字：光用控制面板卸载还不够，还要检查这几个地方有没有残留。
C:\Program Files\nodejs\目录是否还在，在就删掉。%APPDATA%\npm目录是否还在，这是全局包目录，可以删。- 环境变量 Path 里有没有
C:\Program Files\nodejs\和%APPDATA%\npm，有就删掉。 - 用户变量里有没有
NODE_PATH，有就删掉。
清理干净之后再装 nvm-windows，否则会出现"nvm 装了但 node 命令还是指向旧版本"的问题。这一步我踩过坑，当时没删干净，折腾了半小时才发现是旧路径还在 PATH 里。
4.2 nvm-windows 的安装与目录规划
nvm-windows 的安装包在它的 GitHub Releases 页面，下载nvm-setup.exe。安装过程中会问你两个目录：
- nvm 安装目录：默认
C:\Users\你的用户名\AppData\Roaming\nvm，建议改成C:\nvm这种短路径，避免路径太长导致某些工具报错。 - node 软链接目录：默认
C:\Program Files\nodejs，这个保持默认即可，因为很多工具默认去这里找 node。
装完之后，nvm 会把C:\nvm和C:\Program Files\nodejs都写进 PATH。注意这里的C:\Program Files\nodejs其实是个软链接，指向当前激活的那个 Node 版本的实际目录。切换版本时，nvm 只是改这个软链接的指向，所以 PATH 不用动。
4.3 常用命令与版本切换实操
打开新的命令行窗口，先验证 nvm 是否可用：
nvm version能出版本号就说明装好了。接下来是几个高频命令：
nvm list available # 查看可安装的版本列表 nvm install 20.11.0 # 安装指定版本 nvm install lts # 安装最新的 LTS 版本 nvm list # 查看已安装的版本 nvm use 20.11.0 # 切换到指定版本 nvm uninstall 18.0.0 # 卸载指定版本nvm use需要管理员权限，因为它要改软链接。如果报"access denied"，用管理员身份打开命令行再执行。切换成功后敲node -v确认版本变了。
这里有个实用技巧：nvm install lts会自动装最新的 LTS，但如果你想要某个具体的 LTS 大版本，比如 18.x 的最新版，可以写nvm install 18，它会装 18 系列里最新的那个。
4.4 全局包在版本切换后的处理
nvm-windows 有个和 macOS 上 nvm 不一样的地方：每个 Node 版本有独立的全局包目录。也就是说你在 Node 18 下装的pnpm，切到 Node 20 之后就用不了了，需要重新装。
这个设计有它的道理，因为不同 Node 版本对原生模块的 ABI 要求不同，共用全局包容易出问题。但用起来确实麻烦，每次切版本都要重装一遍常用工具。我的做法是维护一个global-packages.txt，里面列出常用的全局包，切版本后一条命令批量装：
npm install -g pnpm typescript eslint prettier nodemon把这条命令存成脚本，切完版本跑一下就行。虽然土，但比一个个装省事。
5. npm 配置与镜像源优化
5.1 npm 默认源的问题与替换
npm 默认从官方源拉包，在国内网络环境下速度经常很慢，装个大点的依赖能等到怀疑人生。解决办法是换成国内镜像源。常用的有淘宝镜像（npmmirror）和腾讯云镜像。
换源命令：
npm config set registry https://registry.npmmirror.com换完之后可以用npm config get registry确认。想换回官方源就执行npm config set registry https://registry.npmjs.org。
这里要提醒一句：不要随便用网上的"一键换源"脚本，有些脚本会同时改一堆配置，包括一些你不了解的选项，改完出问题很难排查。手动改 registry 这一条就够了，其他配置保持默认。
5.2 全局目录与缓存目录的迁移
npm 默认把全局包装在%APPDATA%\npm，缓存在%LOCALAPPDATA%\npm-cache。这两个目录都在 C 盘用户目录下，时间长了会占不少空间。如果你 C 盘紧张，可以把它们迁到其他盘。
npm config set prefix "D:\dev\npm-global" npm config set cache "D:\dev\npm-cache"改完之后要把D:\dev\npm-global加进 PATH，否则全局装的工具调不出来。这一步是很多人忽略的，改完 prefix 发现vue命令找不到了，就是因为新目录没进 PATH。
迁移缓存目录后，之前下载的包缓存不会自动搬过去，需要重新下载。所以建议在刚开始配置环境时就规划好目录，别等装了一堆东西再迁。
5.3 npm 常用配置速查
下面这张表整理了我常用的 npm 配置项，可以直接参考：
| 配置项 | 作用 | 推荐值 |
|---|---|---|
| registry | 包下载源 | https://registry.npmmirror.com |
| prefix | 全局包安装目录 | 自定义短路径 |
| cache | 缓存目录 | 自定义短路径 |
| fund | 是否显示赞助提示 | false |
| audit | 是否自动审计 | false |
| progress | 是否显示进度条 | true |
fund和audit关掉能减少每次安装时的网络请求，装包速度会快一点。progress保持开启，装大包时能看到进度，心里有底。
设置命令统一用npm config set 键 值，查看用npm config get 键，列出全部用npm config list。
6. 环境变量配置的深入解析
6.1 用户变量与系统变量的区别
Windows 的环境变量分两层：用户变量和系统变量。用户变量只对当前登录用户生效，系统变量对所有用户生效。查找顺序是系统变量优先，用户变量在后。
这个优先级会带来一个隐蔽的问题：如果你在系统变量里配了一个 Node 路径，在用户变量里又配了另一个，实际生效的是系统变量里的那个。很多人改用户变量发现不生效，就是因为系统变量里有个更高优先级的路径。
排查方法：在命令行敲where node，它会列出 PATH 里所有能找到的 node.exe 路径，按优先级排序。第一个就是实际生效的。如果第一个不是你期望的，就去对应的变量里删掉。
6.2 PATH 的拼接逻辑与常见错误
PATH 是一串用分号隔开的目录。系统查找命令时，从左到右依次在每个目录里找，找到就停。所以顺序很重要。
常见的错误有这么几种。一是路径末尾多了个反斜杠，比如C:\Program Files\nodejs\;，某些情况下会导致匹配失败。二是路径里带了引号，比如"C:\Program Files\nodejs"，引号会被当成路径的一部分。三是路径中间有中文或空格没处理好，虽然 Windows 一般能识别，但个别老工具会出问题。
还有一个隐蔽的坑：PATH 长度限制。老版本的 Windows 对 PATH 有 1024 字符的限制，虽然现在放宽了，但如果你的 PATH 特别长，还是可能出问题。解决办法是精简 PATH，把不常用的路径删掉，或者用短路径替代。
6.3 手动配置环境变量的完整步骤
假设你要手动把 Node.js 加进 PATH，步骤如下：
- 右键"此电脑"，选"属性"。
- 点"高级系统设置"。
- 点"环境变量"按钮。
- 在"系统变量"区域找到 Path，双击。
- 点"新建"，填入
C:\Program Files\nodejs\。 - 一路确定保存。
- 关闭所有已打开的命令行窗口，重新打开一个。
第 7 步是关键，很多人改完不重开窗口，发现没生效就以为配错了。其实环境变量是在进程启动时读取的，已经打开的窗口读的是旧值。
验证方法：新窗口里敲echo %PATH%，看输出里有没有你刚加的路径。有就说明配好了。
7. 常见问题与排查技巧实录
7.1 npm.ps1 禁止运行脚本的解决
这是 PowerShell 用户最常遇到的问题，报错信息类似：
npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本原因是 PowerShell 默认的执行策略是 Restricted，不允许运行脚本文件。npm 在 PowerShell 里是通过npm.ps1这个脚本调用的，所以被拦了。
解决办法是改执行策略。以管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedRemoteSigned的意思是本地脚本可以运行，从网络下载的脚本需要签名。这个策略比Unrestricted安全，比Restricted宽松，是官方推荐的开发环境设置。
改完之后用Get-ExecutionPolicy -Scope CurrentUser确认。如果还是不行，检查一下是不是组策略强制了执行策略，那种情况需要联系管理员。
7.2 node 命令找不到的排查路径
敲node -v报"不是内部或外部命令"，说明 PATH 里没有 Node 的路径。排查顺序如下：
- 先确认 Node.js 是否真的装了，去
C:\Program Files\nodejs\看有没有node.exe。 - 有的话，检查环境变量 Path 里有没有这个目录。
- 没有的话，手动加上，重开命令行。
- 如果加了还不行，用
where node看系统找到了哪些，对比一下。
还有一种情况是装了 nvm 但没激活任何版本。nvm 装完只是装了个管理器，还需要nvm use激活一个版本，软链接才会指向实际的 Node 目录。没激活时C:\Program Files\nodejs是空的，自然找不到 node。
7.3 版本切换后全局命令失效
用 nvm 切了版本，发现之前装的pnpm、yarn这些命令用不了了。这是正常现象，因为每个 Node 版本有独立的全局包目录。解决办法就是重新装一遍，或者用前面说的批量安装脚本。
如果你不想每次都重装，可以考虑用 corepack 管理包管理器。Node 16.9 之后自带 corepack，执行corepack enable之后，pnpm、yarn这些可以通过 corepack 自动按项目配置的版本调用，不依赖全局安装。这是更现代的做法，值得一试。
7.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| node 命令找不到 | PATH 没配或没重开窗口 | 检查 PATH，重开命令行 |
| npm 命令找不到 | npm 目录没进 PATH | 加 %APPDATA%\npm 到 PATH |
| npm.ps1 禁止运行 | PowerShell 执行策略限制 | 改 RemoteSigned |
| 版本切换不生效 | 旧版本残留或软链接没更新 | 清理残留，管理员权限执行 nvm use |
| 全局包装完调不出 | 全局目录没进 PATH | 加 prefix 目录到 PATH |
| 装包速度慢 | 用的官方源 | 换国内镜像源 |
| 装包报权限错误 | 目录权限不足 | 用管理员命令行或改目录权限 |
8. 一些踩坑之后的经验总结
装 Node.js 这件事，说简单也简单，说坑也多。我这些年印象最深的几个教训，分享出来给后来人省点时间。
第一个是别在中文路径下装开发环境。早期我把项目放在"我的文档"里，路径带中文，结果某些工具编译时报错，排查了半天才发现是路径问题。后来所有开发相关的目录都用纯英文，再没出过这类问题。
第二个是卸载要卸干净。Node.js 的卸载程序不会清理 PATH 里的残留，也不会删全局包目录。换版本或者重装之前，手动检查一遍前面说的那几个位置，能省掉很多"为什么新版本不生效"的困惑。
第三个是环境变量改完必须重开命令行。这个坑我踩过不止一次，改完 PATH 在当前窗口测试没反应，以为配错了，其实是窗口没重开。养成习惯：改完环境变量，关掉所有命令行，重新开一个再测。
第四个是镜像源不是越多越好。有些人喜欢装一堆镜像切换工具，今天用这个明天用那个，结果配置混乱，出问题不知道是哪个源的问题。我的做法是固定用一个稳定的镜像源，需要临时切换时用--registry参数单次指定，不动全局配置。
最后说一个关于版本选择的建议：新项目直接用最新的 LTS，老项目跟着项目要求走。不要为了尝鲜用 Current 版本，也不要死守老版本不放。Node.js 的版本迭代很快，保持在一个稳定的 LTS 上，既能用到新特性，又不会遇到太多兼容性问题。如果团队协作，最好在项目里放一个.nvmrc文件写明 Node 版本，大家用 nvm 时nvm use就能自动切到对应版本，省去沟通成本。
