如果有人问你“Node.js 怎么装”你大概率会得到一句“官网下个安装包一路 Next 就行”。这话没错但只能说解决了“能跑”的问题离“用得舒服、不踩坑”还差得远。我见过太多新手的机器上Node.js 装完没几天就出各种幺蛾子——全局包装不上、版本切来切去一团糟、npm 下载慢到怀疑人生最后只能含泪重装系统。这篇就从头到尾讲清楚 Node.js 安装配置的完整思路从版本选择到镜像源、从全局路径到多版本共存一次讲透照着做就行。这篇内容是写给谁的想在自己的电脑上搭前端开发环境的新人被 node-gyp 编译折磨到崩溃的 Windows 用户还有想在一台机器上同时维护多个项目的进阶玩家。不管你属于哪一类看完这篇应该都能找到对应的解法。1. 安装之前先把这几件事想清楚1.1 Node.js 和 npm 到底是什么关系很多新手会混淆的概念先把地基打好。Node.js 是一个 JavaScript 运行时让你能在浏览器之外跑 JS 代码npm 是随 Node.js 一起分发的包管理器负责下载和管理第三方库。两者是“买一送一”的关系装好 Node.jsnpm 一般也就有了。另外还要知道 Node.js 自带的 npm 是个独立项目它的更新节奏和 Node.js 本身不同步。你装的 Node.js 是某个版本但里面捆绑的 npm 不一定是当时最新的。所以碰到 npm 版本太老导致的问题单独升级 npm 就行不需要重新装 Node.js。顺带提一下 yarn 和 pnpm 这两个后来者。它们本质上也是包管理器解决的是 npm 在某些场景下的性能和一致性问题。后面讲到配置的时候我会说怎么在一个干净的 npm 环境里把它们也搞定。1.2 版本选择LTS 还是 CurrentNode.js 的官网首页会给你两个下载按钮左边是 LTSLong Term Support长周期支持右边是 Current当前最新版。我给绝大多数人的建议就一句话能用 LTS 就用 LTS别追新。LTS 版本的维护周期很长覆盖率广大部分第三方库和框架都会优先保证对 LTS 的兼容。你在生产环境里装个库发现编译不过大概率是因为 Node.js 版本太新而不是库本身有问题。Current 版本更像是实验室里跑的前沿玩意适合尝鲜和测试新特性但别指望生态都跟得上。还有一个扎心的现实很多老项目的依赖和 Node.js 的版本强绑定。你新项目用 Node.js 20 没问题但那是个两年前的老项目用 20 跑直接一堆语法报错。这种时候就需要多版本切换方案了后面专门讲。1.3 不同平台的安装差异Windows、macOS、Linux 三家的安装姿势和后续维护成本是完全不一样的Windows官方 .msi 安装包最省心但版本切换最痛苦装完还要手动配环境变量。macOS推荐用 Homebrew但你如果没装过 Homebrew安装过程本身也是个事。Linux官方源里的 Node.js 版本通常偏旧想要新版本得加第三方源或者直接用版本管理工具。这三大系统我都实际用过接下来这节就按平台把安装方式一个个拆开。2. 三种主流安装方式怎么选2.1 官方安装包适合快速上手先用 Windows 来说。打开官网选 LTS 版本对应的 Windows Installer下载完双击然后进入“一路 Next”环节。有几个细节要留意到自定义安装那一步一定要确认“Add to PATH”是勾选状态。这个选项默认勾着但架不住有人手滑取消。安装路径建议改成非系统盘比如E:\Nodejs后面清理起来方便也不至于给系统盘增加压力。装完之后不要继续用之前已经打开的命令行窗口。必须先全部关掉重开不然环境变量不会刷新输入node -v大概率提示“不是内部或外部命令”。macOS 的 .pkg 安装包就没这么多事装完直接能用PATH 会自动配好。Windows 上如果懒得用安装包也可以用 winget 一条命令搞定但我不推荐把 winget 当作新手的第一选择因为它的安装源版本可能滞后而且配置不如 .msi 可控。2.2 系统包管理器适合日常开发机macOS 上比较常规的做法是brew install node这个方式简单但它会直接安装最新版本的 Node.js没有 LTS 和 Current 的选择余地。如果你后续要用多版本切换这种方式装出来的 node 会跟 nvm 产生路径冲突相当难受。所以我的建议是如果你知道自己以后会折腾多版本一开始就别用 Homebrew 装 Node.js。Linux 上直接走系统包管理器也会有类似问题而且更严重。很多发行版的软件源里 Node.js 都停留在老版本比如某个系统源里还挂着 Node.js 16.x但外面早就 22 了。用这种源装出来的环境开发新项目时经常会遇到“这个库要求 Node.js 18 以上”的报错到时候再换版本就很折腾。2.3 nvm 版本管理推荐大多数人使用nvmNode Version Manager是一个按用户维度管理 Node.js 版本的 Shell 脚本它不碰系统级目录把所有版本的 Node.js 都装进你的用户目录下然后通过软链接的方式切换当前激活的版本。macOS / Linux 下安装 nvm 的方法是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完后要重启终端或者手动让 shell 重新加载配置文件。Windows 没有原生的 nvm但有一个社区移植版叫 nvm-windows功能上覆盖了大部分需求和原生 nvm 差不多的场景。下载安装包装完也别急着重开终端先在命令行里敲nvm version确认一下。装了 nvm 之后安装新版本就变成nvm install --lts nvm use --lts使用多版本切换比如切到某个特定版本nvm install 18.20.4 nvm use 18.20.4这个方式规避了我在前面说的所有坑不需要 sudo不需要碰系统路径版本随便切还可以给每个项目单独规定用哪个版本。如果只能推荐一种安装方式我写这篇教程会毫不犹豫地推荐 nvm 系方案。3. 安装后的三个关键配置3.1 npm 镜像源配置很多人在 npm install 的时候卡到怀疑人生问题几乎都出在默认下载源上。npm 默认的官方源在国外对于国内用户来说速度看缘分。解决办法是换镜像源这类镜像源属于社区托管的公网服务本质上是把官方源的包数据做了定时同步再从国内节点分发不带任何特殊性质放心用即可。换源前先看一下当前源npm config get registry如果显示的是官方地址执行npm config set registry https://registry.npmmirror.com换完之后再执行一次npm config get registry确认地址已经变成镜像源然后试着装一个库速度差别是体感级别的。如果公司内部有自建的私有源也可以指到内部地址上去这个不影响其他配置。需要注意的是registry 是全局配置对公司项目和个人项目一视同仁如果你同时维护多个项目建议优先用项目级配置下面细说。3.2 全局包安装路径npm 有一个全局安装模式装出来的工具放在全局目录可以在任意路径下执行。举个例子npm install -g pnpm这条命令会把 pnpm 装到全局目录。但你会遇到两个问题第一在 Linux/macOS 上默认全局目录可能位于系统目录下普通用户没有写权限导致安装失败需要 sudo 才能装第二在 Windows 上全局包的目录非常“深”还占 C 盘空间。先说 Linux/macOS 的解法。给 npm 的全局目录设置一个用户级别的路径npm config set prefix $HOME/.npm-global然后把这个目录加到 PATH 里在 shell 配置文件比如.bashrc、.zshrc里加一行export PATH$HOME/.npm-global/bin:$PATH重新加载配置之后用npm install -g装的任何工具都能直接用了而且不需要 sudo。这个操作的本质是告诉系统“我自己的可执行文件放在这里”完全合法合规也避免了对系统目录乱动。再单独说 Windows。Windows 上的 npm 全局目录默认在 npm 安装目录下而 npm 一般装在系统盘的node_modules里。时间一长你全局装的各种 CLI 工具都会堆积在系统盘。要改目录第一步在非系统盘建两个文件夹比如E:\Nodejs\node_global和E:\Nodejs\node_cache。第二步设置 npm 的全局目录和缓存目录npm config set prefix E:\Nodejs\node_global npm config set cache E:\Nodejs\node_cache第三步进入环境变量设置把Path里的用户变量改成E:\Nodejs\node_global然后把默认的缓存路径变量改成E:\Nodejs\node_cache。注意这里改的是“用户变量”里的 Path不是系统变量改错了容易影响系统其他程序。这一步做完以后全局装的东西全部落在非系统盘C 盘清清爽爽。3.3 编辑器与开发环境Node.js 本身只是一个运行时真正写代码用的 IDE 需要单独配置。主流的做法是用 VS Code 这类编辑器搭几个和 Node.js 配合最紧密的插件比如支持智能提示和小服务区调试的扩展。不过这块依赖个人偏好就不展开推荐了。有一个值得做的操作是开启 corepack。Node.js 从某个版本开始内置了 corepack用来统一管理 yarn 和 pnpm 的版本。启用方式corepack enable然后你就可以直接使用 pnpm 和 yarn不再需要单独全局安装。它还会根据项目里的packageManager字段自动切换工具版本对于维护多个项目很友好。4. 验证安装与多版本切换4.1 安装验证不论用哪种方式装完都要做一套完整的验证流程从最基本的开始node -v npm -v分别打印出 Node.js 和 npm 的版本号装好且 PATH 配好就能看到。如果第一行就报错基本可以确定是 PATH 的问题。接着验证 npm 能正常下载和安装包mkdir /tmp/node-test cd /tmp/node-test npm init -y npm install lodash如果这条命令成功执行node_modules 目录里出现了 lodash 的代码说明整个链路npm 源、权限、网络、磁盘写入都是通的。很多新手装完 Node.js 后直接跑项目看到报错就以为没装好其实问题往往出在依赖安装这一环这个最小化测试能帮你把问题和项目本身隔离开。用 nvm 的话还可以快速看一眼当前管理了哪些版本nvm list带*号的表示当前正在使用的版本。4.2 多版本共存场景与实操多版本切换最常见的场景是企业里多点交付的老项目。比如你手头有一个线上项目它构建时固定用的是老版本 Node.js同时又在开发一个新项目需要新版本的特性。装了 nvm 之后你可以这样nvm install 16.20.2 nvm install 22.x nvm use 16.20.2在项目根目录执行旧版本的构建命令构建结束之后切回新版本继续开发新项目。这中间有一个需要重点提醒的事不同 Node.js 版本对应的 npm 版本也不同全局包在不同 Node 版本之间是隔离的。你切到 16 之后之前全局装的某些工具可能“不见了”这不是 bug因为 nvm 给每个版本的 Node.js 都维护了独立的全局包空间。如果某个工具在多个版本下都要用那就分别在每个版本下重装或者统一用 corepack 的方式管理可移植的工具链。除了手动切换版本还可以在每个项目和 Node.js 版本绑定做法是在项目根目录下放一个.nvmrc文件把需要的版本号写进去20.11.0之后在项目目录里执行nvm usenvm 会自动读取这个文件并切换到对应版本。这样换人、换电脑之后团队其他人也能一键复现同样的 Node.js 环境省去很多“在我电脑上是好的啊”的尴尬。5. 常见报错排查与避坑指南5.1 报错“node 不是内部或外部命令”这条 Windows 用户见得多。先检查环境变量里的 Path 是否包含 node.exe 所在目录一般默认是C:\Program Files\nodejs\或者你自己改的安装路径。如果没有有两种处理方法重新安装 Node.js 并在安装向导里勾选 Add to PATH或者手动编辑环境变量把 node.exe 的路径加进去。手动编辑的方法是右键“此电脑” →“属性”→“高级系统设置”→“环境变量”在用户变量里找到 Path新增一行填根目录。填完要重启终端。macOS 和 Linux 如果出现command not found: node先看是不是用了 sudo 安装导致 PATH 没生效或者 shell 配置文件没有重新加载。执行source ~/.zshrc或者source ~/.bashrc一般能解决。5.2 全局安装包时报 EACCES 权限错误这个基本是 Linux/macOS 用户没设置 prefix 就直接npm install -g导致的。权限冲突的本质是全局目录不在当前用户可写范围内。解法是两条路线一个是像我前面说的设置用户级 prefix 并修改 PATH另一个是直接把 node 和 npm 重新装进用户目录下nvm 方案天然满足。只需要记住不要在遇到 EACCES 时直接sudo npm install -g短时间内也能跑但后续你装的工具一旦涉及到跨用户编译路径问题搞乱的就是整个系统目录的归属排查起来很痛苦。5.3 依赖安装时的 node-gyp 编译失败项目里如果包含原生模块也就是需要 C/C 编译的那类库安装依赖时会调用 node-gyp 去拉编译工具链Windows 上需要安装 Python 和 Visual Studio Build Tools。macOS 上需要 Xcode Command Line Tools。Linux 上需要build-essential和python3。报错代码里通常会出现“node-gyp”相关的字样而且往往带着一堆编译日志。这个问题的根源不在于 npm 配置而在于系统缺少编译工具链。很多人在这一步被劝退以为是自己 Node.js 没装好。这时候先确认系统里有没有 Python 和 C 编译环境再回到项目里重新安装依赖大概率就过了。5.4 npm 版本过老引起的报错有些老版本 npm 在解析依赖的时候会有不少历史 bug表现是报错信息特别抽象比如 ERESOLVE、ELIFECYCLE 之类。先把 npm 升级到当前版本的 LTS 集成的较新版本npm install -g npmlatest如果项目对 npm 版本有特殊要求比如旧项目只支持 npm 6就不要强行升级 npm而是切换到对应时代的 Node.js 版本再操作。这种场景下nvm 又能救你直接nvm install 老版本整套环境都会跟着对齐。5.5 排查工具直接把问题摊开看新手遇到问题时容易慌其实排查方向是有迹可循的。你可以按顺序跑这些命令which node which npm node -v npm -v npm config get registry npm config listwhich node告诉你当前执行的 node 来自哪里如果输出路径不是你预期的说明 PATH 顺序有问题。npm config get registry看镜像源是否配置到位。npm config list可以一次性看到所有配置项包括奇奇怪怪的遗留配置。这一套下来大部分“明明装了却不好使”的问题都能定位到源头。另外在 nvm 场景下which node的输出大概率是一个软链接路径指向 nvm 目录下的某个版本这是正常现象不用慌。最后分享一个我个人的使用习惯不管在哪台机器上装 Node.js我第一件事永远是先装 nvm然后用 nvm 装 LTS 版本接着立刻设置 npm 的镜像源和全局路径再corepack enable。这套流程走下来大概十几分钟之后基本不会再回踩 Node.js 环境相关的坑。如果看到这里还有哪一步报错是上面没提到的建议把报错信息原样复制到搜索框里再加上你的操作系统版本一起搜效率远高于自己瞎试。Node.js 的安装配置本身不难难的是理解每个配置项背后的原理。把这篇里的“为什么”看懂了以后遇到什么新问题你心里都会有个大概的排查方向。
