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_globalnpm 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。如果你打开这个文件能看到刚才设置的内容以键值对的形式躺在里面prefixD:\nodejs\npm_global cacheD:\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 --registryhttps://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 RemoteSignednpm 不是内部或外部命令也不是可运行的程序Node 安装目录或全局模块目录未加入 Path检查并添加环境变量重启终端node -v正常npm -v报错npm 文件缺失或版本太旧执行npm install -g npmlatest升级 npm安装包速度极慢或超时正在访问官方源网络延迟高配置镜像源npm config set registry https://registry.npmmirror.comnpm 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 Tools6.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-domexception1.0.0: use your platforms 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 --depth0列出全局顶层包肉眼确认需要的包是否在列表里。如果包确实已安装但仍然找不到检查 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 的 nvmnvm.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安装指定版本的 Nodenvm 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 和 npmln -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 vuelatestnpm install但很多人在执行npm install时又碰到各种版本兼容报错这大多是 Node 版本和 Vue 生态依赖版本不匹配导致的。用 LTS 版本通常能规避大部分问题如果要同时维护多个 Vue 项目强烈建议用前面讲的 nvm 按项目切换 Node 版本。拿环境问题来说我觉得最值钱的不是某一两条命令而是排查的思路先分清是系统层面的问题环境变量、PATH、权限还是 npm 层面的问题镜像源、缓存、依赖树损坏再一层层缩小范围。对照着这篇教程里的问题速查表绝大多数问题都能自己定位。如果哪天你被某个环境报错卡住了试试先删 node_modules、清理缓存、检查 .npmrc、确认环境变量多半能找到答案。