第一次装Node.js的人，十个里有八个会栽在环境变量上。装完在命令行敲node -v，系统提示“不是内部或外部命令”；npm install完一个全局工具，转头用的时候又找不到命令。这些现象我在各种电脑上见过无数次，根子往往不是安装本身出了问题，而是安装方式选错、环境变量没配对、版本概念没搞清。Node.js说到底就是一个让JavaScript能跑在服务器端的运行时环境，前端开发靠它跑构建工具，后端开发靠它写接口服务，桌面端工具链也离不开它。
2024年这个时间点，Node.js的版本线已经更新到22.x，生态成熟得不能再成熟，但“装好”和“用好”之间，还隔着一整套下载、安装、路径配置、镜像加速、版本管理的学问。这篇就把从0到1的整个过程拆开讲清楚，哪个步骤干什么、为什么这么干、出现问题怎么定位，全部说透。适合谁看？刚入门的前端同学、要从零搭开发环境的后端同事、以及那些“装了三次Node都没配好”的老手。内容以Windows为主，macOS和Linux的关键差异也会顺带提到。
1. 装Node.js之前，先把版本和安装方式的账算清楚
1.1 LTS与Current：版本号里藏着的选择逻辑
打开Node.js官网首页，通常会有两个下载入口，一个标LTS，一个标Current。新手最容易犯的错是哪个新点哪个，看到Current版本号数字更大、年份更新就点了。这个选择很关键，建议在下载之前先把版本发布规则弄清楚。
Node.js的版本发布一直遵循一个稳定节奏：偶数主版本会进入LTS长期支持，奇数主版本作为试验性的Current版本。以2024年为例，v22.x是当年的LTS主线，v23.x属于Current活跃版。LTS的意思是这个版本会持续获得最长30个月的安全与稳定性补丁，适合所有生产环境、日常开发和课程项目。Current版本则优先吸收新特性，代价是API可能调整、某些第三方依赖库还没跟上，拿它跑正式项目，很容易被上游改动坑到。
我的建议很直接：除非你有明确理由要用新特性，否则一律选LTS。什么算明确理由？比如你要验证某个新API，或者项目依赖里明确写着“Requires Node >= 23”。版本号本身的规则也值得了解，Node.js采用语义化版本三段式命名：主版本.次版本.补丁版本。主版本号变化代表不兼容的大改动，次版本号增加代表在既有功能上加了新东西，补丁号是修复问题。看到“Node 20.10.0有个bug，升级到20.11.0修复”这类信息，就知道只需要动最后一位。
| 版本线 | 定位 | 推荐使用场景 |
|---|---|---|
| 偶数版（20.x/22.x） | LTS长期支持 | 生产环境、正式项目 |
| 奇数版（21.x/23.x） | Current试验版 | 尝鲜新特性、跑新库 |
1.2 三种安装方式与它们各自的适用人群
Node.js的安装方式大体分三类：官网官方安装包、系统包管理器、版本管理器。这三类不是谁替代谁的关系，而是适用场景不同，选错会直接导致后续维护很痛苦。
官方安装包是最省心的方式。Windows下是.msi格式，macOS下是.pkg，Linux下是预编译的tar.xz。安装向导会帮你完成绝大多数配置，PATH也会在勾选后自动写入。适合的人群是：只在电脑上装一个Node、不打算频繁切换版本、不想接触命令行脚本的普通开发者。
系统包管理器适合本来就很习惯用包管理器维护软件的人。macOS的Homebrew、Linux的apt和dnf，一条命令就能装好，升级也统一。但缺点很明显：系统仓库里的Node版本通常比官方慢几个小版本，有时候还停留在旧主版本，包管理器升级整台系统时也可能连带改变Node版本，导致项目环境不稳定。
版本管理器是三个方案里我最推荐的。Windows用nvm-windows，macOS/Linux用nvm。它能装任意多个Node版本，随时切换，还能按项目固定版本。很多人一开始觉得多此一举，等遇到“老项目要Node 16、新项目要Node 22”的时候，才知道版本管理器有多香。它唯一的要求是你愿意多学几个命令。
1.3 环境变量：为什么装完必须“配”一下
无数教程把“配置环境变量”描述成一个神秘仪式：装完没反应，就打开系统属性、高级、环境变量，一顿操作，然后就好了。但如果你不理解为什么，后面遇到变体问题依然会懵。
Windows在执行命令时，会在当前目录和PATH环境变量列出的目录里逐个查找可执行文件。你装了Node.js，它的node.exe和npm相关脚本位于安装目录下，如果这个目录没有出现在PATH中，系统在别的路径下就找不到它。在命令行敲node -v报“不是内部或外部命令”，本质就是“系统不知道node.exe在哪里”。
所以“配置环境变量”翻译成人话，就是把Node.js里存放可执行程序的目录告诉操作系统。理解了这一点，你会发现所谓配置其实很简单：找到目录，加进PATH，完事。环境变量里还有一类叫NODE_PATH的变量，用来指定模块查找的全局目录，普通场景基本用不到，但很多教程会煞有介事地让你配。我建议先忽略它，除非你明确知道自己在做什么。
2. Windows端下载安装全流程：每一步都要看明白
2.1 从官网下载安装包的完整步骤
Windows用户装Node.js，第一步去官网。打开后页面正中会有两个醒目的下载入口，左侧写的是LTS版本，右侧写的是Current。我的建议前面说过了，选LTS。
进入LTS的下载页，找到Windows Installer (.msi) 64位的链接。怎么确认电脑架构？右键“此电脑”选“属性”，看系统类型，x64就是64位，x86选32位。2024年的电脑基本没有32位，这个确认步骤多数人可以直接跳过，但我的建议是既然看到了，顺手看一眼。
为什么强烈推荐.msi而不是.zip？.msi是Windows安装器格式，安装时会写入注册表、自动配置PATH、注册卸载信息，之后卸载也干净。.zip免安装版看着简单，解压完一堆配置全得手动，环境变量、文件关联、右键菜单一样不能少，漏一个就埋一个雷。除非你只是临时用一下，否则别碰zip。
下载时留意一下文件大小，Node.js官方.msi安装包一般在25MB到35MB之间。如果某网站给你的“官方安装包”只有几百KB，或者让你先装个下载器，关掉，那不是官网。下载完成后双击.msi，Windows可能会出现“是否允许此应用更改设备”的UAC提示，确认文件来源后点是。有些版本Windows会提示“未知发布者”，只要文件名、来源网址对得上，基本可以放心。官方签名的文件通常会有有效的数字签名信息。
2.2 安装向导里的选项怎么勾
.msi安装向导大概有几步，真正需要你动脑的主要是Custom Setup和Tools for Native Modules。
Custom Setup这一步让你选安装组件，默认是Node.js runtime、npm、以及配套的文档和工具。保持默认这里就行，但安装路径建议改一下。默认路径C:\Program Files\nodejs里有空格和一些权限限制，虽然官方安装器处理过，但后面有些老工具链遇到带空格的路径会出现解析问题。我的习惯是改到D:\Nodejs这种纯英文无空格的目录，一劳永逸。
下一步，向导里有一个Add to PATH选项。不同版本这个选项的位置和默认状态略有不同，但意思一样：把Node.js安装目录写进系统环境变量。这个必须勾上，很多新手在安装时觉得“先不管以后再说”，结果装完node -v直接报错。勾上它，你就不用再去手动配环境变量了。
然后是Tools for Native Modules，它询问是否安装Python、Visual Studio Build Tools等原生模块编译工具。如果你现在并不确定要不要编译C++扩展模块，建议先跳过。这类工具占用空间大、安装时间久，真到需要的时候单独装也不迟。选了也不会有坏处，只是占资源。
点Install之后，安装程序开始复制文件，一般一两分钟就完成，最后点击Finish。如果在最后一步看到“Run Node.js”之类的按钮，也不必着急，关掉窗口继续下一步就好。
2.3 install完成之后，立刻做三个验证
装完先别急着写代码，因为环境变量是安装时写入的，已经打开的命令行窗口读不到这些新配置，必须新开窗口。这是很多人忽略的起步问题：装完回原来的窗口执行node -v，必报错。
在开始菜单搜索“cmd”或者“PowerShell”，打开一个新的命令行窗口，依次做三件事。
第一，执行node -v，正常情况下输出类似v20.11.1。看见版本号，说明运行时安装成功。第二，执行npm -v，输出npm的版本号，说明包管理器可用。第三，执行node -e "console.log(process.version)"，这是用脚本方式确认运行时能正常加载和执行JavaScript代码，比单纯看版本号更可靠。
如果node -v有输出、npm -v报错，多半是npm脚本没在PATH里，或者安装时某个组件缺失。如果两个都报“不是内部或外部命令”，先从安装时是否勾选Add to PATH查起。别急，第四章专门处理这些报错。
3. 环境变量配置实操：从PATH原理到手工添加
3.1 PATH变量说明了什么
PATH可能是你以后打交道最多的环境变量，它本身就是一个路径列表，Windows用分号分隔，macOS和Linux用冒号分隔。当你在命令行输一个命令，系统会先看当前目录，找不到就按PATH里的顺序逐个目录去找。
记住“按顺序”这三个字。如果电脑里存在多个同名可执行文件，排在前面的目录会优先命中。很多人电脑上装了好几个Node版本，node -v显示的永远是某个路径下的版本，就是PATH顺序说了算。查看当前的PATH，Windows命令行执行echo %PATH%，macOS/Linux执行echo $PATH，输出会是一大串路径。理解这个机制，大部分“明明装了却用不了”的问题，都能归结为“这个目录没在PATH里”或者“这个目录排在另一个版本后面”。
3.2 手工配置Node.js环境变量的标准步骤
万一安装时没勾Add to PATH，或者用的是zip解压版本，或者不小心改了路径，就需要手工配置。这里给出一套标准的操作链路。
Windows下，先确定Node.js安装目录里真的有node.exe。然后按Win键输入“环境变量”，在搜索结果里打开“编辑系统环境变量”，点右下角“环境变量”按钮。在“系统变量”列表里找到Path，双击进入编辑，点击“新建”，填入Node.js安装目录。注意，填的是含node.exe的那一层目录，不是node.exe文件本身。默认安装的话通常是C:\Program Files\nodejs，你改了安装位置就填你的实际目录。
特别提醒一点，不要用旧版Windows的“编辑文本”模式在末尾手工追加路径并拼分号，很容易写错。新版编辑界面是列表形式，逐条添加，安全得多。添加完成后，所有命令行窗口关闭重开，再跑node -v。这一步也容易漏：刚才打开的窗口继承的是修改前的环境变量，不清空重开等于白配。
macOS和Linux手工配置的思路完全一样，只是落在shell配置文件中。在~/.bashrc、~/.zshrc或/etc/profile中找到合适位置加一行：
export PATH="/你的node安装目录/bin:$PATH"然后执行source ~/.zshrc让配置立即生效。注意Windows的路径用分号，Unix系的PATH用冒号，混着抄会出问题。
3.3 关于NODE_PATH和npm全局目录的补充
很多老教程会让你顺手设置NODE_PATH，说这样才能找到全局模块。这个说法在现代npm环境下已经过时了。
Node.js解析模块时默认是沿着项目目录逐级向上查找node_modules，并不依赖NODE_PATH。npm的全局包也有自己固定的安装位置，Windows下通常是%APPDATA%\npm，这个目录在安装Node时会被自动加入PATH，所以全局安装的CLI工具才能直接在命令行使用。真正需要手工设置NODE_PATH的场景极少，除非你有多个全局依赖目录要自定义，否则不要为了“看起来完整”去配置一个不用的变量，那反而可能干扰模块解析。
有开发者会发现，全局包的CLI命令时灵时不灵，归根到底还是那个问题：npm全局bin目录不在PATH里。排查方法是执行npm config get prefix，拿到全局目录后再加进PATH。具体操作放到4.3里继续讲。
4. 安装后必踩的五个坑：现象、原因、排查链路
4.1 'node'不是内部或外部命令
这是所有Node新手最常撞上的第一堵墙。装完打开命令行敲node -v，系统冷淡地返回一句“不是内部或外部命令，也不是可运行的程序或批处理文件”。
排查链路别乱，按三层方向走。
第一层，确认安装文件本身存在。打开安装目录，看到node.exe才说明程序真的装上了。如果文件都不存在，可能是安装没走完，或者你下的是zip解压到了某个奇怪位置，这时候重装比配置更有用。第二层，检查PATH里是否包含这个目录。命令行执行echo %PATH%看输出，如果没有，回到环境变量编辑页添加。第三层，也是最容易忽略的：重新打开命令行。环境变量在安装时写入，已经打开的窗口读到的是旧配置，不清空重开，配置和验证永远对不上。
三层都检查完还报错，别急着重装。执行where node，看系统实际从哪个路径找到了node命令。有时是电脑里还残留着另一个旧版Node目录，PATH顺序里它在前面插了一脚，这种隐蔽冲突用where一眼就能看出来。
4.2 npm慢到怀疑人生？镜像源这样配
npm默认下载源部署在海外，国内网络环境下npm install拉包慢得能让人喝三杯水。这不算故障，但体验极差。
解决办法是配置镜像源。最常规的做法是把npm的registry指向一个国内社区维护的镜像站，例如执行：
npm config set registry https://registry.npmmirror.com执行完用npm config get registry验证配置是否生效，输出是镜像地址就说明成功了。之后npm install会从这个镜像源拉取依赖，速度通常能提升几倍。相当于把npm的“原料仓库”从远处搬到你家附近，下载路径短了，自然快。
这里有两个容易踩的点。第一，不要用全局镜像源跑所有项目。如果你的公司有私有npm仓库，内部包只在私有源里，全局指向公共镜像会导致拉不到私有包。更稳的做法是项目根目录创建.npmrc文件，在文件里写registry=你的私有源地址，这个配置只作用于当前项目，不影响其他项目。第二，镜像源也有缓存延迟。刚发布几十秒的新包，公共镜像可能还没有，遇到“明明发布了却拉不到”的情况，临时切回官方源试一次，或者等几分钟再装。
还有个小技巧，npm不只是慢，偶尔还会因为缓存损坏报一堆莫名其妙的错误。先执行npm cache clean --force清理一遍缓存再重试，比反复重装卸载靠谱得多。
4.3 全局安装了工具却提示找不到命令
使用npm install -g装了一个命令行工具，使用的时候却提示“xxx不是内部或外部命令”。问题八成出在全局目录没进PATH。
先执行npm config get prefix查询npm全局包的安装目录。Windows下一般输出C:\Users\你的用户名\AppData\Roaming\npm，macOS下可能是/usr/local/bin或用户目录下的某个bin。然后把这个目录加入PATH，和前面配置环境变量的方法完全一样。加完重开命令行，工具就能用了。
如果想省事，还可以用npx。npx是npm自带的小工具，会在当前项目的node_modules/.bin和全局缓存里查找并执行命令，只要包装过、路径没配上，npx都能帮你绕过去。更推荐的做法是：临时工具用npx直接运行，常用工具才全局安装，全局安装完顺手把目录加进PATH，这是最舒服的组合。
4.4 一台电脑多个Node版本打架
随着项目越做越多，电脑上的Node版本很可能不止一个。有的来自官方安装包，有的来自nvm，还有其他工具链自带的运行时。哪天你发现node -v显示的版本和自己预期的不一样，这就是“版本打架”了。
用where node列出所有node.exe的位置，排在第一位的才是当前生效的。如果第一位不是你想要的版本，有两个处理方向：调整PATH顺序，把想要的那个版本目录往前移；或者把多余的版本卸载掉，只保留需要的那一个。最推荐的做法是彻底卸载官方安装包，把所有Node版本交给nvm-windows统一管理，这样版本的选择权完全在你手里，不再受PATH顺序的隐性干扰。
还有一种情况是某天明明什么都没动，node -v却变了。想想是不是最近装过某个大型软件，它自带的运行时把自己加进了PATH甚至直接覆盖了同名文件。这类“隐形安装”很难防，遇到就先where node查路径，比盲目重装有效。
4.5 版本与系统兼容性导致的静默失败
有些坑不报错、不提示，项目就是跑不起来。比如老项目在Node 20上npm install报gyp ERR，或者某依赖库在运行时崩溃，日志里只留下一个模糊的stack trace。这类问题的责任方大多不是你写的代码，而是Node版本和项目依赖的兼容性错位。
很多老项目的依赖库发布在Node 14/16时代，它们在包安装阶段会编译原生模块，而新版本Node对编译工具链和v8 API都有所调整，老库根本跟不上。解决方案不是硬啃编译错误，而是把Node切回项目创建时对应的版本区间。
怎么确定项目要哪个版本？先看package.json里的engines字段，这里通常写明“node >= 14 && < 17”之类的约束。没有的话，看README里的环境要求说明。两者都缺，就根据项目创建时间和依赖库的发布时间推断。判断完之后，用nvm安装并切换到指定版本，比在电脑上同时维护无数个手动安装的运行时可靠得多。
5. 多版本管理：用nvm-windows让Node版本随叫随到
5.1 什么场景真的需要多版本
说句实在话，如果一台电脑只跑一个固定版本的项目，那nvm确实可以不用装。但实际开发中需要多版本的场景比想象中多得多。我之前在维护一套跨平台系统时，生产环境锁死在Node 16，另外有个新项目用Node 22，本地还要跑几个依赖老版本库的自动化脚本。没有nvm的话，每次切换都卸载重装，一次十几分钟，一周切几次，光折腾环境就耗了大半天。
如果你经历过这种场景，会非常理解版本管理器的价值。nvm-windows是Windows上比较主流的Node版本管理器。注意它和macOS/Linux上的nvm不是同一个程序，前者是独立的可执行文件，后者是shell脚本，命令风格也略有区别。在Windows上就用nvm-windows，别把两个搞混。
5.2 nvm-windows的安装与日常命令
安装nvm-windows之前有一件事必须做：先卸载电脑上已经存在的Node官方安装包。nvm-windows的职责是接管Node版本目录和PATH管理，如果电脑里还留着官方安装包，它会和nvm-windows争抢对PATH的控制权，导致切换失效甚至命令冲突。
卸载完官方版，去nvm-windows的官方仓库下载最新版安装包。安装路径建议使用纯英文无空格目录，比如D:\nvm，避免后续路径解析问题。装完后，打开新命令行执行nvm version确认安装成功。
日常命令不多，记住这几个就够用了：
nvm list：查看已安装的版本列表，前面带*的是当前使用的版本nvm install 20.11.1：安装指定完整版本号，也可以简写成nvm install 20，它会自动安装该主版本线的最新发布版nvm use 20.11.1：切换当前使用的版本nvm list available：查看远端可供安装的版本列表
切换完别忘记重开命令行窗口，然后node -v验证一下实际生效的版本。这一步和前面所有环境变量操作的套路一致：窗口环境是启动那一刻的快照，切换命令改了全局配置，旧窗口不会自动感知。
5.3 切换版本时环境变量是怎么联动的
nvm-windows之所以能“一键换版本”，秘密在于它管理了一个固定的安装目录，里面按版本号建了子文件夹。每次切换，它就把PATH里指向Node安装目录的条目，改指向你选中的那个子文件夹。node命令执行时，顺着PATH找到的就是这个版本的node.exe。原理搞清楚，你就能理解为什么“切换后必须重开命令行”——因为PATH被改了，旧窗口的PATH还是旧的。
有一个必须提醒的联动问题：全局npm包和Node版本是绑定的。你用Node 20全局安装了一个工具，切到Node 22后，这个工具在命令行里大概率还用不了，因为全局包安装目录跟随当前Node版本的bin目录走。解决办法也很简单，切完版本后重新npm install -g把要用的工具装一遍。
最后还有个小技巧。nvm-windows安装目录下有一个settings.txt配置文件，里面可以设置root和path两个字段，分别指定nvm本身和Node版本存储的位置。如果默认路径存在权限问题或者遇到空间不足，手动编辑这个文件，改完重启命令行就生效，不用去记复杂的注册表操作。
最后说一个我自己的体会。给不少机器装过Node.js之后，我发现真正费时间的从来不是安装这个动作，而是对运行原理的理解。在环境变量上花十分钟搞清楚PATH的查找逻辑，后面省下的是数不清的排查时间。按这篇教程装好环境，顺手把镜像源配好、nvm-windows装上，这台机器未来一年的Node使用体验都会非常省心。如果哪一步卡住了，回到对应章节按排查链路过一遍，大概率问题就出在那几个最常规的位置上。行了，去装吧，装完记得验证三连。
