上个月帮一位同事迁移开发环境时踩了一整天的坑。事情是这样的新入职的同事拿到一台离线测试机要把整套 Node.js 开发需要的环境搬过去nvm、nodejs、pnpm 一个都不能少。刚开始我以为拷贝几个文件夹就行结果发现如果不理解这三者各自的目录结构和管理机制离线迁移就是一场噩梦。后来我把整套流程跑通之后也把之前踩过的坑一起整理成了这篇记录希望能帮到要自己搭环境、或者正在给新同事和离线环境准备 Node 开发机的朋友。这篇文章以 Windows 环境为主macOS 和 Linux 的路径逻辑有差异但核心原理完全通用。内容适合刚接触 Node 生态的初学者也适合已经用 npm 很久但没折腾过 nvm 和 pnpm 的开发者。我会把整个搭建和迁移过程拆开讲不光是命令还会解释每一步为什么要这样做以及每个报错背后的真正原因。1. 整体思路与方案选型1.1 为什么是 nvm nodejs pnpm 这套组合先说个大背景。做过前端或者 Node 后端开发的人大概率都经历过这种场景项目 A 用的是 Node 16项目 B 要求 Node 18项目 C 内部工具链又依赖 Node 20。如果没有版本管理工具你得反复去官网下载安装包卸载重装光一个版本切换就能耗掉一个上午。nvm 的价值就在这里。它可以在同一台机器上同时安装多个 Node.js 版本用一条命令随时切换当前 PATH 里激活的版本。对 Windows 用户来说最常用的实现是 nvm-windows它和 macOS/Linux 上的 nvm 是两个不同的项目千万不要混为一谈后面我会单独说清楚它们的区别。nodejs 本身自带的 npm 是 Node 生态的老牌包管理器但它有一个比较明显的痛点每个项目都会生成一份自己的 node_modules100 个项目装了同一个依赖磁盘里就躺了 100 份副本。pnpm 之所以越来越流行就是因为它用“内容寻址存储 硬链接”的方式把同一版本的依赖在全局只保存一份然后通过硬链接放回每个项目的 node_modules 里。简单点类比以前的 npm 是每个人家里都囤一箱矿泉水pnpm 相当于小区里只有一个公共水仓每户门口放一个空桶用水的时候直接接过来。这套组合的实际运行逻辑就是nvm 管 Node 版本Node 自带 npmnpm 可以装 pnpmpnpm 负责真正管理项目依赖。平时开发和构建走 pnpm遇到需要切换 Node 版本时用 nvm 快速切整个工作流非常顺畅。1.2 离线迁移的核心逻辑离线迁移这个词听起来唬人本质上就是解决一个问题在没有外网的目标机器上如何让原本需要联网下载的所有东西都能直接可用。这里需要先建立一个概念。在线搭建环境时工具链的“完整状态”由三部分组成。第一部分是 nvm 目录里各个 Node 版本的实际文件第二部分是 pnpm 的全局 store也就是依赖缓存仓库第三部分是各类配置文件比如.npmrc、.pnpmrc、pnvm 的 settings.txt 等。这三样东西全部带齐离线机器上就能恢复出 90% 的开发环境剩下的只是让工具知道这些文件在哪里。很多人迁移失败就是只拷贝了项目代码到目标机器上执行pnpm install后才发现网络不通瞬间陷入“装不了依赖 什么都干不了”的僵局。反过来如果把 store 和配置文件一并带过去pnpm 在离线模式下一句pnpm install --offline就能从本地 store 里把所有依赖硬链接出来速度甚至比在线安装还快。所以整篇文章的主线就一条先讲清楚 nvm、nodejs、pnpm 各自的安装和配置细节再讲怎么把这三者的“状态”完整打包搬走最后总结各种报错的排查思路。2. nvm 的安装与配置实操2.1 下载安装nvm-windows 与 Linux 版不是同一样东西先强调一下容易踩的第一个坑。很多人到网上搜 nvm看到官方仓库叫 nvm-sh/nvm那是给 macOS 和 Linux 用的。Windows 上用的是另一个项目叫 nvm-windows作者是 coreybutler不要下载错。安装方式有两种。一种是下载nvm-setup.exe直接安装下一步下一步就完了非常省事。另一种是下载nvm-no-install.zip解压到某个目录自己配环境变量适合习惯手动管理工具链的开发者。我之前偷懒直接用安装包后来发现安装包会自动写环境变量省了很多手工配置的麻烦所以推荐新手直接选安装包方式。不过安装路径要特别注意。nvm 的整个工作是靠目录结构和符号链接实现的一旦路径里有中文、空格或者特殊符号后面很容易出现各种莫名其妙的错误。比如C:\Program Files\nvm4这种带空格的路径使用 nvm 时大概率会遇到命令找不到或者切换失败的问题。我自己的习惯是装到根目录下的一个纯英文路径比如D:\nvm4。装完之后打开系统环境变量会看到 nvm 自动添加了几项NVM_HOME指向 nvm 的安装目录比如D:\nvm4NVM_SYMLINK指向一个专门的软链接目录比如D:\nvm4\currentPATH里增加了%NVM_HOME%和%NVM_SYMLINK%这三项配置是 nvm 整个切换机制的关键。不理解也没关系等到后面遇到permission denied类的问题再回头看这段话你会恍然大悟。2.2 修改 settings.txt解决下载慢和默认架构问题安装包装完后nvm 目录下会生成一个settings.txt文件里面的内容大概是这样的root: D:\nvm4 path: D:\nvm4 arch: 64 proxy: none node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/其中arch表示默认下载 64 位还是 32 位的 Node 包现在新机器基本都是 64 位写死成 64 就行。重点提一下node_mirror和npm_mirror这两个是国家软件镜像站提供的 Node 发行版镜像地址。国内网络环境下面直接下载 Node 官方包经常慢到怀疑人生把这两个值配上后nvm install的下载速度会有一个质的提升。这个文件修改完不需要重启存盘后重新打开终端即可生效。如果之后执行nvm install提示找不到版本号或者下载地址不对问题多半出在 mirror 配置上。2.3 核心命令与切换原理nvm 的常用命令不多日常用到的基本就这几个nvm list // 查看本机所有 Node 版本带星号的是当前使用版本 nvm install 20.15.0 // 安装指定版本 nvm install lts // 安装最新长期支持版 nvm use 20.15.0 // 切换到指定版本 nvm alias default 20.15.0 // 设置默认版本新开终端后自动激活 nvm ls available // 列出可在线安装的所有版本第一次接触 nvm 的人可能会好奇为什么nvm use之后PATH 里不需要手工改东西因为 nvm 的切换操作实际上是删掉了NVM_SYMLINK这个目录里原有的符号链接再重新创建一个指向当前版本目录的链接。换句话说D:\nvm4\current永远指向“当前应该生效的那个 Node 版本”而 PATH 里的%NVM_SYMLINK%一直指向这个目录。这样一来无论你怎么切版本系统的 PATH 都不用变。这个机制理解后很多后续问题都能想通。举个例子某个全局命令行工具如果在安装时把路径写死到了某个具体版本目录nvm 一切换它可能就找不到了。这个坑我在后面章节还会专门讲。3. Node.js 的安装与环境变量配置3.1 用 nvm 安装 Node 并激活通过 nvm 安装 Node 不需要去官网下载安装包所有事情都在命令行里完成。我自己习惯先装一个 LTS 版本再看看项目需要什么额外版本。具体操作就是nvm install 20.15.0 nvm use 20.15.0安装完成后直接验证版本node -v npm -v这时候你会看到node -v输出版本号npm -v也会输出一个版本号。这里要留个心眼npm 的版本号是随 Node 版本捆绑的并不是全局独立安装的。每个 Node 版本的目录下都有自己的一套 npm这也是为什么后来通过npm i -g pnpm安装的 pnpm 会“跟随”当前 Node 版本走的原因——它被装进了当前激活的那个 Node 的全局目录里。3.2 配置 npm 镜像源与全局参数Node 装好之后npm 的默认源大概率是官方源。国内使用经常会遇到下载包超时的问题所以第一件事就是把它指到合法的镜像源。npm config set registry https://registry.npmmirror.com/可以通过npm config list看当前所有配置npm config list除了 registry还有两个经常被提及的配置项是prefix和cache。在 nvm 管理的 Node 环境下我不建议随便去改这两个值。为什么因为 npm 的全局包默认会安装到当前 Node 版本的目录下的node_modules中这个位置天然由 nvm 接管。如果你手工把 prefix 改到一个自定义目录短期内看似把全局包集中到了一处但后续切换 Node 版本时可能会出现全局工具和当前 Node 版本不匹配的兼容问题。如果你确实想把 npm 全局包固定到一个独立目录那就要做好“每次切换 Node 后手动处理依赖”的心理准备。对于大多数场景我建议让 npm 全局包随着 nvm 的版本目录走保持最简单、最不容易出错的路径逻辑。3.3 理解 Windows 下全局命令的执行顺序还有一个 Windows 特有知识点很多人在这里栽过跟头。npm i -g安装的全局工具在 Windows 下会生成一个同名目录里面至少有三个文件.cmd文件、.ps1文件、无扩展名的 shell 文件。在 PowerShell 中执行命令时系统会按照特定顺序去匹配这些文件而.ps1文件的执行又受“脚本执行策略”的约束。这就导致了网上最常见的一个报错npm : 无法加载文件 D:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这个报错的核心原因是 PowerShell 默认的 ExecutionPolicy 是Restricted不允许运行任何.ps1脚本。而 npm 在 PowerShell 下实际调用的就是npm.ps1因此被直接拦截。解决办法也很简单在管理员终端里执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser它只对本机用户生效不是系统全局的安全性可控。执行后重新打开终端npm 就不会再被拦截了。这个问题不解决后续安装 pnpm 也会遇到一模一样的报错所以建议装环境时顺便把这个执行策略一次改到位。4. pnpm 的安装与配置要点4.1 pnpm 的硬链接机制与现代 Monorepopnpm 能火绝不是营销出来的而是它在依赖管理上确实动了真格。用 npm 安装依赖时每个项目都会完整复制一份依赖树pnpm 则把所有依赖包的实体文件统一放在一个全局 store 里项目里的 node_modules 只是通过硬链接和符号链接指向这些实体。这意味着如果你有 50 个项目都依赖 React 18磁盘上只有一份 React 18 的真实文件其它全是链接。这种设计不仅省空间还能显著提升安装速度。更重要的是pnpm 对 Monorepo 有天然支持一个仓库里多个子包所有子包的依赖都抽到顶层 node_modules 和 store 里统一管理避免重复安装。现在的开源生态里像 Vite、Nuxt 这些知名项目都已经切换到了 pnpm可以说它是社区默认的前端包管理器。4.2 三种安装方式我最终选了哪一种pnpm 的安装方式大致有三种我逐一试过各有取舍。第一种是直接通过 npm 安装npm install -g pnpm这条命令最简单但前面已经分析过npm 的全局安装是跟着当前激活的 Node 版本走的。一旦你用 nvm 切换了 Node 版本原来的 pnpm 就找不到了。新开终端输入pnpm -v很大概率会提示“pnpm 不是内部或外部命令”。第二种是官方提供的独立脚本安装。Windows 下执行iwr https://get.pnpm.io/install.ps1 -useb | iex这条命令会从 pnpm 官网拉取安装脚本并把 pnpm 装到用户目录下一个固定的位置比如C:\Users\你的用户名\AppData\Local\pnpm。由于它不在任何特定 Node 版本目录里nvm 切换版本不会直接弄丢它。它仍然依赖 PATH 里的 node 命令来运行但工具本身是独立存在的。第三种是 Node 内置的 Corepack 机制。Node 16.13 以后的版本自带 Corepack执行corepack enable后就能直接使用 pnpm。听起来很优雅但实际使用中我遇到过 Corepack 下载 pnpm 包卡住的情况它背后的下载逻辑依然需要联网去拉二进制文件离线环境里一样会尴尬。我做了一张对比表方便直观比较方案安装效果对 nvm 切换的容忍度离线迁移友好度npm 全局安装装在当前 Node 版本目录差切换后命令丢失差独立脚本安装装在用户目录固定位置好切换后不受影响好整个目录拷走即可Corepack随 Node 版本管理一般依赖网络下载差离线更难处理我最终选择了独立脚本安装。原因很简单稳定、可迁移、不依赖具体 Node 版本。4.3 配置 store 目录和镜像源装完 pnpm 后最重要的一件事不是pnpm -v验证版本而是先把 store 目录固定到你自己想要的位置。pnpm 默认的 store 目录在 Windows 上通常位于用户缓存目录下面路径很长而且散落在 C 盘。后续如果要迁移或者清理找起来非常麻烦。我建议立刻把它改到专门的数据盘或某个固定的工具目录下pnpm config set store-dir D:\pnpm-store pnpm config set registry https://registry.npmmirror.com/此时可以执行pnpm config list检查配置是否生效。另外还有一个非常实用的命令pnpm store path它会直接输出当前 store 到底在哪。如果输出的路径和你配置的不一致说明可能项目级.npmrc里还设置有别的store-dir优先查一下项目目录下的.npmrc和环境变量。4.4 pnpm 与 workspace 配置的基本须知pnpm 在普通项目中可以直接使用但如果你的项目根目录下存在pnpm-workspace.yaml文件pnpm 就会把它当作一个 workspace 项目来对待并强制要求该文件包含packages字段。这个文件容易埋坑。我之前有一个旧项目不知道谁放了一个内容为空的pnpm-workspace.yaml结果执行pnpm install时报了一个让人摸不着头脑的错误ERR_PNPM_INVALID_WORKSPACE_CONFIGURATION packages field is missing or empty解决办法就是检查这个文件补上正确的字段。如果只是普通单包项目里面写packages: - **如果是 Monorepo则按实际子包目录来配置。另外还有一个经常用到的命令是pnpm link它用于把本地开发的库链接到当前项目相当于软链。对于本地私有库的联调一句pnpm link ../my-lib就能搞定后续改代码立即生效不需要反复 npm publish。5. 离线迁移的完整实操记录5.1 迁移前在源机器上先完成这些准备工作离线迁移的第一步不是在目标机器上折腾而是在源机器上把所有“状态”整理好。我总结了一个口诀叫“三目录两文件”你可以照着检查三目录指的是nvm 安装目录比如D:\nvm4里面包含所有已安装的 Node 版本和 settings.txtpnpm store 目录比如D:\pnpm-store里面是所有依赖包的实体缓存pnpm 安装目录也就是独立脚本安装的位置通常是C:\Users\你的用户名\AppData\Local\pnpm两文件指的是用户目录下的配置文件.npmrc记录 npm 和 pnpm 共享的 registry、store-dir 等配置.pnpmrc如果存在里面可能会有针对 pnpm 的额外全局配置在源机器上动手打包之前我建议先跑一遍全局包清单确认哪些工具需要在新环境保留npm ls -g --depth0 pnpm list -g接着做一个操作进入你已经拉好代码、并且执行过pnpm install的项目目录再跑一次pnpm install或者pnpm fetch。这样做的目的是把项目所有的依赖包索引进 store 里补齐确保 store 是最全的状态。这个过程可能在联网状态下很快但它直接决定了目标机器离线下能不能成功恢复。5.2 目标机器上恢复 nvm 和 Node 版本这一步有两种做法。做法一是全程离线安装。先把源机器的 nvm 整个目录拷贝到目标机器的同一个路径。比如源机器在D:\nvm4目标机器也放到D:\nvm4然后手工创建或修改环境变量把NVM_HOME、NVM_SYMLINK和 PATH 都指向对应目录。这样目标机器上的 nvm 直接就能看到所有已经存在的 Node 版本目录不需要联网下载。做法二是在目标机器上先正常安装 nvm 安装包然后把源机器 nvm 目录下各个v20.15.0之类的版本文件夹复制到目标机器 nvm 目录下的对应位置。这种方式更保险因为安装包会自动帮你把环境变量、注册表相关项配置齐全省去手工设置可能带来的遗漏。不管哪种方式都建议在恢复后打开新终端验证nvm list nvm use 20.15.0 node -v npm -vnvm list如果能看到一堆已存在的版本号说明安装目录被正确识别了。此时node -v和npm -v如果能正常输出版本号环境恢复就成功了一半。5.3 目标机器上恢复 pnpm 和 storepnpm 的恢复逻辑和 nvm 类似。因为源机器使用的是独立脚本安装整个 pnpm 目录本身就具备可迁移性。把它原样拷贝到目标机器同一个位置然后确认系统 PATH 环境变量里包含了 pnpm 对应的 bin 目录。如果目标机器上 PATH 没有自动添加手工加一下。然后验证pnpm -v pnpm store path这里有个非常重要的细节如果目标机器上的 store 目录路径与源机器不一致pnpm 需要重新初始化 store 的索引。最省事的方式是让 store 路径保持一致两边的.npmrc配置也保持一致这样从源机器拷贝过来的 store 就能被 pnpm 无缝识别。如果必须使用不同路径也不要慌。先把.npmrc里的store-dir改成新路径然后把源 store 目录复制到新路径下。pnpm 启动时会扫描 store 目录的内容重新建立索引文件虽然耗时取决于依赖包数量但不会影响最终结果。迁移完成后回到项目目录执行一次pnpm install --offline如果 store 完整这个命令会以极快的速度完成因为它不需要访问网络纯粹是“从本地仓库提取依赖并创建硬链接”。如果中途提示某个包缺失说明 store 不完整需要回到源机器把缺失的包补齐后再拷贝一次。5.4 为什么不能直接拷贝项目里的 node_modules很多第一次接触离线迁移的人会有一个直觉操作既然 node_modules 项目里已经有了直接把整个项目文件夹包括 node_modules 一起拷过去不就行了我可以非常明确地说pnpm 项目里千万别直接这么干。原因很简单pnpm 的 node_modules 里大量使用的是符号链接和硬链接结构。符号链接是相对当前路径建立的直接拷贝过去后目标机器上没有对应的 store 实体文件这些链接全部都会变成断链。即便能启动运行时会报一堆“找不到模块”的错误排查起来很痛苦。正确的做法是把项目代码连同 lockfilepnpm-lock.yaml一起拷过去然后把 store 也拷过去最后在目标机器上重新执行pnpm install --offline。pnpm 会对照 lockfile 检查 store 里是否有对应依赖有的话就直接从 store 里建立链接整个过程非常快。这里再补一个冷门但实用的命令pnpm store add。如果有一些不在 lockfile 里的离线 tgz 包可以通过这条命令手工添加到 store 中然后再用pnpm install --offline安装。虽然平时用到的场景不多但在私有包离线迁移时它是最可靠的兜底方案。6. 常见问题与排查技巧实录6.1 npm 或 pnpm 执行报 Permission Denied / 禁止运行脚本这个问题的完整报错通常长这样npm : 无法加载文件 D:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本 pnpm : 无法加载文件 C:\Users\xxx\AppData\Local\pnpm\pnpm.ps1因为在此系统上禁止运行脚本原因就是 PowerShell 的 ExecutionPolicy 限制导致.ps1脚本无法执行。解决方式之前说过管理员终端里执行一条命令Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这里我想补充两个细节。第一个修改之后要重新打开终端窗口很多人在当前窗口直接执行发现还是报错其实是 PowerShell 会话没有重新加载环境变量和策略。第二个如果公司设备管理策略锁死了 ExecutionPolicy不允许修改那么可以改用 CMD 窗口执行命令或者临时用powershell -ExecutionPolicy Bypass启动一个不受限制的终端来操作。6.2 提示“pnpm 不是内部或外部命令”或“无法将 pnpm 项识别为 cmdlet”这个报错出现的原因基本就是两个。第一种pnpm 确实装了但安装目录没有被加进 PATH 环境变量。第二种pnpm 是通过npm i -g pnpm安装的后来 nvm 切换了 Node 版本它随着旧版本一起“消失”了。排查顺序其实很快where pnpm如果提示找不到说明 PATH 里没有。先去检查源机器上安装 pnpm 时生成的那个目录路径把它手动加入 PATH重启终端。如果where pnpm能找到路径但执行还是报错那大概率是 nvm 切换导致全局命令路径变化。解决方式就是改用独立脚本安装或者切换到安装 pnpm 时的那个 Node 版本再重新执行npm i -g pnpm。6.3 nvm 切换 Node 版本后VSCode 里某些全局工具报 Permission Denied这个场景很经典比如你平时用 VSCode 的终端跑全局命令某天执行nvm use 20.15.0切到另一个版本后突然发现某个通过 npm 全局安装的工具报起了/xxx: Permission denied而且重启 VSCode 也没用。这里其实和 pnpm 的问题同源。很多 CLI 工具在安装时会把自己的 shim 或者执行入口放到当时激活的 Node 版本的全局目录里或者把 PATH 中的某个路径写死。nvm 一切换版本原来的 shim 入口路径失效新的版本目录下又没有这个工具的安装记录自然就报“permission denied”。解决思路有两个。一个是把那个工具在“当前激活的 Node 版本”下重新安装一遍让它的 shim 指向新的版本目录。另一个是如果你希望它不随 nvm 变化就使用工具的独立安装方式把它装到用户目录通过固定的 PATH 入口去调用。我个人在后面遇到这种情况时会选择后者它从根上解决了“nvm 一切换全局工具就失踪”的问题。6.4 报错 ERR_PNPM_INVALID_WORKSPACE_CONFIGURATION这个报错的排查方法前面提过直接看项目根目录下有没有pnpm-workspace.yaml。有就打开检查packages字段是否存在、是否为空格式是否合法。没有文件的话还要检查一下是不是命令敲错了比如在 monorepo 根目录执行pnpm install时误把 workspace 配置文件删了也会触发这个错误。补充一个容易被忽略的点pnpm-workspace.yaml里如果 glob 写错了会把一些不该当成子包的东西识别成 workspace 包导致 install 时出现奇怪的依赖提醒。建议是非 monorepo 项目干脆不要放这个文件放了就保证它内容是完整的。6.5 pnpm 在线安装下载失败或超时在线安装 pnpm 或安装项目依赖时如果频繁出现“ETIMEDOUT”“ECONNRESET”“Failed to find response”之类的错误绝大多数情况是网络问题。优先检查镜像源是否配置正确pnpm config get registry如果指向的是官方源建议改成镜像源。如果已经配置了镜像还是失败那就是代理或内网限制问题。可以试试关闭系统代理或者临时在命令行里设置环境变量告诉 pnpm 不要走代理。离线环境下最好的做法是提前在联网机器上把 store 补齐然后走--prefer-offline或--offline安装这是我最推荐的方案。6.6 报错信息速查表报错信息核心原因快速解决方案npm.ps1 / pnpm.ps1 禁止运行脚本PowerShell ExecutionPolicy 限制执行Set-ExecutionPolicy RemoteSignedpnpm 不是内部或外部命令pnpm 目录不在 PATH 或随 nvm 切换丢失修改 PATH 或改用独立脚本安装/xxx: Permission deniednvm 切换后全局命令 shim 路径失效在目标 Node 版本下重装该工具或独立安装ERR_PNPM_INVALID_WORKSPACE_CONFIGURATIONworkspace yaml 缺少 packages 字段补全packages配置下载超时 ETIMEDOUT / ECONNRESET网络源不稳定或代理干扰配置镜像源、临时关代理pnpm shim points back at the shim独立脚本安装或环境变量冲突清理旧 shim重新用脚本安装并检查 bin 路径写在最后的一点实际经验把所有过程走完之后我最大的体会是离线迁移最关键的不是“拷贝文件”而是理解 nvm、nodejs、pnpm 各自把状态放在了哪里。nvm 的 Node 版本在 nvm 目录pnpm 的依赖实体在 store配置文件在.npmrc和.pnpmrc。把这三个位置搞清楚离线迁移其实就是在搬三样东西剩下的只是换了个路径重新告诉工具“东西在这里”。所以如果让我给一个建议那就是不要等到要迁移了才去整理环境。从搭建第一天起就把 nvm 目录、pnpm store、全局配置放在固定的、可预期的路径下并且写进自己的环境初始化脚本里。这次是离线迁移下次可能就是新电脑入职、服务器部署甚至是公司内网环境整体搬迁这套思路都能直接复用到不同场景。我个人还有一个比较“笨”但很有效的习惯每次搭建完环境都会把当时的node -v、npm -v、pnpm -v、pnpm store path这几个输出结果存成一个environment.txt放到项目目录里。未来不管是自己换机器还是同事遇到环境问题翻出这个文件按图索骥比靠回忆排查高效得多。