1. 装机第一步：先搞懂 Node.js 和 npm 到底是什么
很多新手第一次接触 Node.js 时，经常被一堆概念绕晕：Node、npm、nvm、cnpm、yarn、pnpm……还没开始写代码，光是装环境就劝退了一半人。我用最直白的方式先把这个东西讲清楚。
Node.js 本身是一个 JavaScript 运行时环境，核心作用就是让 JavaScript 不再只能跑在浏览器里，而是能在操作系统上直接执行。比如你可以用 JavaScript 写一个后台服务、写一个命令行工具、做文件读写、调系统接口，这些都靠 Node.js 在底层支撑。它的内部使用了 Google V8 引擎，就是 Chrome 浏览器里那个解释执行 JavaScript 的引擎，所以你写出来的代码能跑得飞快，而且天生支持异步 I/O，特别适合处理高并发的网络请求场景。
npm 则是 Node.js 自带的包管理工具，全称是 Node Package Manager。你可以把它理解为"JavaScript 世界的应用商店"。以前你想用别人写好的功能模块，得手动下载文件、手动引入、手动处理依赖关系，版本冲突能把人折磨到怀疑人生。npm 解决了这个问题，一行命令npm install就能把某个开源模块连同它所有依赖一起拉下来装好，项目里的依赖清单用 package.json 文件统一管理，团队成员拉下代码后执行一条命令就能恢复整个依赖环境。
那两个东西为什么非得"安装及环境配置"一起讲？因为真正干活的时候你会发现，装 Node.js 只是开始，后面的坑一个比一个经典：命令敲下去提示"npm 不是内部或外部命令"、npm 安装包慢到怀疑网络断连、PS1 文件执行策略报错、全局安装的模块找不到……这些问题的根源，十有八九都是环境配置没做对。这篇教程会用完整的 Windows 环境作为演示主线，把从零到能正常跑项目、发布 npm 包的全流程拆开讲透，每个步骤背后的原理也一并说清楚。
2. 动手之前：版本选择和核心概念扫盲
2.1 官方版本号里的门道
很多人在官网看到一个页面好几个按钮，就懵了。Node.js 官网首页常年挂着两个版本：LTS 和 Current。LTS 全称 Long Term Support，就是长期维护版本，官方会承诺长达 30 个月的稳定支持和安全补丁更新，适合生产环境、正式项目和绝大多数学习者。Current 版本则是最新功能版，能第一时间体验新特性，但相对不稳定，一些第三方依赖可能还没来得及适配。
我自己的建议非常简单粗暴：不是专门做 Node 底层开发或者特别想尝鲜的人，一律选 LTS。别为了某个新语法特性去装 Current，结果项目里某个老依赖直接跑不起来，排查问题的时间足够你把功能写完三遍了。另外记住一个点，中文社区里常看到的"偶数版本号是稳定版、奇数版本号是测试版"这种说法已经不适用于现在 Node 的发布策略，你只需要认准官网标着 LTS 字样的那一栏就好。
2.2 安装方式怎么选：安装包、nvm 还是包管理器
Windows 上安装 Node.js 常见有三条路：直接下载官方安装包、使用 nvm-windows 工具管理多版本、用 winget 或 Chocolatey 等包管理器命令安装。三种方式各有适用场景。
官方安装包（.msi）是最直观、最不容易出问题的方式，下载一个文件双击到底就能用，环境变量会自动配置好，适合第一次接触的新手。nvm-windows 则是"Node 版本管理神器"，可以在一台电脑上同时安装多个 Node 版本，通过命令行随时切换。如果你以后可能同时维护多个不同技术栈的项目，某个老项目要求 Node 12，另一个新项目要用 Node 20，那 nvm 就是唯一解。第三种包管理器方式，适合习惯用命令解决一切的选手，但系统环境依赖较强，不推荐作为首选。
这篇教程重点讲官方安装包的完整配置流程，在最后会专门补充 nvm 的安装和多版本配置方法，因为从热搜词来看，nvm 全局配置 node 的需求量非常大。
2.3 先看清 PATH 环境变量的作用
聊环境配置之前，必须先讲清楚 PATH 到底是个什么东西，否则你永远只能照着教程敲，出了问题就傻眼。
电脑里装了软件之后，软件的可执行文件往往埋在一个很深的目录里，比如C:\Program Files\nodejs\node.exe。你在命令行里输入命令时，系统会把命令当成一个文件名去磁盘上找这个文件，但它不可能翻遍整块硬盘去找，所以就需要一个"快捷目录列表"，这就是 PATH 环境变量。
当你在终端里敲下node -v，系统的执行顺序是这样的：先看当前目录下有没有 node.exe 或 node 相关的可执行文件，没有再按 PATH 变量里的路径挨个去找，找到就执行，全部找不到就提示"不是内部或外部命令"。
理解了这一点，后面所有的环境变量配置就都有了逻辑基础。所谓"配置环境变量"，核心就两件事：把 Node 的可执行目录告诉系统，以及把全局模块的目录告诉系统。
3. 从零开始：完整安装流程实录
3.1 下载 Node.js 安装包
打开 Node.js 官网的下载页面，选择 LTS 版本的 Windows 安装包。这里还有一个细节：Windows 平台有 .msi 和 .zip 两种文件格式。.msi 是图形化安装向导，推荐大多数人使用；.zip 是免安装压缩包，解压配置就能用，适合绿色软件爱好者，但环境变量得手动配。
点 .msi 下载时要注意自己的系统架构，绝大多数现代电脑是 64 位系统，下载 x64 后缀的文件就行。如果你的电脑还是 32 位系统，就得找对应的 x86 版本。怎么确认系统位数？右键"此电脑"-"属性"，在系统类型一栏能看到。
3.2 安装向导的关键选项
拿到 .msi 文件后双击运行，安装过程大部分一路 Next 即可，但有一个界面非常重要，很多人就是在这里埋下了环境变量错乱的隐患。
安装向导会进入一个 "Custom Setup" 界面，里面默认勾选了 Node.js runtime、npm package manager 等几个组件。这里建议保持默认全选，同时留意底部的安装路径。默认路径是C:\Program Files\nodejs\，如果你介意 C 盘空间，可以改到其他盘符，比如D:\nodejs\。这里有一个实操要点：安装路径尽量不要带中文或空格，虽然新版安装器做了兼容处理，但某些底层 npm 包对路径中的非英文字符还是很敏感，包括后面会讲到的全局模块目录配置，也最好全部使用英文路径。
走到后面会出现一个 "Tools for Native Modules" 的勾选界面，这是询问是否自动安装编译原生模块所需的 Python 环境和 Visual Studio Build Tools。如果你只是做普通的 JavaScript 开发，这里可以不必勾选，减少安装时间和体积。但如果你知道自己后面会用到 node-sass、bcrypt、sharp 这类带原生 C++ 代码的包，那建议还是勾上，省得以后编译报错再回头补环境。
3.3 安装完成后的第一步验证
安装完成后，重新打开一个终端窗口（这里强调"重新打开"是有原因的，后面会在问题清单里详细解释），依次输入两条命令验证：
node -vnpm -v如果屏幕上分别输出了版本号，比如v20.19.0和10.8.2，说明 Node 和 npm 已经各自就位了。至此一个最基础、最干净的 Node 环境已经安装完成。
注意，我上面说的是"各自就位"，这里要先埋个伏笔，npm 的版本号和 Node.js 的版本号并不是一一对应的，不同的 Node 版本内置的 npm 版本也不同，后面你会见到那种"Node 版本明明挺新，但 npm 版本偏旧"的诡异情况，那个我们留到问题清单里细说。
4. 安装只是开始：环境变量配置完整拆解
4.1 自动配置了哪些东西
安装 .msi 时，安装器会在系统 PATH 中自动添加 Node.js 的安装目录，这就是为什么你能直接在终端里运行 node 和 npm 命令。多数情况下，安装完什么都不用动就能用。但为什么还有那么多人陷入"环境变量配置"的泥潭？因为实际开发中，你光能在终端里执行命令远远不够，还得考虑全局包的安装位置、缓存位置、权限问题、镜像源加速等一堆事情。
4.2 手动配置 PATH（自定义安装或绿色版）
如果你用的是 .zip 免安装版本，或 .msi 安装时修改了路径导致某些命令失效，那就需要手动配置 PATH。具体操作如下：
右键"此电脑"-"属性"-"高级系统设置"，进入"环境变量"。在"系统变量"里找到 Path 这一项，双击编辑，点击"新建"，把 Node.js 实际安装目录加进去，比如C:\Program Files\nodejs\。如果你想使用全局安装的 npm 包命令，还得把全局模块目录也加到 Path 里，默认是C:\Users\你的用户名\AppData\Roaming\npm。
改完之后，一定要记得点击所有对话框的"确定"按钮，关闭当前终端，重新打开一个新的终端窗口才能生效。终端窗口里的环境变量是在它启动那一刻从系统里读取的，不是实时刷新。
4.3 单独设置 npm 全局目录和缓存目录
这是很多老手都会做的一步"预防性设置"，新手往往不知道。npm 默认把全局安装的包放在系统盘用户目录下，缓存数据也在 C 盘。时间一久，C 盘空间会被各种依赖包占掉几十 GB，重装系统后一切归零。
为了把这一切挪走，建议在一开始就重设两个路径：
npm config set prefix "D:\nodejs\npm_global"npm config set cache "D:\nodejs\npm_cache"第一个命令把全局包安装目录改到 D 盘，第二个命令把 npm 的缓存目录改到 D 盘。执行完后，再去系统环境变量的 Path 里添加D:\nodejs\npm_global，这样全局安装的命令行工具就可以在任意目录下使用了。
这里有一个实操心得分享：如果你按这个方案做了，之后全局安装的任何包，可执行文件都会出现在D:\nodejs\npm_global目录下，打开这个目录看到一堆 .cmd 文件就说明全局工具注册成功。常见的问题是在全局安装某个 CLI 工具后，执行该命令提示"不是内部或外部命令"，几乎都是因为这一项没加进 Path。
4.4 两个配置文件的用户级隔离
刚才执行的npm config set命令，实际上是修改了一个配置文件。Windows 上这个文件在C:\Users\你的用户名\.npmrc。如果你打开这个文件，能看到刚才设置的内容以键值对的形式躺在里面：
prefix=D:\nodejs\npm_global cache=D:\nodejs\npm_cache理解这个文件非常有用，因为很多项目会在项目目录下再加一个 .npmrc 文件，用于覆盖全局设置。npm 对配置项的查找层级是：项目级 > 用户级 > 全局级，越具体的级别优先级越高。遇到"我在项目里设置了镜像源怎么不生效"这类问题时，基本都是优先级搞错了。
5. npm 核心配置：镜像源与依赖管理的实战经验
5.1 为什么必须配国内镜像源
npm 官方源服务器在国外，国内网络环境访问延迟很高，装个小包可能等几十秒，装个大项目能等到怀疑人生。解决方案是配置镜像源，目前使用最广泛的是 npmmirror.com，也就是原来的淘宝 npm 镜像，它每 10 分钟同步一次官方仓库，速度和稳定性都相当不错。
执行命令：
npm config set registry https://registry.npmmirror.com查看当前镜像源地址：
npm config get registry还有一个临时指定镜像源的用法，适合不想全局修改的场景：
npm install --registry=https://registry.npmmirror.com我自己用镜像源这么多年，给一个忠告：镜像源只是一个"下载加速通道"，它不会改变包的各种行为。网上偶尔有人说"用了镜像源装出来的包有问题"，绝大多数情况是别的原因造成的，不要因噎废食。
5.2 建议顺手开启的沙盒模式
从 npm 7 开始，npm install有了一种新的处理方式。默认情况下，npm install安装时会同时执行依赖包里的构建脚本（preinstall、install、postinstall），这既是便利也是安全隐患。npm 在较新版本中加入了--ignore-scripts选项，使用它会跳过后置脚本的执行。
对于普通项目来说，我建议在团队项目里约定使用npm install --ignore-scripts安装依赖，然后针对确实需要构建脚本的个别包单独放行。这个习惯在当前供应链攻击频发的环境下尤为值得养成。不过要注意，如果你安装的包确实依赖 postinstall 来编译原生模块（比如 esbuild、sharp 等），忽略脚本会导致它们无法正常工作，所以这个选项不是无条件使用，要看项目情况权衡。
5.3 使用 cnpm 还是直接用 npm
以前很多人会额外安装一个 cnpm 命令行工具来加速，因为老版本 npm 的某些机制在镜像源下表现不佳。现在 npm 本身已经支持 registry 配置，cnpm 的"独立安装器"属性反而容易造成依赖结构不一致的问题。
我的观点很明确：不要额外安装 cnpm，直接用npm config set registry就够了。如果你就是想用 cnpm 的某些特性，也建议仅在npx层面使用，而不要全局安装一个大而全的 cnpm 客户端。
6. 常见问题与排查技巧实录
6.1 问题速查表
下面这张表是我这些年帮人排查环境问题时最常遇到的场景汇总，几乎覆盖了热词里提到的所有坑。建议收藏备用。
| 现象 | 直接原因 | 解决方案 |
|---|---|---|
npm : 无法加载文件 ...npm.ps1，因为在此系统上禁止运行脚本 | PowerShell 执行策略限制 .ps1 文件 | 以管理员身份运行 PowerShell，执行Set-ExecutionPolicy RemoteSigned |
'npm' 不是内部或外部命令，也不是可运行的程序 | Node 安装目录或全局模块目录未加入 Path | 检查并添加环境变量，重启终端 |
node -v正常，npm -v报错 | npm 文件缺失或版本太旧 | 执行npm install -g npm@latest升级 npm |
| 安装包速度极慢或超时 | 正在访问官方源，网络延迟高 | 配置镜像源npm config set registry https://registry.npmmirror.com |
| npm install 报权限错误 | 全局目录为系统保护目录 | 修改 prefix 到用户目录或 D 盘目录 |
| 全局安装命令无法找到 | 全局模块目录未配置在 Path | 将 npm prefix 所在目录加入系统 Path |
| 同一个项目不同电脑装依赖结果不一致 | package-lock.json 未提交或 npm 版本差异 | 提交 lockfile，统一 npm 版本 |
| Node 版本正常但 npm 报版本不支持 | Node 版本过旧，新 npm 不支持 | 升级 Node 或降级 npm 版本，优先选用 LTS |
| 安装原生模块报编译错误 | 缺少 Windows 构建工具 | 以管理员身份运行npm install --global windows-build-tools，或安装 VS Build Tools |
6.2 高频报错：npm.ps1 执行策略限制
npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本，这可能是 Windows 新手遇到的最多的一条报错，也是搜索热词里反复出现的。它的本质是 PowerShell 的执行策略（Execution Policy）不允许运行 .ps1 脚本文件。npm 在 Windows 上通过一个 npm.ps1 脚本来启动，当系统安全策略限制脚本执行时，就被拦下来了。
解决办法分两种。如果只是想让 npm 和 node 正常工作，最简单的方案是在终端里使用 CMD 而不是 PowerShell，或者改用npm.cmd命令。但如果你希望在 PowerShell 里正常使用，管理员身份打开 PowerShell，执行下面的命令：
Set-ExecutionPolicy RemoteSigned这里解释一下RemoteSigned的含义：本地创建的脚本可以直接运行，从网络下载的脚本必须经过数字签名才能运行。npm 的脚本是随 Node 安装包一起落地的本地文件，所以这个策略既保证了系统安全，又能解决 npm 命令不可用的问题。
提示：执行策略修改后，如果公司电脑有统一的安全策略管理，重启后可能又被重置。遇到这种情况不用硬刚，检查是否存在组策略级别的强制限制。
6.3 高频报错：npm 因版本或依赖问题报错
热词里有两条 npm 报错值得单独解释：一条是npm warn deprecated node-domexception@1.0.0: use your platform's native DOMException，另一条是npm ERR! Cannot read properties of null (reading 'edgesout')。
前者其实是一个警告，不是错误。npm 在安装依赖时发现某个间接依赖包已经被原作者标记为废弃（deprecated），提示你应该改用平台原生的 DOMException。遇到这种情况，你不需要做任何事，它只是提醒，不会导致安装失败。想要排查这个废弃包被哪个依赖引入，可以执行npm ls node-domexception查看依赖链。
后者是一条地地道道的报错信息，出现在项目安装依赖的过程中。根据我排查的案例，绝大多数情况是因为 node_modules 目录损坏或 package-lock.json 与 package.json 不一致。解决办法按顺序尝试：先删除整个 node_modules 目录和 package-lock.json 文件，再重新执行npm install。如果仍然报错，可以清理缓存后重试：
npm cache clean --force再不行就降低 npm 版本或换 Node 版本试试。这类问题背后往往是某个依赖包的安装脚本生成了异常的输出，导致 npm 内部解析出错。工具链越乱，报错越离奇，这是规律。
6.4 为什么提示找不到模块？
Error: Cannot find module 'xxx'大概是任何 Node 开发者都见过的另一大类报错。常见场景是全局工具命令能执行，但过程中找不到某个模块；又或者一个项目之前跑得好好的，换个目录就报找不到模块。
排错的逻辑并不复杂：找不到模块就是 require/import 解析时，系统在查找路径下没找到目标文件。先用npm root -g查看全局 node_modules 路径，确认全局包是否真的安装在了这个目录下。再用npm list -g --depth=0列出全局顶层包，肉眼确认需要的包是否在列表里。如果包确实已安装但仍然找不到，检查 NODE_PATH 环境变量和项目里是否有局部覆盖的依赖。
这里分享一个真实案例：有位朋友装了全局的某个 CLI 工具，执行时一直报找不到模块opencv。排查半天，最后发现他之前手动设置了 NODE_PATH 指向一个已经删除的目录。局部配置覆盖了全局默认查找路径，引发了诡异现象。遇到莫名其妙的模块找不到问题，第一时间检查 NODE_PATH，这个变量的优先级极高，而且很多新手根本不知道它的存在。
7. 进阶方案：nvm 实现多版本 Node 共存管理
7.1 为什么需要多版本管理
做开发久了，你很容易遇到这种情况：公司老项目用的是 Node 14，语法特性和依赖包兼容性都停留在那个时代；自己接的私活或新项目用上了 Node 20，某些 npm 包要求更高的 Node 版本。如果电脑上只有一个 Node，每次切项目都要卸载重装，成本高到崩溃。nvm 的出现就是解决这个痛点，它允许你在一台机器上安装多个 Node 版本，并随时切换当前激活的版本。
Windows 上用的工具是 nvm-windows，和 Linux/macOS 的 nvm（nvm.sh）虽然命令相似，但底层实现完全不同，别搞混了。nvm-windows 是一个独立的应用程序，通过修改系统 PATH 环境变量来实现版本切换。
7.2 nvm-windows 安装与配置步骤
先去 nvm-windows 的 GitHub Releases 页面下载安装包（nvm-setup.exe），安装时它会自动检测或让你指定 Node.js 的安装目录。建议把 nvm 本体装到纯英文路径，比如D:\nvm。安装完成后重新打开终端，验证：
nvm version查看本机已安装的 Node 版本列表：
nvm list安装指定版本的 Node：
nvm install 20.19.0切换使用某个版本：
nvm use 20.19.0这里有一个新手很容易踩的坑：nvm-windows 在切换版本时，实际上修改的是系统 PATH 里 Node 目录的指向。所以切换到某个版本后，npm 也会跟着变成该版本自带的 npm。如果你之前用官方安装包装过 Node，建议先彻底卸载干净再装 nvm，否则两个工具的路径会冲突，出现"明明 nvm 切换了版本，终端里 node -v 还是老版本"的诡异问题。解决办法是进入"环境变量"设置，手动把残留在 Path 里的 Node 目录删掉。
7.3 nvm 和 nrm 搭配使用的技巧
很多人在 Node 版本切换之外还想管理多个 registry 源，会额外安装一个 nrm 工具。nrm 的全称是 npm registry manager，它的作用是在不同的 npm 镜像源之间快速切换。虽然现在 npm 本身也能通过--registry参数临时指定源，但如果你经常在各种源之间切换，nrm 的效率会高不少。
npm install -g nrmnrm lsnrm use taobao这个工具的用法没啥难度，主要提醒一点：nrm 切换到某个源后，它修改的还是你的用户级 .npmrc 文件。如果你后续用npm config set registry手改过，两者会产生覆盖关系，最终以 .npmrc 的内容为准。
8. 扩展场景：其他平台的自定义需求
8.1 Linux 离线安装 Node 环境
热词里有一条"linux离线安装node"，这个场景我遇到过几次，通常出现在内网开发环境或生产服务器不直接对外开放的场景。授人以鱼不如授人以渔，分享一个完整可行的手动方案。
在能联网的机器上，从 Node 官网下载对应系统架构的 Linux 二进制压缩包，例如：
wget https://nodejs.org/dist/v20.19.0/node-v20.19.0-linux-x64.tar.xz将压缩包拷贝到内网服务器，解压到指定目录：
tar -xJf node-v20.19.0-linux-x64.tar.xz -C /usr/local/创建软链接，让系统命令能直接找到 node 和 npm：
ln -s /usr/local/node-v20.19.0-linux-x64/bin/node /usr/bin/node ln -s /usr/local/node-v20.19.0-linux-x64/bin/npm /usr/bin/npm验证：
node -v npm -v如果还想配置全局模块目录，在用户目录的 .bashrc 或 .profile 里追加环境变量：
export NODE_HOME=/usr/local/node-v20.19.0-linux-x64 export PATH=$PATH:$NODE_HOME/bin执行source ~/.bashrc使配置生效。这种离线方式的优点是灵活、可控，不依赖系统的包管理器，缺点是要自己手工管理版本升级。还有一种方式是在内网搭建 npm 私服，或者从有网的机器上用npm pack把依赖打包再拷贝过去，但那属于另一个话题了。
8.2 两个容易忽略的验证操作
写在最后，分享两个非常小但非常实用的验证习惯。
安装完 Node 后，用一句命令看全链路状态：
npm config list这条命令会把你的各种配置项、镜像源、prefix、cache 目录全部列出来，一眼就能看出环境配置有没有问题。
还有一个是查看 Node 和 npm 对应的架构是否匹配。如果你在 Windows 上装了 x86 版本的 Node，但又用 x64 版本的全局命令行工具，某些依赖会出现诡异的兼容报错。排查架构问题可以执行：
node -p "process.arch"输出 x64 就是 64 位架构。
8.3 配合 VS Code 和前端框架的提醒
热词里还有不少关于 VS Code 配置 C/C++/Python 环境、Vue3 安装及环境配置的内容，这说明很多人在装 Node 的同时，其实是在搭一套完整的前端开发环境。Node 装好了之后，VS Code 里新建终端就能直接使用 node 和 npm 命令。但有一点值得提醒：VS Code 启动时继承的是它自身启动时的环境变量，如果你改了系统环境变量，建议完全关闭 VS Code 再重新打开，不要只关终端窗口，否则就会出现"系统环境变量明明加好了，VS Code 终端里还是提示找不到命令"的怪事。
至于 Vue3 项目的创建，环境配置好之后其实就是两条命令的事：
npm create vue@latestnpm install但很多人在执行npm install时又碰到各种版本兼容报错，这大多是 Node 版本和 Vue 生态依赖版本不匹配导致的。用 LTS 版本通常能规避大部分问题，如果要同时维护多个 Vue 项目，强烈建议用前面讲的 nvm 按项目切换 Node 版本。
拿环境问题来说，我觉得最值钱的不是某一两条命令，而是排查的思路：先分清是系统层面的问题（环境变量、PATH、权限），还是 npm 层面的问题（镜像源、缓存、依赖树损坏），再一层层缩小范围。对照着这篇教程里的问题速查表，绝大多数问题都能自己定位。如果哪天你被某个环境报错卡住了，试试先删 node_modules、清理缓存、检查 .npmrc、确认环境变量，多半能找到答案。
