直接把 2024 最新版 Node.js 下载、安装、环境配置这一整套流程，掰开了揉碎了讲一遍。
先说个实际感受：帮人装 Node.js 装多了，我发现真正卡住新手的往往不是“下一步”点得对不对，而是安装完之后那一堆“环境变量”“命令行工具链”“镜像源配置”看不懂。很多人照着教程装完，一输node -v就报错，或者 npm 装包慢到怀疑人生，然后就开始怀疑自己装了个假 Node。这篇文章就是冲着解决这些问题去的，从官网下载开始，到安装过程中的每个选项怎么选、为什么这么选，再到最后的 npm 全局配置和常见报错排查，一条龙讲清楚。适合完全没接触过 Node.js 的小白，也适合以前装过但一直没搞明白底层逻辑、想系统理一遍的开发者。
1. 先把话撂这：为什么这么多人卡在环境配置这一步
Node.js 说白了就是一个让 JavaScript 能在服务器端跑起来的运行时环境。以前 JavaScript 只能在浏览器里玩，有了 Node.js 之后，它就能读文件、连数据库、起 HTTP 服务、做后端接口，前端工程师靠一门语言通吃前后端就是从这个东西开始的。你要装各种前端构建工具（比如 Webpack、Vite）、跑本地开发服务器、用 npm 安装各种依赖包，前提都是先把 Node.js 装明白。
我接触过不少刚入门的朋友，下载安装其实挺顺的，就是一路 Next，但到后面用着用着就出问题。最常见的几种：
- 安装完打开命令行输
node -v，提示“不是内部或外部命令”。 - npm 装包特别慢，一个几 MB 的库能等好几分钟。
- 全局安装的工具（比如
npm install -g某个脚手架）装完之后，命令行里找不到这个命令。 - 重装系统后环境变量丢了，忘了之前是怎么配的。
这些问题大概率不是 Node 本身坏了，而是安装环节里几个“隐藏选项”没选对，或者环境变量没配对。这篇教程我尽量把每一个步骤后面的为什么讲清楚，你把原理搞明白了，以后不管换电脑、换系统还是帮别人装，都不至于两眼一抹黑。
2. 下载前必须先搞清楚的几个选择题
2.1 LTS 版还是 Current 版
进入 Node.js 官网，首页会有两个大按钮：左边是 LTS，右边是 Current。很多人不看说明随手就点右边的“最新版”，其实大多数情况下应该选 LTS。
LTS 全称 Long Term Support，意思是长期支持版。这类版本会持续收集 bug 修复和安全更新，稳定性优先，适合生产环境和绝大多数个人开发。Current 版本则是最新特性抢先体验版，功能新，但迭代快、API 可能有变化，主要用于尝鲜或某些必须依赖新特性的项目。
我的建议很直接：不管你是什么水平，默认下载 LTS 版本就对了。除非你明确知道某个新语法或新 API 只有在 Current 版本里才有，否则没必要去当小白鼠。用 Current 版本写业务代码，一个坑就是某个依赖库还没适配，装都装不上。
提示：LTS 版本号后面经常标注“Includes npm X.X.X”，意思是这个 Node 发行版自带了对应版本的 npm，不需要单独安装。
2.2 Windows 平台：MSI 安装包还是 ZIP 二进制包
Windows 系统下，官网下载区一般提供两种格式：.msi安装包和.zip压缩包。
大多数人不习惯用压缩包，因为解压完还得自己配环境变量，但又正因为这个原因，ZIP 包其实是“最干净”的安装方式。你把它解压到一个目录，然后把这个目录手动填进系统的 Path 环境变量，整个过程完全可控，卸载也方便——直接删文件夹、清环境变量就行。很多有经验的开发者喜欢这种方式，因为不怕安装器留下乱七八糟的注册表残留。
MSI 安装包则走的是向导式安装，下一步、下一步就行，它会自动帮你把 Node 添加进 Path，还会帮你配置一些可选组件。虽然安装器本身也会写注册表，但对常规使用来说没什么负担。
这篇教程主要讲 MSI 方式，因为它对新手更友好、更不容易出错。ZIP 方式我会在后面的环境变量章节单独说明，原理清楚了之后，冻结版、绿色版随你玩。
2.3 32 位还是 64 位
这个选择题现在越来越简单了：除非你的电脑是好几年前的老古董，否则一律选 64 位（x64）。
怎么确认系统位数？Windows 下按Win + I打开设置，进“系统 > 关于”里看“系统类型”。macOS 近几年的机型基本都是 64 位，不用纠结。下载的时候看清安装包文件名里带的是x64还是x86，选错了也能装，但是运行某些原生模块时会报架构不匹配的错，得不偿失。
2.4 系统自带的包管理器方案
如果你用的是 macOS，其实还有一条更省心的路：通过 Homebrew 安装。命令行执行：
brew install node@20这种方式会把 Node 二进制和相关工具统一装到 Homebrew 管理的目录里，升级也方便，执行brew upgrade node就完了。Windows 用户则可以用 winget:
winget install OpenJS.NodeJS.LTS不过这里我要说句实话：包管理器安装虽方便，但隐藏了一些底层细节，新手如果不知道它装到哪儿了，后面配置环境变量和排查问题会更难下手。所以这篇教程依然建议你先用官方安装包手动装一遍，等你理解了 Node 安装后的文件结构，再用包管理器会顺手很多。
3. Windows 系统下的 MSI 安装全程实操
3.1 下载并在本地找到安装包
打开 Node.js 官网，点 LTS 版本的下载按钮，浏览器会下载一个类似node-v20.x.x-x64.msi的文件。文件名里的版本号因人而异，以实际下载到的为准。
这里提醒一句：如果你的浏览器或安全软件对.msi文件弹出警告，检查一下是不是从官网下载的。只要域名是 nodejs.org，基本可以放心放行。下载完成后先别急着双击，向右键单击安装包选择“以管理员身份运行”。不这么做的话，后面安装到C:\Program Files目录时可能因为权限不足而失败。
3.2 安装向导每个界面的含义
双击安装包后，会依次看到几个界面，很多人一路 Next 就过去了，其实里面有些选项值得停下来看一眼。
Welcome 界面：直接 Next。
License 界面：勾选同意按钮，继续 Next。GPL 协议的东西我记得很清楚，开发本质上也确实受益于开源协议。
Destination Folder 界面：这是安装目录。默认是C:\Program Files\nodejs\。如果你 C 盘空间紧张，可以改成其他位置，但改完之后必须记住这个路径，后面排查问题要用。我一般推荐直接用默认路径，简单省事。
Custom Setup 界面：这里有个选项叫“Add to PATH”，一定要确保它是开启状态。Node 安装器默认勾选，但有些手欠的人会取消掉，最后发现命令行不认识 node。另外如果你用 VS Code，可以把“Install npm command Line tools”和“Install npx command Line tools”也选上，这俩是配套工具，建议默认全开。
接下来会问你是否安装“Node.js core modules”“npm package manager”“online documentation shortcuts”这些，默认全选即可。
Tools for Native Modules 界面：这个很容易被忽略，而且下面还跟着一段“自动安装 Python、Visual Studio Build Tools”的说明。这个选项是用来编译原生 Node 模块的，比如某些依赖 C++ 模块的 npm 包。选上它意味着安装器会额外调用一个脚本去下载 Visual Studio Build Tools 和 Python，整个过程很耗时，而且大概率要翻车——网络不好时会在这一步卡很久，或者装到一半报错。
我的建议是：新手直接取消这个勾选。绝大多数前端项目用不到编译原生模块，等你真的遇到node-gyp报错时再回来补装也不迟。装过一次你就知道，那条路比安装 Node 本身痛苦得多。
Ready to Install 界面：点 Install，开始安装。装完后默认会启动 Node.js 的文档快捷方式，不想要可以取消勾选。
3.3 安装完成后的第一眼检查
安装完成后，按Win + R，输入cmd回车，在命令行窗口里依次输入：
node -v npm -v正常情况下会分别打印出 Node 和 npm 的版本号，比如：
v20.12.0 10.5.0能打印版本号，说明安装成功，Path 也自动配好了。如果提示“不是内部或外部命令”，先别慌，大概率是环境变量没有生效，看下面几个章节。
4. macOS 系统下的安装与细节
4.1 pkg 安装包的完整流程
macOS 版官网下载的是一个.pkg文件，双击后弹出安装器界面。安装过程非常“苹果”，一路“继续”就行，直到出现“安装”按钮，它会要求你输入用户密码授权。
安装完成后，默认路径是：
/usr/local/bin/node /usr/local/bin/npm这里的/usr/local/bin通常已经存在于系统的 PATH 环境变量中，所以装完直接打开终端（Terminal 或 iTerm2），输入node -v就能看到版本号。
macOS 用户如果遇到node命令找不到，最常见的原因是装了 pkg 但终端重启过，或者系统用的 shell 是 zsh，缓存了之前的 PATH。解决办法很简单：关闭终端窗口，重新打开一个新窗口，再试一次。
4.2 nvm 方式安装的优势和步骤
如果你准备长期做前端或 Node 开发，我强烈推荐 macOS 用户通过 nvm（Node Version Manager）来管理 Node。它的最大好处是可以在同一台机器上同时安装多个 Node 版本，随时切换。比如某个老项目只支持 Node 14，你在 nvm 里装一个 14，再装一个 20，工作时执行：
nvm install 14 nvm install 20 nvm use 14一条命令就能切换。这是搞多项目开发时的神器。
安装 nvm 很简单，在终端里执行：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完 nvm 后，它会往你的 shell 配置文件里追加几行脚本。记得执行source ~/.zshrc让配置生效，然后：
nvm install --lts它会自动安装最新的 LTS 版本。后续用node -v验证即可。
Windows 用户也有 nvm-windows 这个工具，同样支持多版本切换，但我个人建议 Windows 新手还是先把官方安装包玩明白，不要一开始就上版本管理工具，否则概念太多容易乱。
4.3 macOS 下“已损坏”提示的说明
有部分用户从网盘或非官方渠道下载安装包时，macOS 的 Gatekeeper 会拦截并提示“已损坏，无法打开”。这通常不是文件真的损坏，而是系统安全策略不认这个来源。
解决办法有两种，一是在“系统偏好设置 > 隐私与安全性”里允许某个来源的应用，二是直接在终端执行：
sudo xattr -d com.apple.quarantine /路径/安装包.pkg然后再重新安装。不过我更建议：直接从官网下载，不给系统拦你的机会。
5. 环境变量的底层逻辑与 ZIP 包方式
5.1 PATH 到底是什么
很多教程讲到“配置环境变量”时都是一带而过，导致不少人只知道照着截屏操作，不知道为什么这么配。这里我用一个非常形象的类比说清楚。
PATH 环境变量，你可以理解成一张“命令通讯录”。当你打开命令行输入node的时候，系统并不会自己满硬盘去找这个程序，而是先查 PATH 里记录的目录列表，挨个找有没有一个文件叫node。找到了就执行，找不到就报“不是内部或外部命令”。
Node 的安装器自动帮你做的事情，就是把C:\Program Files\nodejs\这个目录写进了 PATH。如果你下的是 ZIP 包，这一步就得自己动手。
假设你把 ZIP 包解压到了D:\nodejs，那么操作如下：
- 右键“此电脑”，选择“属性”。
- 点击“高级系统设置”。
- 点击“环境变量”按钮。
- 在下方“系统变量”列表中找到
Path，双击它。 - 点击“新建”，输入
D:\nodejs，确定。
完成后打开新的命令行窗口，输入node -v，就能看到版本号。
注意：修改完环境变量后，已打开的命令行窗口不会自动更新 PATH，必须关掉重新开一个。很多“我明明配了为什么还报错”的案例，都是因为这个。
5.2 为什么 PATH 里会出现重复的 node 路径
用 MSI 安装且多次重装过 Node 的人，打开 PATH 一看可能会发现里面躺着好几条C:\Program Files\nodejs\。这在 Windows 下是常见情况，新安装会把相同路径再追加一次。虽然重复路径一般不会引发严重错误，但可能让某些工具在做路径解析时产生困惑，比如 nvm-windows 在切换版本时会因为多个 Node 路径存在而误判。
建议重装或升级前，先清理 PATH 里已有的 Node 相关条目，再执行新安装。
5.3 如何验证环境变量是否生效
除了node -v之外，还有一个更详细的命令可以看 Node 的完整执行路径：
where nodeWindows 下会输出一行路径，比如：
C:\Program Files\nodejs\node.exemacOS 或 Linux 下用：
which node如果这个路径和你预期的安装目录一致，说明 PATH 配置没问题。
6. npm 包管理器配置：镜像源与全局目录
6.1 npm 是 Node 自带的“软件商店”
Node 装好后，npm 会跟着一起安装。它叫 JavaScript 包管理器，作用就是你写项目时需要某个第三方库（比如 Vue、React、Express），不用跑去官网一个个下载，直接用：
npm install 包名npm 就会从远程仓库拉取这个包，存到项目的node_modules目录里。这个远程仓库默认的服务器在境外，国内访问速度时快时慢，尤其是一些体积较大的包，下载体验很不稳定。这就是为什么很多人反映 npm 装包慢。
6.2 更换镜像源的正确姿势
解决办法是换一个更快的下载源。国内常用的是淘宝镜像，它的全称叫 npmmirror。在命令行执行：
npm config set registry https://registry.npmmirror.com这条命令的意思是：把 npm 的默认下载源改成 npmmirror 提供的镜像地址。设置完后验证一下：
npm config get registry会输出：
https://registry.npmmirror.com说明镜像切换成功。之后安装包的速度会明显提升。
如果你想换回官方源，执行：
npm config set registry https://registry.npmjs.org/顺便说一句，在某些团队内部会使用私有的 npm 仓库，配置方式同样是修改 registry。原理都一样，只是地址不同。
6.3 自定义全局安装路径
npm 支持全局安装工具，比如：
npm install -g nodemon这里-g表示全局安装，工具会被放到一个全局目录里，然后命令行里随时能调用。默认情况下，Windows 的全局目录是C:\Users\你的用户名\AppData\Roaming\npm，macOS 则是/usr/local/lib/node_modules。
如果你不想让这些工具堆在 C 盘，可以手动改路径。Windows 下在项目目录或用户目录新建一个文件夹，比如D:\node_global，然后执行：
npm config set prefix "D:\node_global"同时需要把这个目录加进 PATH，步骤同 5.1 节。这样后面全局安装的工具都会进这个目录，方便统一管理。
macOS 下也可以改 prefix，但我还是建议 macOS 用户直接用 nvm，因为 nvm 会自动管理全局工具的路径，省心得多。
6.4 cnpm 值得装吗
以前很多教程喜欢推荐装 cnpm——它是淘宝镜像团队出的一个 npm 替代客户端。但现在的实际情况是：直接用 npm + 切换 registry 就已经足够，cnpm 的意义越来越小。而且 cnpm 在某些场景下会出现文件结构不一致、锁定文件不兼容的问题，反而添乱。
我的建议很明确：别再单独装 cnpm 了，直接改 registry 就行。
7. 高频问题排查与避坑经验
7.1 “不是内部或外部命令”的三种原因
这是一条最高频的报错信息，看起来像世界末日，其实原因就那么几个。
第一，Node 根本没装上。检查一下C:\Program Files\nodejs\是否存在，不存在就是安装失败或装到了别处。
第二，PATH 没配好。按第 5 章方法打开环境变量确认nodejs目录是否在 Path 里。如果 Path 里有但命令行仍然报错，尝试打开一个新的命令行窗口再试。
第三，安装后没重启电脑。某些 Windows 版本对系统环境变量做了优化，新装的 PATH 不需要重启就能生效，但依然有例外。实在不行就重启一次。
7.2 npm 提示无法加载、或者提示禁止运行脚本
Windows 下执行某些 npm 脚本时可能遇到：
npm : 无法加载文件 C:\...\npm.ps1，因为在此系统上禁止运行脚本这是因为 PowerShell 的执行策略默认限制了脚本运行。解决办法：以管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy RemoteSigned输入Y确认。这个命令的意思是允许本机创建的脚本运行，同时要求远程下载的脚本必须有数字签名。对开发者来说安全性足够，也不会影响日常使用。
7.3 安装原生模块时报 node-gyp 错误
如果你执行某条 npm install 忽然冒出node-gyp、python、Visual Studio Build Tools之类的字眼，说明你要装的包里含有需要本地编译的 C++ 模块，最常见的是node-sass、bcrypt等老牌库。
回到第 3.2 节讲过的“Tools for Native Modules”的选项，这时候才需要补足编译环境。安装 Visual Studio 的“使用 C++ 的桌面开发”工作负载，以及 Python 3.x，然后再重试装包。但是这里我个人劝你别硬拼环境，优先看看有没有替代包。比如node-sass直接换sass，bcrypt 用纯 JS 的bcryptjs在多数业务场景足够用，省去一大串编译烦恼。
7.4 npm 版本和 Node 版本不匹配
用了一段时间后你会发现npm -v的版本可能跟 Node 自带的不太一样，因为你可能单独升级过 npm。升级 npm 的命令是：
npm install -g npm@latest但这里有个风险：太新的 npm 可能不再支持你当前较老的 Node 版本。如果你遇到 npm 运行报错、命令无法识别，或者某个功能不支持，先检查一下 npm 版本和 Node 版本的兼容性。通常来说，官方会把某个 npm 版本对应某个 Node 版本区间，别盲目升到 latest。
7.5 关于版本管理器 nvm-windows 的一点提醒
如果你想在 Windows 上使用 nvm-windows 做多版本切换，先卸载已安装的 Node，再安装 nvm。否则两个工具会同时往 PATH 里写 Node 路径，互相干扰。
nvm-windows 的常用命令：
nvm list # 查看已安装版本 nvm install 20 # 安装 Node 20 nvm use 20 # 切换当前版本切换版本后，用node -v验证。这个工具适合需要同时维护多个项目的开发者，不建议新手入门就碰它。
7.6 掌握 Node 安装目录的文件结构
最后再分享一个“无用但有用”的知识。打开C:\Program Files\nodejs\目录，你能看到node.exe、npm.cmd、npx.cmd这些文件。node.exe是真正的运行时主程序，npm.cmd是 npm 的 Windows 批处理入口，npx.cmd则是用来执行仓库内包的。
看到这些文件之后，再看 PATH 配置，就不会觉得玄学了——系统就是在这一堆文件里找名字叫 node、npm、npx 的入口而已。哪天你误删了某个文件，导致命令异常，去这个目录对照一下就大概率能找到原因。就像家里抽屉里放着什么钥匙，心里有个数，拿哪个开哪个门就不会慌。
说到底，Node.js 的安装难点不在“下一步”，而在理解它在系统里是怎么被找到、怎么被组织的。把环境变量、镜像源、全局目录这几点弄明白，往后无论是换新电脑重装、还是给团队新同学指导，都不会再有“跟着教程走了一半突然不知所措”的情况。
