接触 Node.js 这几年我发现一个特别有意思的现象真正卡住大多数新人的往往不是写代码本身而是最前面的环境搭建。下载一个安装包谁都会可装完之后node -v没反应、npm报错、环境变量改了不生效、版本装错了导致项目跑不起来……这些问题几乎每天都能在技术交流群里看到。这篇教程我打算把 Node.js 下载、安装、环境配置的完整流程拆开揉碎了讲一遍包括每一步为什么这么做、界面会显示什么、会遇到哪些坑、怎么排查争取让完全零基础的人也能照着把环境折腾出来并且理解背后的原理而不是只会机械地“下一步、下一步”。这篇文章适合所有刚入门的前端开发者、转行做 JavaScript 服务端开发的工程师以及需要在本机跑 Vue、React 等前端工程化的同学。不管你用的是 Windows、macOS 还是 Linux下面我都会给出对应的方案但主战场会放在最常见也最容易出问题的 Windows 上。1. 动手之前先搞明白Node.js 到底是什么东西很多教程上来就让装装完就完事。但如果你不清楚自己装的是什么后面遇到问题会非常被动。这里我花点篇幅讲清楚基础概念这些都是后续排查问题绕不开的知识点。1.1 一句话讲清楚它为什么重要Node.js 本质上是一个 JavaScript 运行时环境。在没有 Node.js 之前JavaScript 只能在浏览器里跑离开浏览器就什么都干不了。Node.js 把 Chrome 浏览器的 V8 引擎抽了出来让 JavaScript 可以在服务器端、命令行工具里运行。这样一来前端开发者用同一门语言就能写后端服务也能用它来构建前端项目的打包工具、启动本地开发服务器。你现在打开任何一个稍有点规模的前端项目十有八九能看到 package.json 文件。Vue 项目要跑起来第一步就是npm install安装依赖然后npm run dev启动开发服务——这两个命令背后靠的就是 Node.js。所以装好 Node.js是所有前端工程化操作的前提条件绕不开。1.2 Node.js 和 npm 的关系它俩不是同一个东西但又密不可分新手最常混淆的一个概念就是 Node.js 和 npm。你安装官方的 Node.js 安装包之后npm 会跟着一起装上所以很多人误以为它们是一个东西。实际上Node.js 是运行时环境负责执行 JavaScript 代码npm 是 Node.js 的包管理器负责下载、安装、管理第三方代码库叫“依赖包”或“模块”。我举个生活化的例子Node.js 相当于一台洗衣机npm 相当于你从超市买回来的洗衣液、柔顺剂。洗衣机本身就能洗衣服但你想洗得更干净、更香就需要这些额外的东西。npm 就是帮你把“洗衣液”从超市货架上拿下来、摆到你家柜子里的那个搬运工。没有 npm你也能用 Node.js 写代码跑代码但所有公共库都得手动下载、手动管理版本那效率会低到让人崩溃。1.3 版本选择LTS 还是 Current别一激动就装最新版Node.js 官网提供两个版本的下载入口LTSLong Term Support长期支持版和 Current当前最新版。LTS 版本会获得长达数年的维护更新稳定性优先修复 bug 和安全漏洞Current 版本则会第一时间上线新功能但可能不够稳定。我的建议非常明确除非你有特殊需求否则一律选 LTS。生产环境部署、日常项目开发LTS 都是最稳妥的选择。很多第三方依赖在 Current 版本刚出来时会存在兼容性问题你装了最新版npm install时报错查半天发现是 Node 版本太新导致的那种体验真的难受。我自己见过太多人因为追求版本新结果踩了一堆莫名其妙的坑最后退回 LTS 才消停。2. 下载安装前的准备与关键决策在正式点击安装按钮之前有几个决定需要你先做好。这些决策直接影响后面环境配置的复杂度做好了能省下不少事。2.1 下载渠道认准官方网站别去乱七八糟的镜像站下载 Node.js 只有一个建议渠道官方网站。搜索引擎里搜“Node.js 下载”很容易出来一堆第三方下载站有些捆绑了广告软件有些版本老旧还有些看着正规实则不安全。我以前在帮别人排查环境问题时见过装了一些来路不明的分发版导致各种诡异报错的案例。打开官网首页你会看到两个醒目的绿色按钮左边是“当前活跃的 LTS 版本”右边是“当前最新版本”还有 Windows、macOS、Linux 三种操作系统的安装包。官方页面会根据你的操作系统自动推荐对应的安装包格式但为了严谨我建议还是自己手动确认一下版本号。认准版本号再去点下载按钮比如 v20.x LTS、v22.x LTS 这样的字样。2.2 安装包格式选择Windows Installer 还是二进制压缩包进入下载页面你会发现同一版本下有好几个文件可供下载Windows 系统通常有这些Windows Installer (.msi)官方图形化安装向导推荐大多数用户使用。Windows Binary (.zip)免安装绿色版解压即用但需要手动配置环境变量。MSI 安装包的优势在于它自动帮你把环境变量配好了双击一路下一步就能用省心。ZIP 压缩包则适合那种不想污染系统注册表、想绿色化使用的人。但说实话如果你是因为“不想配置环境变量”而选择 MSI那后面还是要理解环境变量的原理因为即使 MSI 自动配置了你早晚也会遇到需要手动改环境变量的场景。macOS 用户对应的是 .pkg 安装包和 .tar.gz 压缩包Linux 用户一般用预编译二进制或者系统包管理器安装。后面我会分平台细说。2.3 安装路径规划别装到 C 盘根目录或者带中文的路径这一点很多人不重视但确实值得提前说。Node.js 默认安装路径在 Windows 上是C:\Program Files\nodejs\这个路径本身是英文且没有空格问题Program Files 中间有空格但 Node 官方安装器能处理一般不用改。但我不建议手动把安装路径改成C:\Node.js或者D:\新建文件夹\nodejs这种——前者没问题后者带中文极少数依赖在解析中文路径时会出现编码问题到时候报错很难排查。如果你确实想装到 D 盘路径全英文就行比如D:\Software\nodejs。另外建议把这句记下来Node.js 的全局模块安装目录默认在用户目录下跟 Node.js 本体安装在哪关系不大这个后面环境变量章节会详细展开。3. 完整安装流程实操从双击安装包到命令行成功响应下面开始正式安装。我尽量把每一步界面上能看到什么、该点什么都说清楚毕竟很多人看图文教程最怕的就是“我这一步怎么和你截图不一样”。3.1 Windows 系统MSI 安装向导全程图解双击下载好的 .msi 文件会弹出安装向导的第一个界面点击 “Next” 进入下一步。接下来会看到许可协议界面勾选 “I accept the terms in the License Agreement”然后继续点 “Next”。随后进入安装路径选择界面这里可以点击 “Change” 修改安装位置建议保持默认或者改成纯英文路径。继续 “Next”进入 “Custom Setup” 自定义功能界面。这个界面列了一堆组件默认是全部安装我建议不要做任何改动保持默认。你会注意到里面有一项叫 “Add to PATH”这是 Node.js 自动添加环境变量的关键选项千万别取消勾选。很多“装完了但命令用不了”的问题就是因为安装时手动取消了这一项。接下来是两个可选的附加步骤界面“Choose whether to install tools for Native Modules”——这个询问是否安装编译原生模块所需的工具链包括 Python 和 Visual Studio Build Tools。大多数人不做原生模块编译直接点 “Next” 跳过就行。等你后面真的需要安装 node-sass、bcrypt 这类原生模块时再回来单独装工具更合适。点击 “Install” 开始安装等待进度条跑完最后点 “Finish” 完成。安装完成后最关键的一步是验证。打开一个新的命令行窗口——注意必须是新打开的窗口如果安装前你就开着命令行窗口它可能不会自动刷新环境变量——输入node -v npm -v如果输出类似下面这样的版本号信息说明安装成功v20.14.0 10.7.0这里有个细节想强调打开新命令行窗口这件事看起来不起眼但真的很多人在这上面卡住。他们装完之后继续用之前打开的那个命令行窗口输入命令结果提示“node 不是内部或外部命令”实际上环境变量已经配好了只是老窗口没刷新。3.2 macOS 系统pkg 安装包步骤说明macOS 最省事的方式是下载官方提供的 .pkg 安装包。双击打开后会有一个简短的介绍界面一路点 “Continue” 继续。安装器会询问是否同意许可协议点 “Agree”然后选择安装位置一般保持默认。接下来输入你的 Mac 用户密码等待安装完成即可。安装完成后同样打开 “终端” 应用输入node -v和npm -v验证。如果你之前安装过旧版本新版本装完后终端有时会缓存旧的命令路径这时可以尝试关闭终端再重新打开。macOS 还有一种方式是使用 Homebrew 安装brew install node这种方式的好处是后续升级方便直接brew upgrade node就行。但 Homebrew 安装的版本可能不是最新版通常它会指向当前最新稳定版具体以仓库为准。新手如果只是为了学 Node.js直接用官方 pkg 更直观不容易出现权限方面的困惑。3.3 Linux 系统包管理器与官方二进制的取舍Linux 的安装方式就比较多了。Ubuntu/Debian 系可以用 aptsudo apt update sudo apt install nodejs npm但这里有个坑apt 仓库里的 Node.js 版本往往比较旧甚至有些发行版预装的还是十年前的老版本。我建议先查一下版本号如果项目有版本要求就不可直接用这种方式。更可靠的方式是使用 NodeSource 提供的官方仓库或者直接下载官方预编译的二进制压缩包解压到/usr/local/目录下再把 bin 路径加入 PATH。官方二进制方式的步骤大致如下# 下载链接以官网实际版本为准 wget https://nodejs.org/dist/v20.14.0/node-v20.14.0-linux-x64.tar.xz # 解压 sudo tar -xJf node-v20.14.0-linux-x64.tar.xz -C /usr/local/ # 把解压出来的目录改个简单名字 sudo mv /usr/local/node-v20.14.0-linux-x64 /usr/local/nodejs # 配置 PATH临时生效 export PATH/usr/local/nodejs/bin:$PATH # 写入当前用户配置文件使其永久生效 echo export PATH/usr/local/nodejs/bin:$PATH ~/.bashrc source ~/.bashrc如果系统里有多个用户需要使用也可以把 PATH 写入 /etc/profile这属于系统级配置按实际情况取舍。Linux 环境的自由度更高但也要求你对自己在做什么有更清晰的认识每一行命令建议都理解之后再执行。4. 环境变量配置安装完不等于装好如果你用的是官方 MSI 或 pkg 安装包环境变量通常已经帮你配好了。但作为一篇“保姆级详解”这部分必须讲透因为你会遇到三种情况一是改过安装路径需要手动配置二是用 ZIP 免安装包需要手动配置三是当环境变量出问题时你必须知道去哪里看、怎么改。4.1 环境变量到底是什么先消除这个认知盲区简单说环境变量就是操作系统提供给应用程序的一组“全局开关和路径提示”。其中最重要的一个叫 PATH。当你在命令行里输入node并按回车时系统会在当前目录下找有没有名为 node 的程序文件找不到就会按 PATH 里记录的目录逐一去找。所以node命令能用本质上是 PATH 里包含了 Node.js 安装目录环境变量配置出问题就是这个路径没有写对或者根本没有写入。有人把环境变量配置想得很神秘其实就是往一个文本配置里加一行路径只是 Windows 提供的是图形化编辑界面Linux 是往配置文件里写文本命令。4.2 Windows 图形界面配置环境变量全步骤右击 “此电脑” → 选择 “属性” → 点击 “高级系统设置” → 点击 “环境变量”。这时你会看到两个区域上面是“用户变量”下面是“系统变量”。关键知识点来了用户变量的 PATH 只对当前用户生效系统变量的 PATH 对所有用户生效。如果你只是自己开发改用户变量足够不需要系统管理员权限如果这台机器上有多个账户都要用 Node.js就改系统变量但修改系统变量需要管理员权限。我个人的习惯是优先改用户变量避免误动系统级配置导致其他程序出问题。找到用户变量里的 Path 项双击它弹出编辑窗口。点击 “新建”输入 Node.js 的实际安装目录比如C:\Program Files\nodejs点确定保存。如果你用的是免安装版还要把全局模块的缓存目录也加进去这个后面专门讲。保存之后需要重新打开命令行窗口才能生效因为命令行窗口启动时读取环境变量。用echo %PATH%可以查看当前窗口识别到的 PATH 内容确认它包含 Node.js 路径。4.3 npm 全局模块路径与 cache 路径的配置npm 安装的全局命令工具默认存放在一个固定的全局目录里。在 Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm在 Linux/macOS 上是/usr/local/bin或/usr/local/lib/node_modules。你可以用以下命令查看当前的全局目录前缀npm config get prefix npm config get cache如果你不希望全局模块占 C 盘空间或者因为系统权限问题无法写入默认目录Linux 上很常见可以通过修改 npm 配置来改变全局模块的安装位置npm config set prefix D:\Software\nodejs\node_global npm config set cache D:\Software\nodejs\node_cache改完之后一定要把D:\Software\nodejs\node_global也加入到 PATH 环境变量里否则你通过npm install -g安装的命令工具找不到执行路径。一个更常见的需求是修改 npm 的镜像仓库这部分我会在后面的优化章节单独讲。这里先记住一条主线Node.js 本体路径是“运行”全局模块路径是“扩展命令”两者都可能需要加入 PATH缺一不可。4.4 NODE_PATH这个环境变量到底要不要设置网上很多教程会让你额外设置一个叫 NODE_PATH 的环境变量作用是让 Node.js 解析模块时能直接找到全局安装的包。但实际上Node.js 在解析模块依赖时有自己的查找策略它会从当前文件目录逐级向上查找node_modules目录跟你设置什么环境变量关系不大。NODE_PATH 是早期模块解析机制的产物现在大部分框架和工具都遵循标准的 node_modules 查找规则设置它并不会带来明显帮助反而可能掩盖问题。我的建议是不要画蛇添足。只有在你遇到非常特殊的模块解析问题时再用npm root -g查看全局模块根目录把该目录加入 NODE_PATH 做排查。日常开发中多数情况下用不到它。4.5 验证是否真正配置成功三个命令组合检查安装和配置完成后不要慌着进入下一步先用三个命令做一次系统体检node -v npm -v where nodewhere nodeLinux/macOS 用which node会输出 node 可执行文件的完整路径。如果输出了路径说明系统确实找到了 Node.js如果没有任何输出但node -v有版本号说明命令可能被别名或 shim 拦截了。这两个结果不一样时值得警惕一下。再加一个检查全局命令是否正常工作的例子npm install -g cowsay cowsay Hello Node.js如果能正常输出一头牛说话的文字图案说明 Node.js 本体路径和 npm 全局模块路径都配置正确了。这一套组合检查做下来环境基本稳了。5. 常见问题与排查技巧实录这一节是我实际经验里最有价值的部分。下面的问题每一个我都在真实场景中见过至少一次有些甚至反复出现。我按“现象 → 原因 → 解决方案”的结构整理方便你遇到问题时直接对照。5.1 “npm 不是内部或外部命令”但 node -v 正常这个现象在排除环境变量问题时非常典型。node -v能正常输出版本号说明 Node.js 本体安装没问题、PATH 里能找到 nodenpm -v却报“不是内部或外部命令”说明 PATH 或 npm 本身出了问题。按下 win R 输入where npm看系统能不能找到 npm 的路径。如果找不到大概率是安装目录下的 npm 文件丢失或损坏。解决办法去官网重新下载对应版本安装包覆盖安装一遍大部分情况下能修复。另外检查一下 PATH 里是否有多个 Node.js 路径比如以前装过旧版本卸载不干净又装了新版两个路径互相干扰会导致命令指向异常。出现这种问题时把旧的无效路径从 PATH 里删掉保留一个有效路径重启命令行窗口再试。5.2 “node 不是内部或外部命令”的几种常见根因这个报错说明系统在 PATH 目录里完全找不到 node 程序。逐条对照排查是否安装过程中取消了 “Add to PATH” 选项如果是重新运行安装包在 “Change” 里确认勾选或者手动添加环境变量。是否修改了安装路径但没有同步修改 PATH比如把 Node.js 从默认目录移到别处环境变量还指向旧路径。这时更新 PATH 里的路径即可。是否命令行窗口是旧窗口没有刷新环境变量关掉重新打开一个。是否 PATH 里的目录中的 node.exe 被误删或者被安全软件隔离去路径目录里检查文件是否存在。检查环境变量时注意一个小细节Windows 的环境变量编辑框里每一行刚好是一个目录不要把两个目录写在同一行用分号分隔。新的 Windows 10/11 图形界面是分行编辑的但如果你在编辑框里按了删除键有可能把多个路径挤到一行里这时候就容易出问题。5.3 版本号不对装了新版命令行还是显示旧版本这种问题几乎都是“PATH 里存在多个 Node.js 版本”导致的。比如你以前用系统包管理器装过后来又用官方安装包装了一遍系统执行 node 命令时先命中了旧版本。解决办法where node查看输出结果如果显示两个不同路径就按优先级清理。Windows 的 PATH 是按顺序查找的找到第一个就不再往后找所以把旧版本路径从 PATH 里删除或者调整顺序就能解决。另外有些 macOS 用户同时用了 Homebrew 和官方 pkg 安装也会出现类似冲突。最简单的应对思路是同一台机器只保留一种安装方式不要混着来。5.4 启动项目时报错node:util does not provide an export named这个报错在较新的项目搭配 Node.js 18 及以上版本时偶尔会遇到原始报错信息大概是node:internal/modules/cjs/loader: throwing Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath ./util is not defined by exports in ...或者The requested module node:util does not provide an export named xxx这类问题的根源往往是某个依赖包在编写时指定了过低的 Node.js 版本比如 12 或 14当你在 Node.js 18 环境下运行时Node 核心模块的导出结构发生了变化旧依赖没有适配。解决方案一般是升级该依赖包的版本找到报错信息里提示的包名执行npm update 包名如果升级后依然报错就往下降 Node.js 版本用回项目要求的 LTS 版本。所以遇到这类问题先别慌这属于依赖生态兼容性问题不是你的环境配置有问题。5.5 全局安装模块时报 EACCES/EPERM 权限错误Windows 上表现为安装过程中出现EPERM或EACCES常见原因有两个一是当前命令行窗口没有以管理员身份运行二是 Node.js 安装目录或全局模块目录的写入权限不足或者文件被占用比如正在运行的进程。Linux 和 macOS 上则更常见用npm install -g往/usr/lib/node_modules写文件时权限不足报 EACCES。最粗暴的解法是用sudo npm install -g xxx但这是治标不治本而且 sudo 加上 npm 会产生很多权限归属混乱的问题日后卸载和更新都麻烦。更好的方案是修改 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc我强烈建议用第二种方案不跟系统目录较劲把主动权握在自己手里。5.6 环境变量修改后命令行不生效这个问题特别常见原因也很简单命令行窗口在启动时加载环境变量如果修改环境变量之前窗口已经开着它不会自动感知变化必须关掉重新打开。如果你用的是 Windows Terminal 或者 VS Code 的内置终端有时光关窗口不够需要完全退出应用再重新打开它们可能缓存了环境变量。再补充一个排查思路在命令行里执行echo %PATH%Windows 下能看到当前环境变量内容如果发现已经包含新路径但命令还是提示找不到那就是路径本身写错了、目录里根本没有 node.exe。检查路径名大小写、空格和斜杠方向Windows 对路径大小写不敏感但空格和斜杠很敏感。5.7 常见问题速查表把上面这些问题的浓缩版整理成表格方便你打印或者收藏。现象可能原因快速解决方案node -v 无输出/找不到命令PATH 未配置或配置错误检查 PATH添加 node 安装目录npm -v 无输出/找不到命令npm 文件损坏或路径失效覆盖安装检查 PATH 多版本冲突版本号和预期不符多个 Node 版本共存删除旧版本清理 PATH 多余条目安装全局模块权限不足全局目录不可写修改 npm prefix 到用户目录老窗口命令不生效环境变量未刷新关闭旧窗口重新打开依赖冲突报错Node 版本过高或过低升级相关依赖或切换 Node 版本中文路径目录异常安装路径含中文重新安装到纯英文路径6. 把环境再优化一步npm 镜像与常用初始化操作装好环境只是起点真正舒服的开发体验还需要几项基础优化。这一节内容不多但能极大提升后续使用体验。6.1 更换 npm 镜像仓库减少下载等待时间npm 默认的仓库地址在海外直接下载依赖经常会出现网络超时或速度极慢的情况。解决办法是换成速度更快的镜像仓库。在国内使用较多的是阿里云提供的 npmmirror 镜像。设置镜像一行命令就能完成npm config set registry https://registry.npmmirror.com设置后用以下命令验证npm config get registry输出是镜像地址就说明生效了。需要注意的是镜像源的更新会有短暂延迟偶尔可能出现某依赖在官方源已发布、镜像还没同步的情况这时候用npm install 包名 --registryhttps://registry.npmjs.org临时指定官方源即可。换镜像源这个话题经常有人争论我认为本质上是择优使用哪个快用哪个工具是为人服务的。但我还是要提醒一句在团队协作时建议在项目里用.npmrc文件统一管理镜像地址避免团队成员全凭个人习惯配置导致依赖安装行为和版本不一致。6.2 初始化第一个 Node.js 项目把环境真正用起来环境配好之后建议立刻创建一个小项目验证完整链路。新建一个空目录在命令行里进入该目录执行npm init -y这个命令会自动生成一个 package.json 文件它是 Node.js 项目的“身份证”记录了项目名称、版本、依赖和脚本命令。接着安装一个简单的第三方库npm install express然后新建一个 index.js 文件写入const express require(express); const app express(); app.get(/, (req, res) { res.send(Hello Node.js); }); app.listen(3000, () { console.log(Server is running at http://localhost:3000); });在命令行执行node index.js浏览器打开http://localhost:3000能看到 “Hello Node.js” 就说明整个环境全部打通。这一套流程走下来你对“Node.js 解析执行 JavaScript npm 管理依赖”会有最直观的感受比看一百篇教程都有效。6.3 多版本管理装一个 nvm以后不再为版本切换发愁文章到这里我最后再把多版本管理工具单独拎出来说一下。前面提到过不同项目可能需要不同的 Node.js 版本如果每次都用卸载重装的方式切换版本效率极低还容易出错。这类场景推荐使用 nvmNode Version Manager。Windows 平台用 nvm-windows这是独立项目不是官方但广泛使用。下载安装后可以nvm install 20.14.0 nvm use 20.14.0 nvm listmacOS/Linux 上可以使用官方版本 nvm安装脚本在 GitHub 仓库里。用 nvm 之后PATH 里的 node 路径由 nvm 统一管理切换版本非常干净不会出现多个版本互相干扰的问题。我个人近年来的习惯是固定用 nvm 管理所有 Node 版本每个项目在 package.json 里标注所需的 Node 版本切换目录时看一眼就切版本。这一招帮我省了大量排查环境问题的时间。最后再分享一个小技巧安装完 Node.js 后最先做的不是急着写业务代码而是先跑一遍npm install -g npmlatest把自带 npm 升级到最新版。官方安装包随附的 npm 版本可能略老升级能避免部分依赖解析问题。实际使用中你会发现环境搭建看起来简单但真正稳定的环境往往来自对细节的追问版本对不对、路径全不全、镜像快不快、目录干净不干净。把这些基础都打扎实后面学习和排错都会顺很多。