1. 安装前先想清楚LTS、版本管理和目录规划1.1 搞懂 Node.js 版本号LTS 和 Current 怎么选很多人上来就去官网点那个最大的绿色按钮结果装完发现版本号长得不太一样有的写v20.11.1有的写v23.4.0一下就懵了。这里我先用最短的话把版本号这件事说清楚。Node.js 的版本号遵循 SemVer 规则格式是主版本.次版本.补丁版本。主版本号变化意味着可能有破坏性 API 调整次版本号增加代表新增功能补丁版本则对应 bug 修复和安全更新。官网首页通常展示两个下载入口一个是LTSLong Term Support长期支持版一个是Current当前最新版。LTS 版本进入长期维护阶段的版本官方会持续提供安全补丁和稳定性更新生产环境首选。Current 版本还在快速迭代中的最新版可以体验新特性但 API 可能在下个大版本里发生变化装在生产环境容易踩雷。以我个人的看法除非你是纯粹想尝鲜否则一律装 LTS。Vite、Webpack、Electron 这类工具链在 LTS 版本上运行得最稳社区解答也最丰富遇到问题搜到的资料几乎都基于 LTS。另外特别注意一些旧项目在升级 Node 大版本后会出现依赖不兼容的问题尤其是牵扯到node-sass、sharp这类带原生模块的包后面我会专门讲这个坑。1.2 要不要装 nvm-windows多版本管理的真实场景先说结论我建议你第一次就用 nvm-windows而不是直接下载安装包。很多人觉得我又不搞多个 Node 版本装个 nvm 是不是多此一举这个想法可以理解但实际工作中你会很快遇到这类场景公司老项目用的是 Node 16你本地装的是 Node 20跑npm install的时候 node-sass 直接编译失败。你下载了别人的开源项目它的package.json里声明了engines字段要求必须用某个具体 Node 版本。你想试试新特性又不想破坏当前稳定的开发环境。有了 nvm-windows这些问题就是一条命令的事。它的工作方式和 Linux/macOS 上的 nvm 很相似维护一个已安装版本列表通过命令切换当前node命令指向的版本。需要注意nvm-windows 和类 Unix 上的 nvm不是同一个项目Windows 用的是 coreybutler 维护的 nvm-windows去它的 GitHub Releases 页面下载nvm-setup.exe安装即可。提示如果你的电脑里已经装了 Node.js先用控制面板卸载干净再装 nvm-windows。两个东西同时在机器上很容易造成 PATH 指向混乱你会发现不管执行nvm use 20多少次node -v显示的始终是旧版本。1.3 安装目录规划的讲究接下来是很多人忽视的目录问题。Node.js 的默认安装路径是C:\Program Files\nodejs这个路径其实有两个隐患Program Files 目录带空格。虽然官方安装包能处理这种情况但某些老旧的构建工具在解析包含空格的路径时确实会出问题。C 盘空间逐渐被蚕食。npm 全局安装的包默认都在C:\Users\你的用户名\AppData\Roaming\npm和node_modules目录里日积月累体积不小。如果你打算用 nvm-windows路径规划更复杂一些。nvm 建议把 Node 各版本放在它自己的目录下比如C:\nvm4nodejs然后通过nvm use动态在C:\Program Files\nodejs创建符号链接。实际上所有版本的 Node 都放在 nvm 的安装目录里符号链接目录只是暴露当前活跃版本给系统。如果你不用 nvm-windows直接用官方安装包我建议在安装向导里把目录改成D:\nodejs这种不含空格的路径后续维护干净得多。2. 一步步把 Node.js 装进 Windows从下载到安装向导2.1 下载渠道与版本核实安装前最后一个准备步骤下载。官方下载渠道是 nodejs.org打开之后首页直接展示两个大按钮左边 LTS右边 Current按刚才的结论选 LTS 就行。国内访问官网有时候很慢或者下载到一半就断。这种情况可以用 npmmirror.com 的二进制镜像站原淘宝镜像地址是https://npmmirror.com/mirrors/node/里面的目录结构和官网完全一致下载速度通常快很多。选择版本时有两个细节版本目录名比如v20.11.1/代表完整的 Node 版本。文件命名规律Windows 用户下安装包要认准.msi结尾的文件比如node-v20.11.1-x64.msi。注意区分x64和arm64——现在不少 Surface 和新的轻薄本用的是 ARM 芯片下载对应的 arm64 版本才能正确运行。提示如果你在镜像站看到像v20.11.1/下面还挂着SHASUMS256.txt这样的校验文件市场上有校验文件列表难得用上。官网下载反过来经常断流。最近版本的热搜里还出现过 error installing 24.21.0: node.js v24.21.0 is not yet released or is not available 这种提示经验上就是下载的版本号写错或者镜像站还没同步最新版本换个时间再下就行。2.2 安装向导里每个选项背后的含义双击.msi文件进入安装向导一路点 Next 的人很多但有几个选项值得停下来想一想。第二页的 Destination Folder是安装路径。如果前面决定了装到 D 盘这里就把C:\Program Files\nodejs改成D:\nodejs。这一步还能顺带解决后来全局模块装到 C 盘的烦恼因为 npm 的全局模块默认放在 Node 安装目录的同级 node_modules 里。第三页 Custom Setup里面有几个子选项Node.js runtime核心运行时必须勾选。npm package managerNode 的包管理器和 Node 一起发布建议保留。不装的话后面没法直接npm install。Online documentation shortcuts桌面和开始菜单的文档快捷方式。对大多数人不重要去掉也行。Add to PATH这个必须保留关键词热门搜索里有一堆 node 不是内部或外部命令绝大多数就是因为安装时没勾这个选项或者手动配置 PATH 时路径写错。最后一页的 Install 按钮。点击后 Windows 可能会弹出 UAC 用户账户控制提示这是正常的选是即可。安装过程一般一分钟内完成极少数情况下杀毒软件会拦截比如某些基于云查杀的引擎会把 npm 全局安装时生成的快捷脚本误判为可疑文件遇到这种情况暂时放行即可。2.3 安装完成的第一个确认动作安装完成后不要急着打开 VS Code 写代码先在命令行里做三个确认动作。这里有个很关键的经验安装完 Node.js 之后之前已经打开的命令行窗口要全部关掉重开。因为环境变量是在安装过程中写入的已经运行的终端进程读取的还是旧的 PATH 快照。新开一个 CMD 或 Windows Terminal依次输入node -v npm -v where nodenode -v会打印当前 Node 版本看到类似v20.11.1的输出就对了。npm -v打印 npm 版本目前 LTS Node 20 自带的 npm 是 10.x。where node比较关键它显示当前node命令指向的可执行文件完整路径。我见过一种诡异情况明明控制系统里没装 Node输入node -v有反应一查where node发现路径在一个莫名其妙的第三方软件目录里。这类问题本质上就是别的软件往 PATH 塞了自己的 Node 运行时不查根本想不到。如果你装的是 nvm-windows情况略有不同。装完后第一步是nvm list available查看可安装的远程版本列表然后nvm install 20.11.1 nvm use 20.11.1注意nvm install后的版本号不能写错格式写20是不行要完整写20.11.1或者用 nvm 支持的模糊匹配写法否则就会出现前面那个 not yet released or is not available 的报错。3. 装完不等于结束环境变量、npm 源和第一行命令3.1 环境变量是怎么自动配的手动配时要小心什么官方 MSI 安装包在安装时会自动把 Node.js 的安装目录添加到系统 PATH 环境变量。这就是为什么装完就能直接在任意终端里执行node命令。理解 PATH 的原理很重要你可以把它想象成一本快递地址簿系统执行命令时会在 PATH 记录的每个目录里找有没有这个名字的可执行文件找到第一个就运行。如果你遇到node 不是内部或外部命令的问题多半是这三种情况安装时取消了 Add to PATH 选项。PATH 里的路径指向错了。系统环境变量和用户环境变量冲突。手动修复方案按Win X打开系统→高级系统设置→环境变量在系统变量里找到Path这一项编辑新增一行指向你的 Node 安装目录比如D:\nodejs。如果你是 nvm-windows 用户系统还会在 PATH 里加一个%NVM_HOME%和%NVM_SYMLINK%这些是 nvm 用来切换版本的关键变量。提示改完环境变量后所有已开的终端窗口都不会自动刷新。要么全部关掉重开要么在 CMD 里执行refreshenv需要 Chocolatey 环境或者干脆重启一次电脑这是新手最容易困惑的点。3.2 npm 默认源太慢换源的完整操作Node.js 装好以后接下来要面对的就是 npm 的下载速度问题。npm 默认从https://registry.npmjs.org/拉取包这个源在国外国内访问经常慢到让人怀疑人生。换源是国内开发者绕不开的一步。目前国内用的最广泛的 npm 镜像源是 npmmirror原淘宝 npm 镜像地址是https://registry.npmmirror.com。你没看错现在的地址已经改成.npmmirror.com了以前那个registry.npm.taobao.org已经是历史产物很多老教程还在让你用淘宝那个老域名实际已经不能用了。查看当前源npm config get registry永久切换源npm config set registry https://registry.npmmirror.com恢复官方源npm config set registry https://registry.npmjs.org/另外提一句npm 自带的--registry参数可以临时指定源比如公司内网有私服时npm install --registryhttps://npm.your-company.com不修改全局配置只影响当前命令。3.3 node -v 有输出但 npm 报错的排查思路有一种比较隐蔽的问题node -v正常输出但npm -v报了一堆错说什么Cannot find module C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js。我见过好几个同事遇到过这个问题根本原因通常是安装了多个 Node 版本或者残留的旧版 npm 缓存被错误合并。比如之前手动装过某个绿色版 Node后来改成 MSI 安装旧文件没清干净两边文件混在一起npm 找不到配套的npm-cli.js。处理办法是把 Node 彻底卸载重装。具体步骤控制面板卸载 Node.js。删除残留目录C:\Program Files\nodejs。删除用户目录下的.npm缓存目录里的 node_modules 相关文件路径通常是C:\Users\用户名\AppData\Roaming\npm和C:\Users\用户名\AppData\Local\npm-cache。重新安装。这套清理流程对 nvm-windows 用户同样适用因为符号链接切换版本时如果目标目录里混入了旧文件也会出现类似问题。4. Windows 专属坑合集这里都是我曾经被绊住的地方4.1 管理员权限与仅此用户的问题Windows 上安装 Node.js 有个隐藏权限问题。我装软件的时候习惯右键以管理员身份运行安装包这个习惯本身没问题但它会带来一个副作用如果安装时勾选了Install for all users选项Node 的安装目录和全局 npm 前缀会写入系统级环境变量如果没勾选这个选项可能只写入当前用户的环境变量。更诡异的是有时候你发现命令行里输入npm install -g装全局包报错EPERM或者EACCES这通常是因为 npm 全局目录没有写权限。Windows 上比较粗暴的解决办法是管理员身份的终端里运行一次npm cache clean --force然后重试安装命令。但这不是治本的方法正确的做法是把 npm 的全局路径配置到你有写权限的目录npm config set prefix D:\nodejs\npm-global设置完之后npm install -g安装的包会进入D:\nodejs\npm-global里的 node_modules同时命令脚本会生成在同目录下需要把D:\nodejs\npm-global也加到 PATH 里才能直接在终端运行全局命令。这么做的好处是以后用npm install -g vite装出来的vite命令不会因为权限问题无法调用。4.2 PowerShell 执行策略拦截脚本这是一个特别小众但特别折磨人的坑。你按照教程在 PowerShell 里运行npx create-react-app my-app结果抛出无法加载文件 ....ps1因为在此系统上禁止运行脚本。问题根源是 Windows PowerShell 默认的执行策略是Restricted禁止任何.ps1脚本运行。而 npm 的npx在执行时为了跨平台兼容会调用 shell 脚本Windows 上就是.ps1或.cmd。解决办法是在有管理员权限的 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned策略表示本地创建的脚本可以运行从网上下载的脚本需要经过数字签名验证才能运行。这是兼顾安全与便利的默认平衡点。注意如果你在Windows PowerShell ISE或者命令提示符里执行npx就不太会遇到这个问题因为 CMD 执行的是.cmd版本脚本。很多教程没提这茬导致全程用 PowerShell 的同学在npx那一步卡死。4.3 路径、中文和杀毒软件Node.js 项目里路径含中文或空格的问题属于平时没事、出问题一头雾水的类型。比如你把项目放在D:\工作\个人项目\第一个项目下面然后npm install偶尔会报一些奇怪的错尤其是安装原生模块时编译器找不到路径里的某个文件。npm 内部对路径的处理有问题不代表所有包都有问题但确实有一部分 C 原生模块的构建脚本对非 ASCII 路径支持不佳。我给你的建议是项目工程目录用纯英文且不含空格。个人项目也养成都放在D:\projects\my-app这种目录下的习惯。开发和运维领域这种玄学问题绝大多数和路径编码有关。杀毒软件的问题也值得单独提出来。Windows Defender 在默认配置下一般不会捣乱但有些第三方安全软件会实时扫描磁盘上的每个可执行文件在npm install大量生成文件时造成性能骤降个别激进的安全策略甚至会直接把node.exe加入隔离名单。遇到安装依赖极其缓慢或者间歇性报错时可以暂时退出杀毒软件试试。装完之后再恢复防护。4.4 老项目 node-sass 编译失败的连锁反应这是我在实际工作中见到最普遍也最难解决的坑。很多稍微老一点的前端项目三五年历史直接或间接依赖node-sass而这个包的核心原理是安装时从 GitHub 下载对应 Node 版本预编译的 libsass 二进制下载不到就在本地用 node-gyp 现场编译。Windows 上本地编译需要 Python 和 Visual Studio Build Tools缺一不可少了任何一个都会报各种看不懂的编译错误。最经典的报错是gyp ERR! stack Error: Could not find any Visual Studio installation解决办法通常是手动安装 Windows Build Tools在管理员终端里跑npm install --global windows-build-tools但这条路现在也不是很顺了因为项目维护状态变化。说实话如果项目还在用 node-sass我建议你优先考虑换用sassdart-sass 实现通常只是改一下包名和导入方式的事。实在改不了再考虑装 Python 3.x VS Build Tools 的组合。还有一个先决条件要确认node-sass 必须和当前 Node 主版本匹配比如 node-sass 4.14 只支持 Node 14放到 Node 20 上百分之百编译失败。这时候你想用 Node 14 来跑项目一个 nvm-windows 就派上大用场了一条命令切换nvm install 14.21.3 nvm use 14.21.3Windows 上多版本管理的重要性在这种时候体现得淋漓尽致。5. 跑通第一个 Node.js 项目从 http 服务到日常脚本5.1 5分钟启动一个本地 Web 服务装好环境之后拿一个最简单的 HTTP 服务练手是理解 Node.js 运行机制的最好方式。新建一个server.js文件写入以下代码const http require(http); const server http.createServer((req, res) { res.writeHead(200, { Content-Type: text/plain; charsetutf-8 }); res.end(Hello, Node.js on Windows!); }); server.listen(3000, () { console.log(Server running at http://localhost:3000); });在项目目录下执行node server.js打开浏览器访问http://localhost:3000看到输出就说明 Node.js 已经能正常工作了。如果访问后一直转圈不见响应优先排查 Windows 防火墙是否拦截了 node.exe 的入站请求首次运行时会弹出网络访问许可在没有管理员权限的情况下有可能被自动拦截。这个例子里有个细节值得初学者体会Node.js 的 HTTP 模块创建服务时不需要额外安装任何依赖说明 Node 本身自带的模块体系已经覆盖了基础的网络编程能力。你更常用的express、koa这些框架本质上是基于这些底层模块封装出来的工具集。5.2 用 Node.js 写个批量处理脚本的基本套路安装完环境后很多人不知道使用 Node.js到底能用在哪。除了跑 Web 服务前端构建脚本、文件批量处理、爬虫抓取这些都是 Node.js 的常规应用场景。给你看一个实际例子写一个脚本批量重命名当前目录下所有.jpg图片把文件名里的空格替换成下划线。const fs require(fs); const path require(path); const currentDir process.cwd(); const files fs.readdirSync(currentDir); files.forEach((file) { if (path.extname(file) .jpg file.includes( )) { const newName file.replace(/ /g, _); fs.renameSync(path.join(currentDir, file), path.join(currentDir, newName)); console.log(renamed: ${file} - ${newName}); } });执行方式依然简单node rename.js这个脚本用到的fs和path模块都是 Node.js 内置的核心思路是读目录、遍历文件、改文件名。把 Node.js 当作脚本语言用Windows 上要比写 PowerShell 脚本更顺手因为 Node.js 的语法对前端开发者几乎没有学习成本而且fs模块处理编码、递归目录这种操作远比批处理命令直观。5.3 前端开发者常用的 Node.js 全家桶认知最后聊一下前端开发者的熟悉场景。现在的前端工具链本质上都跑在 Node.js 上Vite / Webpack打包工具负责把 Vue、React 源码编译成浏览器能跑的静态文件。npm / yarn / pnpm包管理器负责安装项目依赖、管理版本。npx临时执行 npm 包的命令比如npx create-vite直接生成项目模板。这些工具在 Windows 上安装后都会在 PATH 里注册一个和包名同名的命令脚本.cmd、.ps1、.bash分别对应不同 shell。这也是为什么npm install -g之后新开一个终端才能识别新命令——PATH 只在终端启动时读取一次。如果你发现自己全局装了个包但输入命令提示不是内部或外部命令先检查全局安装目录是否在 PATH 里。用npm prefix -g查看当前全局前缀然后按之前小节的方法调整 PATH 即可。6. 后续维护版本升级、多版本切换与彻底卸载6.1 用 nvm-windows 换版本的实际操作如果你装了 nvm-windows平时换版本都是这么几步nvm list # 查看本机已安装版本 nvm list available # 查看远程可安装版本 nvm install 22.2.0 # 安装新版本 nvm use 22.2.0 # 切换当前使用版本nvm use切换的原理有意思它会把当前激活的 Node 版本通过符号链接挂到C:\Program Files\nodejs目录下。这个过程需要管理员权限所以如果你的终端不是管理员模式nvm use会自动弹 UAC 确认这正常。我在实际使用中注意到一个问题如果你用nvm装了多个版本每个版本的全局 npm 包是互相隔离的。在 Node 20 下装的全局工具切到 Node 22 之后就消失了。这其实是 nvm 的设计如此避免不同版本间全局模块冲突。你在踩坑时会发现这个设计是优点而不是缺点。6.2 手动升级与卸载清理的正确姿势没用 nvm-windows 的同志升级 Node 只有一条路去官网下载新版安装包直接覆盖安装。MSI 安装器会保留原有 npm 全局包但存在一种概率出现兼容性问题最典型的表现是之前全局装的某个包依赖旧版 Node 的某些 C 内部 API新版 Node 不兼容就报错。这时候就需要彻底重装。卸载之后手动清理这几个位置的残留文件路径说明C:\Program Files\nodejs安装主目录卸载后通常残留C:\Users\用户名\AppData\Roaming\npm全局 npm 脚本和模块C:\Users\用户名\AppData\Local\npm-cachenpm 下载缓存C:\Users\用户名\AppData\Roaming\npm-cache某些旧版 npm 缓存位置HKCU\Software\nodejs和HKLM\Software\nodejs注册表残留项清理完再装新版就能避开大部分莫名其妙的兼容坑。关于 nvm-windows 的卸载也要多说一句直接卸载前最好先nvm use切换到某个版本再在控制面板里卸载。不然符号链接失效后PATH 里残留的C:\Program Files\nodejs指向一个不存在的目标虽然不太影响其他命令但每次node都会报错烦人。6.3 一个小技巧npm 的依赖重装与缓存问题排查最后补充一个日常使用频率很高的排查思路。Windows 上npm install经常出现装到一半报错的情况很多和网络不稳或缓存损坏有关。简单粗暴的方法删除node_modules目录。删除package-lock.json文件。执行npm cache clean --force清理缓存。重新npm install。如果项目很大node_modules删起来很慢可以借用系统命令加速rd /s /q node_modules这是 Windows 上删除目录最快的方式没有之一。装了 node 之后也许你还会遇到node 命令突然反应很慢的情况。排查思路是先定位node的可执行文件路径确认系统中没有别的软件覆盖。之前的热搜里有 codex windows设置未完成 这类开发者工具问题其实很多都是环境变量没配对。核心排查思路是一致的先where node再看 PATH 顺序最后检查用户变量和系统变量是否冲突。这套安装与排查的流程我前前后后执行过不下几十次从 Windows 7 一路用到现在 Windows 11凡是照着上面思路走的基本二十分钟内都能把环境跑通。真正在一线踩坑之后你会明白Node.js 本身安装并不难难点都在 Windows 的权限体系和历史残留上。既然选择了 Windows 作为开发环境花点时间了解 PATH 的工作原理、PowerShell 的执行策略和卸载清理的细节后续所有的烦恼都会少一大半。
Windows 下 Node.js 安装与配置完全指南：从版本选择到环境变量排查
1. 安装前先想清楚LTS、版本管理和目录规划1.1 搞懂 Node.js 版本号LTS 和 Current 怎么选很多人上来就去官网点那个最大的绿色按钮结果装完发现版本号长得不太一样有的写v20.11.1有的写v23.4.0一下就懵了。这里我先用最短的话把版本号这件事说清楚。Node.js 的版本号遵循 SemVer 规则格式是主版本.次版本.补丁版本。主版本号变化意味着可能有破坏性 API 调整次版本号增加代表新增功能补丁版本则对应 bug 修复和安全更新。官网首页通常展示两个下载入口一个是LTSLong Term Support长期支持版一个是Current当前最新版。LTS 版本进入长期维护阶段的版本官方会持续提供安全补丁和稳定性更新生产环境首选。Current 版本还在快速迭代中的最新版可以体验新特性但 API 可能在下个大版本里发生变化装在生产环境容易踩雷。以我个人的看法除非你是纯粹想尝鲜否则一律装 LTS。Vite、Webpack、Electron 这类工具链在 LTS 版本上运行得最稳社区解答也最丰富遇到问题搜到的资料几乎都基于 LTS。另外特别注意一些旧项目在升级 Node 大版本后会出现依赖不兼容的问题尤其是牵扯到node-sass、sharp这类带原生模块的包后面我会专门讲这个坑。1.2 要不要装 nvm-windows多版本管理的真实场景先说结论我建议你第一次就用 nvm-windows而不是直接下载安装包。很多人觉得我又不搞多个 Node 版本装个 nvm 是不是多此一举这个想法可以理解但实际工作中你会很快遇到这类场景公司老项目用的是 Node 16你本地装的是 Node 20跑npm install的时候 node-sass 直接编译失败。你下载了别人的开源项目它的package.json里声明了engines字段要求必须用某个具体 Node 版本。你想试试新特性又不想破坏当前稳定的开发环境。有了 nvm-windows这些问题就是一条命令的事。它的工作方式和 Linux/macOS 上的 nvm 很相似维护一个已安装版本列表通过命令切换当前node命令指向的版本。需要注意nvm-windows 和类 Unix 上的 nvm不是同一个项目Windows 用的是 coreybutler 维护的 nvm-windows去它的 GitHub Releases 页面下载nvm-setup.exe安装即可。提示如果你的电脑里已经装了 Node.js先用控制面板卸载干净再装 nvm-windows。两个东西同时在机器上很容易造成 PATH 指向混乱你会发现不管执行nvm use 20多少次node -v显示的始终是旧版本。1.3 安装目录规划的讲究接下来是很多人忽视的目录问题。Node.js 的默认安装路径是C:\Program Files\nodejs这个路径其实有两个隐患Program Files 目录带空格。虽然官方安装包能处理这种情况但某些老旧的构建工具在解析包含空格的路径时确实会出问题。C 盘空间逐渐被蚕食。npm 全局安装的包默认都在C:\Users\你的用户名\AppData\Roaming\npm和node_modules目录里日积月累体积不小。如果你打算用 nvm-windows路径规划更复杂一些。nvm 建议把 Node 各版本放在它自己的目录下比如C:\nvm4nodejs然后通过nvm use动态在C:\Program Files\nodejs创建符号链接。实际上所有版本的 Node 都放在 nvm 的安装目录里符号链接目录只是暴露当前活跃版本给系统。如果你不用 nvm-windows直接用官方安装包我建议在安装向导里把目录改成D:\nodejs这种不含空格的路径后续维护干净得多。2. 一步步把 Node.js 装进 Windows从下载到安装向导2.1 下载渠道与版本核实安装前最后一个准备步骤下载。官方下载渠道是 nodejs.org打开之后首页直接展示两个大按钮左边 LTS右边 Current按刚才的结论选 LTS 就行。国内访问官网有时候很慢或者下载到一半就断。这种情况可以用 npmmirror.com 的二进制镜像站原淘宝镜像地址是https://npmmirror.com/mirrors/node/里面的目录结构和官网完全一致下载速度通常快很多。选择版本时有两个细节版本目录名比如v20.11.1/代表完整的 Node 版本。文件命名规律Windows 用户下安装包要认准.msi结尾的文件比如node-v20.11.1-x64.msi。注意区分x64和arm64——现在不少 Surface 和新的轻薄本用的是 ARM 芯片下载对应的 arm64 版本才能正确运行。提示如果你在镜像站看到像v20.11.1/下面还挂着SHASUMS256.txt这样的校验文件市场上有校验文件列表难得用上。官网下载反过来经常断流。最近版本的热搜里还出现过 error installing 24.21.0: node.js v24.21.0 is not yet released or is not available 这种提示经验上就是下载的版本号写错或者镜像站还没同步最新版本换个时间再下就行。2.2 安装向导里每个选项背后的含义双击.msi文件进入安装向导一路点 Next 的人很多但有几个选项值得停下来想一想。第二页的 Destination Folder是安装路径。如果前面决定了装到 D 盘这里就把C:\Program Files\nodejs改成D:\nodejs。这一步还能顺带解决后来全局模块装到 C 盘的烦恼因为 npm 的全局模块默认放在 Node 安装目录的同级 node_modules 里。第三页 Custom Setup里面有几个子选项Node.js runtime核心运行时必须勾选。npm package managerNode 的包管理器和 Node 一起发布建议保留。不装的话后面没法直接npm install。Online documentation shortcuts桌面和开始菜单的文档快捷方式。对大多数人不重要去掉也行。Add to PATH这个必须保留关键词热门搜索里有一堆 node 不是内部或外部命令绝大多数就是因为安装时没勾这个选项或者手动配置 PATH 时路径写错。最后一页的 Install 按钮。点击后 Windows 可能会弹出 UAC 用户账户控制提示这是正常的选是即可。安装过程一般一分钟内完成极少数情况下杀毒软件会拦截比如某些基于云查杀的引擎会把 npm 全局安装时生成的快捷脚本误判为可疑文件遇到这种情况暂时放行即可。2.3 安装完成的第一个确认动作安装完成后不要急着打开 VS Code 写代码先在命令行里做三个确认动作。这里有个很关键的经验安装完 Node.js 之后之前已经打开的命令行窗口要全部关掉重开。因为环境变量是在安装过程中写入的已经运行的终端进程读取的还是旧的 PATH 快照。新开一个 CMD 或 Windows Terminal依次输入node -v npm -v where nodenode -v会打印当前 Node 版本看到类似v20.11.1的输出就对了。npm -v打印 npm 版本目前 LTS Node 20 自带的 npm 是 10.x。where node比较关键它显示当前node命令指向的可执行文件完整路径。我见过一种诡异情况明明控制系统里没装 Node输入node -v有反应一查where node发现路径在一个莫名其妙的第三方软件目录里。这类问题本质上就是别的软件往 PATH 塞了自己的 Node 运行时不查根本想不到。如果你装的是 nvm-windows情况略有不同。装完后第一步是nvm list available查看可安装的远程版本列表然后nvm install 20.11.1 nvm use 20.11.1注意nvm install后的版本号不能写错格式写20是不行要完整写20.11.1或者用 nvm 支持的模糊匹配写法否则就会出现前面那个 not yet released or is not available 的报错。3. 装完不等于结束环境变量、npm 源和第一行命令3.1 环境变量是怎么自动配的手动配时要小心什么官方 MSI 安装包在安装时会自动把 Node.js 的安装目录添加到系统 PATH 环境变量。这就是为什么装完就能直接在任意终端里执行node命令。理解 PATH 的原理很重要你可以把它想象成一本快递地址簿系统执行命令时会在 PATH 记录的每个目录里找有没有这个名字的可执行文件找到第一个就运行。如果你遇到node 不是内部或外部命令的问题多半是这三种情况安装时取消了 Add to PATH 选项。PATH 里的路径指向错了。系统环境变量和用户环境变量冲突。手动修复方案按Win X打开系统→高级系统设置→环境变量在系统变量里找到Path这一项编辑新增一行指向你的 Node 安装目录比如D:\nodejs。如果你是 nvm-windows 用户系统还会在 PATH 里加一个%NVM_HOME%和%NVM_SYMLINK%这些是 nvm 用来切换版本的关键变量。提示改完环境变量后所有已开的终端窗口都不会自动刷新。要么全部关掉重开要么在 CMD 里执行refreshenv需要 Chocolatey 环境或者干脆重启一次电脑这是新手最容易困惑的点。3.2 npm 默认源太慢换源的完整操作Node.js 装好以后接下来要面对的就是 npm 的下载速度问题。npm 默认从https://registry.npmjs.org/拉取包这个源在国外国内访问经常慢到让人怀疑人生。换源是国内开发者绕不开的一步。目前国内用的最广泛的 npm 镜像源是 npmmirror原淘宝 npm 镜像地址是https://registry.npmmirror.com。你没看错现在的地址已经改成.npmmirror.com了以前那个registry.npm.taobao.org已经是历史产物很多老教程还在让你用淘宝那个老域名实际已经不能用了。查看当前源npm config get registry永久切换源npm config set registry https://registry.npmmirror.com恢复官方源npm config set registry https://registry.npmjs.org/另外提一句npm 自带的--registry参数可以临时指定源比如公司内网有私服时npm install --registryhttps://npm.your-company.com不修改全局配置只影响当前命令。3.3 node -v 有输出但 npm 报错的排查思路有一种比较隐蔽的问题node -v正常输出但npm -v报了一堆错说什么Cannot find module C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js。我见过好几个同事遇到过这个问题根本原因通常是安装了多个 Node 版本或者残留的旧版 npm 缓存被错误合并。比如之前手动装过某个绿色版 Node后来改成 MSI 安装旧文件没清干净两边文件混在一起npm 找不到配套的npm-cli.js。处理办法是把 Node 彻底卸载重装。具体步骤控制面板卸载 Node.js。删除残留目录C:\Program Files\nodejs。删除用户目录下的.npm缓存目录里的 node_modules 相关文件路径通常是C:\Users\用户名\AppData\Roaming\npm和C:\Users\用户名\AppData\Local\npm-cache。重新安装。这套清理流程对 nvm-windows 用户同样适用因为符号链接切换版本时如果目标目录里混入了旧文件也会出现类似问题。4. Windows 专属坑合集这里都是我曾经被绊住的地方4.1 管理员权限与仅此用户的问题Windows 上安装 Node.js 有个隐藏权限问题。我装软件的时候习惯右键以管理员身份运行安装包这个习惯本身没问题但它会带来一个副作用如果安装时勾选了Install for all users选项Node 的安装目录和全局 npm 前缀会写入系统级环境变量如果没勾选这个选项可能只写入当前用户的环境变量。更诡异的是有时候你发现命令行里输入npm install -g装全局包报错EPERM或者EACCES这通常是因为 npm 全局目录没有写权限。Windows 上比较粗暴的解决办法是管理员身份的终端里运行一次npm cache clean --force然后重试安装命令。但这不是治本的方法正确的做法是把 npm 的全局路径配置到你有写权限的目录npm config set prefix D:\nodejs\npm-global设置完之后npm install -g安装的包会进入D:\nodejs\npm-global里的 node_modules同时命令脚本会生成在同目录下需要把D:\nodejs\npm-global也加到 PATH 里才能直接在终端运行全局命令。这么做的好处是以后用npm install -g vite装出来的vite命令不会因为权限问题无法调用。4.2 PowerShell 执行策略拦截脚本这是一个特别小众但特别折磨人的坑。你按照教程在 PowerShell 里运行npx create-react-app my-app结果抛出无法加载文件 ....ps1因为在此系统上禁止运行脚本。问题根源是 Windows PowerShell 默认的执行策略是Restricted禁止任何.ps1脚本运行。而 npm 的npx在执行时为了跨平台兼容会调用 shell 脚本Windows 上就是.ps1或.cmd。解决办法是在有管理员权限的 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned策略表示本地创建的脚本可以运行从网上下载的脚本需要经过数字签名验证才能运行。这是兼顾安全与便利的默认平衡点。注意如果你在Windows PowerShell ISE或者命令提示符里执行npx就不太会遇到这个问题因为 CMD 执行的是.cmd版本脚本。很多教程没提这茬导致全程用 PowerShell 的同学在npx那一步卡死。4.3 路径、中文和杀毒软件Node.js 项目里路径含中文或空格的问题属于平时没事、出问题一头雾水的类型。比如你把项目放在D:\工作\个人项目\第一个项目下面然后npm install偶尔会报一些奇怪的错尤其是安装原生模块时编译器找不到路径里的某个文件。npm 内部对路径的处理有问题不代表所有包都有问题但确实有一部分 C 原生模块的构建脚本对非 ASCII 路径支持不佳。我给你的建议是项目工程目录用纯英文且不含空格。个人项目也养成都放在D:\projects\my-app这种目录下的习惯。开发和运维领域这种玄学问题绝大多数和路径编码有关。杀毒软件的问题也值得单独提出来。Windows Defender 在默认配置下一般不会捣乱但有些第三方安全软件会实时扫描磁盘上的每个可执行文件在npm install大量生成文件时造成性能骤降个别激进的安全策略甚至会直接把node.exe加入隔离名单。遇到安装依赖极其缓慢或者间歇性报错时可以暂时退出杀毒软件试试。装完之后再恢复防护。4.4 老项目 node-sass 编译失败的连锁反应这是我在实际工作中见到最普遍也最难解决的坑。很多稍微老一点的前端项目三五年历史直接或间接依赖node-sass而这个包的核心原理是安装时从 GitHub 下载对应 Node 版本预编译的 libsass 二进制下载不到就在本地用 node-gyp 现场编译。Windows 上本地编译需要 Python 和 Visual Studio Build Tools缺一不可少了任何一个都会报各种看不懂的编译错误。最经典的报错是gyp ERR! stack Error: Could not find any Visual Studio installation解决办法通常是手动安装 Windows Build Tools在管理员终端里跑npm install --global windows-build-tools但这条路现在也不是很顺了因为项目维护状态变化。说实话如果项目还在用 node-sass我建议你优先考虑换用sassdart-sass 实现通常只是改一下包名和导入方式的事。实在改不了再考虑装 Python 3.x VS Build Tools 的组合。还有一个先决条件要确认node-sass 必须和当前 Node 主版本匹配比如 node-sass 4.14 只支持 Node 14放到 Node 20 上百分之百编译失败。这时候你想用 Node 14 来跑项目一个 nvm-windows 就派上大用场了一条命令切换nvm install 14.21.3 nvm use 14.21.3Windows 上多版本管理的重要性在这种时候体现得淋漓尽致。5. 跑通第一个 Node.js 项目从 http 服务到日常脚本5.1 5分钟启动一个本地 Web 服务装好环境之后拿一个最简单的 HTTP 服务练手是理解 Node.js 运行机制的最好方式。新建一个server.js文件写入以下代码const http require(http); const server http.createServer((req, res) { res.writeHead(200, { Content-Type: text/plain; charsetutf-8 }); res.end(Hello, Node.js on Windows!); }); server.listen(3000, () { console.log(Server running at http://localhost:3000); });在项目目录下执行node server.js打开浏览器访问http://localhost:3000看到输出就说明 Node.js 已经能正常工作了。如果访问后一直转圈不见响应优先排查 Windows 防火墙是否拦截了 node.exe 的入站请求首次运行时会弹出网络访问许可在没有管理员权限的情况下有可能被自动拦截。这个例子里有个细节值得初学者体会Node.js 的 HTTP 模块创建服务时不需要额外安装任何依赖说明 Node 本身自带的模块体系已经覆盖了基础的网络编程能力。你更常用的express、koa这些框架本质上是基于这些底层模块封装出来的工具集。5.2 用 Node.js 写个批量处理脚本的基本套路安装完环境后很多人不知道使用 Node.js到底能用在哪。除了跑 Web 服务前端构建脚本、文件批量处理、爬虫抓取这些都是 Node.js 的常规应用场景。给你看一个实际例子写一个脚本批量重命名当前目录下所有.jpg图片把文件名里的空格替换成下划线。const fs require(fs); const path require(path); const currentDir process.cwd(); const files fs.readdirSync(currentDir); files.forEach((file) { if (path.extname(file) .jpg file.includes( )) { const newName file.replace(/ /g, _); fs.renameSync(path.join(currentDir, file), path.join(currentDir, newName)); console.log(renamed: ${file} - ${newName}); } });执行方式依然简单node rename.js这个脚本用到的fs和path模块都是 Node.js 内置的核心思路是读目录、遍历文件、改文件名。把 Node.js 当作脚本语言用Windows 上要比写 PowerShell 脚本更顺手因为 Node.js 的语法对前端开发者几乎没有学习成本而且fs模块处理编码、递归目录这种操作远比批处理命令直观。5.3 前端开发者常用的 Node.js 全家桶认知最后聊一下前端开发者的熟悉场景。现在的前端工具链本质上都跑在 Node.js 上Vite / Webpack打包工具负责把 Vue、React 源码编译成浏览器能跑的静态文件。npm / yarn / pnpm包管理器负责安装项目依赖、管理版本。npx临时执行 npm 包的命令比如npx create-vite直接生成项目模板。这些工具在 Windows 上安装后都会在 PATH 里注册一个和包名同名的命令脚本.cmd、.ps1、.bash分别对应不同 shell。这也是为什么npm install -g之后新开一个终端才能识别新命令——PATH 只在终端启动时读取一次。如果你发现自己全局装了个包但输入命令提示不是内部或外部命令先检查全局安装目录是否在 PATH 里。用npm prefix -g查看当前全局前缀然后按之前小节的方法调整 PATH 即可。6. 后续维护版本升级、多版本切换与彻底卸载6.1 用 nvm-windows 换版本的实际操作如果你装了 nvm-windows平时换版本都是这么几步nvm list # 查看本机已安装版本 nvm list available # 查看远程可安装版本 nvm install 22.2.0 # 安装新版本 nvm use 22.2.0 # 切换当前使用版本nvm use切换的原理有意思它会把当前激活的 Node 版本通过符号链接挂到C:\Program Files\nodejs目录下。这个过程需要管理员权限所以如果你的终端不是管理员模式nvm use会自动弹 UAC 确认这正常。我在实际使用中注意到一个问题如果你用nvm装了多个版本每个版本的全局 npm 包是互相隔离的。在 Node 20 下装的全局工具切到 Node 22 之后就消失了。这其实是 nvm 的设计如此避免不同版本间全局模块冲突。你在踩坑时会发现这个设计是优点而不是缺点。6.2 手动升级与卸载清理的正确姿势没用 nvm-windows 的同志升级 Node 只有一条路去官网下载新版安装包直接覆盖安装。MSI 安装器会保留原有 npm 全局包但存在一种概率出现兼容性问题最典型的表现是之前全局装的某个包依赖旧版 Node 的某些 C 内部 API新版 Node 不兼容就报错。这时候就需要彻底重装。卸载之后手动清理这几个位置的残留文件路径说明C:\Program Files\nodejs安装主目录卸载后通常残留C:\Users\用户名\AppData\Roaming\npm全局 npm 脚本和模块C:\Users\用户名\AppData\Local\npm-cachenpm 下载缓存C:\Users\用户名\AppData\Roaming\npm-cache某些旧版 npm 缓存位置HKCU\Software\nodejs和HKLM\Software\nodejs注册表残留项清理完再装新版就能避开大部分莫名其妙的兼容坑。关于 nvm-windows 的卸载也要多说一句直接卸载前最好先nvm use切换到某个版本再在控制面板里卸载。不然符号链接失效后PATH 里残留的C:\Program Files\nodejs指向一个不存在的目标虽然不太影响其他命令但每次node都会报错烦人。6.3 一个小技巧npm 的依赖重装与缓存问题排查最后补充一个日常使用频率很高的排查思路。Windows 上npm install经常出现装到一半报错的情况很多和网络不稳或缓存损坏有关。简单粗暴的方法删除node_modules目录。删除package-lock.json文件。执行npm cache clean --force清理缓存。重新npm install。如果项目很大node_modules删起来很慢可以借用系统命令加速rd /s /q node_modules这是 Windows 上删除目录最快的方式没有之一。装了 node 之后也许你还会遇到node 命令突然反应很慢的情况。排查思路是先定位node的可执行文件路径确认系统中没有别的软件覆盖。之前的热搜里有 codex windows设置未完成 这类开发者工具问题其实很多都是环境变量没配对。核心排查思路是一致的先where node再看 PATH 顺序最后检查用户变量和系统变量是否冲突。这套安装与排查的流程我前前后后执行过不下几十次从 Windows 7 一路用到现在 Windows 11凡是照着上面思路走的基本二十分钟内都能把环境跑通。真正在一线踩坑之后你会明白Node.js 本身安装并不难难点都在 Windows 的权限体系和历史残留上。既然选择了 Windows 作为开发环境花点时间了解 PATH 的工作原理、PowerShell 的执行策略和卸载清理的细节后续所有的烦恼都会少一大半。