装 Node.js 这件事，说简单也简单，官网拖个安装包一路下一步就完事；说麻烦也麻烦，我这些年见过太多人卡在几个固定位置：命令行敲node -v提示“不是内部或外部命令”，npm i -g报权限不足，用版本管理器切换之后全局包集体失踪，还有 PowerShell 里怎么都跑不起 npm。这些问题九成不是 Node.js 本身的问题，而是下载渠道、安装方式、环境变量配置这三步里有一环没对齐。这篇就把 Node.js 下载安装及环境变量配置这条链路从头到尾拆一遍，讲清楚每一步在做什么、为什么这么做、做错了会怎样。无论你是第一次配开发环境的新手，还是手上带着几个项目、需要在多个 Node 版本之间来回切的熟手，下面这些内容都能直接照着抄。我会按 Windows 为主线展开，再补上 macOS 和 Linux 的等价操作，最后给一份我常年积累的排查速查表。
1. 动手之前先想清楚的三件事
很多人装环境失败，不是因为操作错，而是因为一开始就没想清楚要装哪个版本、用哪种方式装、装完放哪里。这三件事一旦定了，后面的步骤其实是机械劳动；定错了，后面全是补丁。
1.1 版本线怎么选：LTS 还是 Current
Node.js 的发版节奏非常规律：每年 4 月左右发一个大版本，10 月左右把其中一个版本转入长期支持（LTS）。版本号是偶数的大版本会进入 LTS 轨道，奇数版本基本是尝鲜线，生命周期短，官方不承诺长期维护。这个设计很像手机系统的稳定版和开发者预览版——预览版能让你第一时间用上新语法，但代价是你得自己承担生态兼容性风险。
我的建议非常直接：生产环境、日常开发、学习练手，一律选 LTS。理由有三个。
第一，生态兼容性。绝大多数 npm 包在发布时是以 LTS 版本作为最低验证基线的，你用一个刚发的 Current 版本，很可能撞上某个依赖还没适配，报一堆莫名其妙的内存错误或者 API 不存在。
第二，问题可搜索性。LTS 版本的用户基数最大，你踩到的坑大概率已经有人踩过并写了答案；用尝鲜版本遇到问题时，搜出来的资料可能一片空白。
第三，升级成本可控。LTS 有明确的维护窗口，主动维护期加维护期算下来通常有两三年，你可以从容规划升级节奏，而不是被版本停更逼着临时抱佛脚。
具体选哪一条 LTS 线，我一般看两点：如果项目依赖里有明确写着engines字段的，按它来；如果是新项目，选当前处于“Active LTS”状态的偶数版本，比如某个时期是 v22 系列，过一段时间 v24 接棒，以此类推。判断方法很简单，去官方下载页看那个绿色的 LTS 标记，别自己猜。
注意：不要因为“新版本性能更好”就盲目上大版本。Node.js 大版本之间会有 API 废弃和能力变更，比如某些内置模块的行为调整、默认参数改变，这类变更在中小项目里往往不会立刻报错，而是在某个边角路径上静默出错，排查成本极高。
还有一种情况要多说一句：如果是接手一个已经存在的项目，第一件事不是装最新版，而是去翻项目根目录有没有.nvmrc、.node-version、package.json里的engines字段，或者 CI 配置文件里写死的版本号。这些文件才是这个项目的“真实版本要求”，按它来装，能省掉大量“我这能跑你那不能跑”的扯皮。
1.2 四种安装方式的取舍：安装包、压缩包、版本管理器、系统包管理器
同样是装 Node.js，至少有四条路可走，各自的适用场景差别很大。我做个对比表，你可以对号入座。
| 方式 | 具体形态 | 优点 | 缺点 | 适合谁 |
|---|---|---|---|---|
| 官方安装包 | Windows 的 .msi、macOS 的 .pkg | 图形向导，自动写 Path，一次到位 | 卸载有残留，换版本要重装 | 只用一个版本、追求省事的人 |
| 免安装压缩包 | .zip / .tar.gz 解压即用 | 不写注册表，卸载就是删目录，可多版本并存 | 环境变量要手动配，容易漏 | 想把环境完全掌控在自己手里的人 |
| 版本管理器 | Windows 上的 nvm-windows，跨平台的 fnm、n | 一条命令切版本，多项目并行不冲突 | 初始化有坑，全局包按版本隔离 | 手上同时有多个项目的开发者 |
| 系统包管理器 | Debian 系的 apt、RedHat 系的 dnf、macOS 的 brew | 与系统更新体系统一，命令简单 | 版本往往滞后，且不便于切换 | 服务器部署、容器镜像构建 |
新手我一般推荐官方安装包起步，先把“能跑起来”这件事完成，建立正反馈；等你手上出现第二个需要不同 Node 版本的项目时，再切到版本管理器。反过来，如果你一上来就用版本管理器，遇到问题时你分不清是 Node 的问题还是管理器的问题，排查会变得很痛苦。
我的实操心得是：不管用哪种方式，都别把 Node.js 装到带中文、带空格的路径下。Windows 上默认的
C:\Program Files\nodejs\里那个空格，历史上坑过无数构建工具；而中文路径在某些旧工具链里会直接导致乱码或找不到文件。给自己留个干净的D:\dev\nodejs之类的目录，后面少掉一半麻烦。
1.3 装之前先清理：残留才是万恶之源
这一步很多人跳过，然后花两小时排查一个本来五分钟就能解决的问题。如果你电脑上之前装过 Node.js，或者装过其他方式安装的 Node.js，先彻底清干净再装新的，否则会出现“命令行里的 node 跟你以为的 node 不是同一个”这种见鬼现象。
清理清单如下，Windows 上逐项确认：
- 控制面板卸载列表里所有名字带 Node.js 的条目；
- 删掉安装目录残留，默认是
C:\Program Files\nodejs； - 删掉全局包目录残留，默认是
C:\Users\<用户名>\AppData\Roaming\npm和npm-cache； - 打开“环境变量”窗口，检查用户变量和系统变量的
Path里还有没有指向旧 Node 目录的条目，有就删掉； - 如果你安装过 nvm-windows，它自己的目录（默认在用户目录下）也要一并处理。
macOS 和 Linux 上对应的是/usr/local/bin/node、/usr/local/lib/node_modules、/opt/homebrew下的相关软链，以及~/.npmrc里遗留的prefix配置。
提示：清理完之后一定重开一个终端窗口再验证。环境变量是进程启动时读取的，已经开着的终端不会自动刷新，你在旧窗口里验证出来的结果没有参考价值。
2. 环境变量到底在配什么
“配置环境变量”这六个字，是新手最容易照抄但最不明白的一步。抄对了没事，抄错一个分号就要命。所以这一节我不讲怎么点鼠标，先讲清楚它在背后干什么。
2.1 Path 的工作机制：命令行是怎么找到 node 的
你在终端敲下node按下回车，系统做的事其实很朴素：它拿到“node”这个字符串，然后沿着Path环境变量里记录的每一个目录，挨个进去找有没有叫node（Windows 上还要找node.exe、node.cmd、node.ps1等）的文件。找到第一个就执行，找不到就报“不是内部或外部命令”。
这个机制的关键点是顺序敏感，先到先得。所以如果你电脑里有两个 Node 目录都在 Path 里，排在前面那个生效。这也是为什么“我明明装了新版本，怎么还是旧的”这类问题的答案往往是：旧目录排在 Path 前面。
用一个生活化的类比：Path 就是一张写着若干地址的清单，你在前台报一个名字，前台按清单顺序一家家打电话，第一家有人接就完事，不会继续往后打。理解这一点，后面所有跟“命令找不到”“版本不对”相关的问题都能自己想明白。
Windows 上的环境变量分两层，这个必须说清楚：
- 用户变量：只对当前登录账号生效，修改通常不需要管理员权限。个人开发机优先用这个。
- 系统变量：对所有账号生效，改它需要管理员权限，而且容易影响其他软件。
我的习惯是：Node 相关的路径一律只改用户变量里的Path，不动系统变量。这样既避免了权限问题，也不会在你换账号或者给别人用这台机器时留下隐患。
验证顺序的时候，Windows 用where node（会按 Path 顺序列出所有匹配项），macOS 和 Linux 用which -a node。这两个命令是排查版本冲突的第一把武器，记住它。
2.2 prefix 与 cache：为什么全局装的包“找得到装不上”
很多人以为 Node.js 装完就完事了，其实还有两个目录要关心：npm 全局包目录（prefix）和缓存目录（cache）。这两个不配好，后面会定期给你制造麻烦。
先解释概念。npm i -g xxx装出来的包，不是塞进 Node.js 的安装目录，而是装到 npm 的全局前缀目录里，然后在这个目录下生成一个可执行文件（Windows 上是.cmd脚本，Unix 上是软链）。你敲xxx命令的时候，系统还是去 Path 里找，所以prefix 目录必须出现在 Path 里，否则包装了但命令用不了，这就是“装了但没装”的经典现象。
默认值长这样：
| 项目 | Windows 默认位置 | macOS / Linux 默认位置 |
|---|---|---|
| Node 可执行文件 | C:\Program Files\nodejs\ | /usr/local/bin/或 brew 的 prefix |
| npm 全局 prefix | C:\Users\<用户名>\AppData\Roaming\npm | /usr/local/lib/node_modules |
| npm 缓存 cache | C:\Users\<用户名>\AppData\Local\npm-cache | ~/.npm |
| 用户级 npmrc | C:\Users\<用户名>\.npmrc | ~/.npmrc |
为什么建议改成自定义目录？三个理由：
- 空间：缓存目录会随着项目依赖不断膨胀，几百兆到几个 G 都正常，扔在系统盘迟早要清；
- 权限：macOS 和 Linux 上
/usr/local/lib通常属于 root，普通用户往里写就要sudo，而sudo npm i -g会带来一堆文件属主错乱的后遗症； - 可迁移：环境全放在一个自己指定的目录下，换机器直接打包拷走，或者干脆用同步盘管理。
注意：改完
prefix之后，一定要把新的 prefix 目录追加进Path，并且关闭所有终端重新打开。我见过太多次改完 npmrc 就急着验证、结果报错说命令不存在的情况，纯粹是因为旧终端的环境变量快照没更新。
缓存的清理也不用太担心误删，它本质上是包 tarball 的本地副本和部分索引信息，删了下次装依赖会重新下载，不影响已装的东西。定期跑npm cache verify让 npm 自己校验并整理就够了，实在撑爆了再用npm cache clean --force。
3. Windows 平台完整实操：从安装向导到命令验证
这一段是纯操作，跟着做就行。我会把向导里每个勾选框的含义讲清楚，因为那三个勾选框勾错任意一个，后面的路都会变长。
3.1 安装向导里那三个勾选项，各自负责什么
从官方下载页拿到.msi之后双击，前面的许可协议、安装路径按需改。真正需要你判断的是“Custom Setup”这一步的三项：
第一项，Node.js runtime。核心运行时，必须装。它决定了安装目录里有node.exe。
第二项，npm package manager。这是 npm 的命令行工具，也几乎是必勾。虽然技术上你可以装完 Node 再手动搞 npm，但没有任何理由这么做。
第三项，Add to PATH。这一项是重点。勾上，安装程序会自动把 Node 安装目录写进用户变量的Path，你装完直接就能用命令；不勾，你就得手工配，而且很容易配错。默认是勾上的，别手贱取消。
至于向导最后出现的“Tools for Native Modules”提示（会问你愿不愿意顺带装编译原生模块所需的构建工具），这个按需处理。如果你只是写业务代码、装纯 JS 的包，不勾也没问题；如果你确定要用到需要本地编译的依赖（这类包会在安装时打印一堆 Python、编译器的报错），勾上能省事，但它会额外下载安装一坨东西，耗时较长。我的一般做法是：先不勾，等真的遇到编译失败再回来补。
装完之后，必须新开一个终端，然后依次验证：
node -v npm -v where node where npm前三行输出正常，说明运行时和 npm 都在位。where node的输出应该指向你刚才的安装目录，如果不是，说明 Path 里有别的 Node 排在前面，回去按 1.3 的清单清理。
3.2 手工配置环境变量：图形界面与命令行两种改法
如果安装时没勾 Add to PATH，或者你要把 prefix 目录也加进去，就需要手工操作。
图形界面的路径是：此电脑右键 → 属性 → 高级系统设置 → 环境变量 → 在“用户变量”区域选中Path→ 编辑 → 新建 → 粘贴目录路径 → 一路确定。注意是新建一行，不是直接在已有字符串末尾粘，Windows 10 之后的编辑器是按行编辑的，直接拼字符串极容易漏分号。
命令行方式（管理员权限的 PowerShell 或 CMD）适合批量操作，但有个坑必须先说：
# 只追加单个目录，相对安全 [Environment]::SetEnvironmentVariable( "Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";D:\dev\nodejs\node_global", "User" )为什么不用常见的setx PATH "%PATH%;xxx"？因为%PATH%展开的是当前进程的 Path，它包含了系统变量和用户变量合并后的结果，你把它整个写回用户变量，等于把系统变量的内容复制了一份进用户变量，路径会越来越长，最终超过长度限制被截断，那才是真正的灾难。用上面这种按 User 作用域读取再写回的方式，只动用户变量本身，安全得多。
配完之后同样要重开终端，用echo %Path%（CMD）或$env:Path（PowerShell）确认路径真的进去了。
我的实操心得：改环境变量之前，先把当前的
Path内容复制一份存到记事本里。这不是迷信，是我真的见过有人把 Path 清空之后找不到北。有备份，最坏情况五分钟还原；没备份，可能要重装系统级别的折腾。
3.3 迁移全局目录并做完整功能验证
这一步是把 prefix 和 cache 挪到你自定义的位置，我以D:\dev\nodejs\node_global和D:\dev\nodejs\node_cache为例。
先建目录，然后写配置：
mkdir D:\dev\nodejs\node_global mkdir D:\dev\nodejs\node_cache npm config set prefix "D:\dev\nodejs\node_global" npm config set cache "D:\dev\nodejs\node_cache"这两条命令做的事，是在用户级配置文件C:\Users\<用户名>\.npmrc里写入两行。你可以直接打开这个文件确认，内容大概长这样：
prefix=D:\dev\nodejs\node_global cache=D:\dev\nodejs\node_cache然后把这行配置验证出来：
npm config get prefix npm config get cache最后的关键一步：把D:\dev\nodejs\node_global加进用户变量的Path（如果安装目录D:\dev\nodejs还没在里面，也一起加）。加完重开终端，做一次端到端验证——装一个带命令行入口的小工具，看它能不能被调用：
npm install -g http-server http-server --version能打印出版本号，说明“下载 → 安装到 prefix → 生成可执行文件 → Path 能找到 → 命令可执行”整条链路是通的。这一步过了，你的 Node 环境基本不会再出结构性问题。
关于 registry 源，如果你所在网络访问默认源较慢，可以在.npmrc里加一行registry=指向一个稳定维护的公共镜像地址，或者公司内部的私有源。这件事本身没有技术难度，但要注意：源是可以按项目覆盖的，项目根目录下如果有.npmrc，它的优先级高于用户级配置。所以“我全局换了源，怎么这个项目还是慢”的答案通常就在项目目录里。
4. macOS 与 Linux：等价操作与几个专属陷阱
Unix 系系统上装 Node.js，路子更野，坑也更隐蔽。核心差异在于权限模型和 shell 配置文件的加载顺序。
4.1 三种常见装法与权限陷阱
用官方 .pkg 安装包：双击一路下一步，它会装到/usr/local/bin，并且自动处理好路径。缺点同样是换版本要重装，卸载也不算干净。
用 Homebrew：命令就一条，brew install node。优点是跟系统包管理体系一致，升级方便；缺点是 brew 装的 node 路径在/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel），而且 brew 的 node 会连带装一堆依赖，卸载时要注意brew uninstall node之后可能还有残留的 formula。
用版本管理器 nvm 或 fnm：这是我个人最推荐的方式。以 nvm 为例，安装脚本会往你的 shell 配置文件里追加一段初始化代码，然后：
nvm install --lts nvm use --lts nvm alias default lts/* node -vnvm alias default这一步很关键，它决定了你新开终端时默认用哪个版本。不设的话，每次新窗口都是“没有 node 可用”的状态，你会以为装失败了。
权限陷阱是 Unix 系独有的大坑。默认情况下全局包目录在/usr/local/lib/node_modules，普通用户没写权限，于是很多人条件反射地加sudo：
sudo npm install -g some-cli # 不要这么干这么干的后果是：全局目录里出现一批属主为 root 的文件，之后你不加 sudo 就再也装不了、升级不了、卸载不了，报EACCES。正确的做法是把 prefix 改到用户目录下：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后在~/.zshrc或~/.bashrc里加一行：
export PATH="$HOME/.npm-global/bin:$PATH"source ~/.zshrc生效，之后所有全局安装都不需要 sudo。
注意：如果你的全局目录已经被 sudo 污染了，先修复属主再改配置：
sudo chown -R $(whoami) /usr/local/lib/node_modules /usr/local/bin。光是改 prefix 并不能解决历史遗留文件的权限问题，那些文件会一直在那里碍事。
4.2 shell 配置文件到底该写哪一个
这个问题在 mac 上尤其容易搞混，因为终端默认 shell 换过一代。判断方法很简单：
echo $SHELL输出/bin/zsh就往~/.zshrc里写，输出/bin/bash就往~/.bash_profile（登录 shell）或~/.bashrc（交互式非登录 shell）里写。拿不准就两个都写一份，重复 export 不会出错，只是 Path 里多一条冗余记录。
Linux 服务器上还有个常见场景：你用 SSH 登录后node -v正常，但写进 crontab 或者用 systemd 跑的服务里就找不到 node。原因是这些非交互式环境不加载.bashrc。解决办法不是去改 crontab 里的 Path 字符串（那种写法又丑又难维护），而是把 node 装到一个全局可见的位置，或者在服务配置里显式声明环境变量。
# systemd 服务片段示例 [Service] Environment="PATH=/usr/local/bin:/usr/bin:/bin" Environment="NODE_ENV=production" ExecStart=/usr/bin/node /srv/app/index.js这种方式的好处是把运行环境写死在配置里，不依赖任何登录 shell 的状态，可复现性最强。
5. 常见问题与排查技巧实录
下面这张表是我这些年被问得最多的问题集合，基本都是环境配置层面的，按现象、原因、处理方式三列整理。遇到问题时先对号入座，能省掉大量瞎试的时间。
| 现象 | 根本原因 | 处理方式 |
|---|---|---|
node不是内部或外部命令 | 安装目录不在 Path，或 Path 改了没重开终端 | 检查用户变量 Path，重开终端，where node验证 |
npm能用但全局装的命令用不了 | prefix 目录没进 Path | npm config get prefix拿到路径，加进 Path |
npm i -g报 EACCES / EPERM | 全局目录无写权限 | 改 prefix 到用户目录，别用 sudo |
| 版本号跟装的版本对不上 | 多个 Node 在 Path 里，旧的排在前面 | where node找全部，删掉多余条目 |
| PowerShell 里 npm 报“禁止运行脚本” | 执行策略限制了.ps1脚本 | Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
| 安装依赖卡住或超时 | 网络到源不稳，或代理配置残留 | 换 registry，清proxy/https-proxy配置 |
| 卸载重装后问题依旧 | 全局目录、缓存、npmrc 残留 | 按 1.3 清单逐项清理 |
| 切版本后全局包全没了 | 版本管理器的全局目录按版本隔离 | 每个版本重新装，或用统一的 prefix |
挑几个重点展开说。
PowerShell 执行策略这一条，坑过的人特别多，因为报错信息看起来完全跟 Node 无关。现象是：CMD 里npm -v正常，PowerShell 里就报一长串红字，说无法加载npm.ps1。原因是 Windows 上 Node 安装目录里同时放了npm、npm.cmd、npm.ps1三个文件，PowerShell 优先解析.ps1，而系统默认执行策略禁止运行本地脚本。改法就是上面那行命令，把当前用户的策略设为RemoteSigned（本地脚本可跑，远程下载的脚本需要签名），影响范围仅限当前用户，比改机器级策略稳妥。
“切了版本全局包没了”这一条，本质是设计如此，不是 bug。版本管理器为了隔离，会为每个 Node 版本维护独立的全局目录。所以要建立正确的心理预期：全局工具不是跟着你走的，是跟着版本走的。缓解办法有两个：一是尽量少装全局包，能用npx临时跑的就别装；二是用package.json里的 devDependencies 加 npm scripts 来固化项目级工具，这样版本一换也不受影响。
“我明明装的是新版本”这一条，排查路径固定三步：where node看有几条、看顺序；node -v看实际生效版本；打开“环境变量”窗口，逐条读 Path 的内容，找那些早已不存在的路径（指向已删除目录的 Path 条目不会报错，但会拖慢命令查找，也是个隐患，顺手清掉）。
还有个隐蔽的坑值得单独提：路径里带空格。
C:\Program Files\nodejs这个默认路径在 99% 的场景下没问题，但某些老旧的构建脚本在拼接命令字符串时不会加引号，一遇到空格就断成两截，报“找不到 C:\Program”。如果你遇到这类看起来毫无道理的构建报错，把 Node 装到无空格路径（比如D:\dev\nodejs）是最省事的解法。
6. 多版本共存与长期维护的几个实用做法
当你的机器上开始同时存在两三个项目的不同 Node 版本需求时，环境管理就从“一次性劳动”变成了“长期运营”。这一段讲讲我目前的实际做法。
6.1 版本管理器的选型与初始化要点
Windows 上主流选择是 nvm-windows，跨平台可用的是 fnm 和 n。选型的核心考量不是功能多少，而是初始化是否顺畅和切换速度。nvm-windows 用 Go 写的，切换本质上是改软链，速度一般；fnm 用 Rust 写的，切换快很多，但生态资料相对少一些。
用 nvm-windows 有几个必须知道的点：
- 安装前必须先卸载已有的 Node.js，并且删干净目录。它是靠替换软链的方式工作的，带着旧安装进去必然冲突。
- 安装路径不要有空格，默认装在用户目录下就行。
nvm use需要管理员权限，因为它要改软链。普通终端里会报“exit status 1”，网上很多教程让你反复重装，其实只是权限问题。- 全局包按版本隔离，前面说过，接受它。
常用命令序列：
nvm list available # 看有哪些版本可装 nvm install 22.14.0 # 装指定版本 nvm use 22.14.0 # 切换（需管理员终端） nvm list # 看已装版本和当前生效版本 nvm uninstall 18.20.0 # 卸载某个版本切换之后同样要重开终端验证，node -v和npm -v都确认一遍。
6.2 团队统一与长期维护清单
个人环境配好只是开始，如果这个环境要跟别人协作，还得让它可复现。我的做法是在项目根目录放一个.nvmrc，里面只写版本号：
22.14.0团队成员nvm use会自动读取。这比在文档里写“请用 Node 22”可靠一百倍，因为文字描述会过期，文件不会。
再进一步，把包管理器版本也固定下来。较新的 Node 版本内置了 corepack，可以在package.json里声明：
{ "packageManager": "pnpm@9.15.0" }这样别人 clone 下来之后，工具链版本和你的一致，不会出现“我这边 lockfile 格式不一样”的问题。要注意 corepack 在不同 Node 版本里的默认可用性有差异，用之前先corepack --version确认一下，没有的话单独装。
最后给一份我自己定期执行的维护清单，你可以直接抄：
- 每季度看一眼当前 LTS 版本，评估是否要跟进；
- 跑一次
npm cache verify，缓存目录超过 5G 就清； - 检查
~/.npmrc，把过期的 registry、失效的代理配置删掉； - 检查 Path，清理指向已删除目录的条目；
- 项目级的
engines字段与实际使用的版本对齐，别让文档和现实脱节。
这套流程跑下来，一台机器维护个三五年不出结构性问题是没问题的。真正让环境变脏的从来不是 Node.js 本身，而是反复随手的临时改动——今天加一条 Path，明天用 sudo 装一个包，后天手动删个目录，半年后你自己都不知道这台机器上到底有几个 node。把配置入口收敛到少数几个文件里（.npmrc、.nvmrc、shell 配置），其他的都别动，这是我踩了足够多坑之后最认可的一条经验。
