基于VSCode的Node项目在没有互联网时利用NPM缓存进行无网络依赖部署

离线环境下的npm依赖部署：一套完整的缓存方案

先说关键结论：在完全断网的机器上跑 npm install，确实能实现依赖安装，但必须满足两个前提——缓存要在有网机器上提前“预热”，并且离线时不能指望npm的默认行为。为什么呢？因为npm从v6开始，默认就会主动联网校验包信息，一旦发现连不上，直接报错中断。

为什么 npm install 在断网时默认失败

问题出在npm v6之后的一个设计选择上：它默认会向 registry.npmjs.org 发送HEAD请求，来验证元数据的有效性。哪怕本地已经缓存了完整的包文件，npm也要先确认远程registry能连上再说。断网时，这一步必然触发 network timeout 或 getaddrinfo ENOTFOUND registry.npmjs.org，安装自然就此中断。

所以，问题的关键不在于“缓存有没有”，而在于npm的联网策略。几个值得注意的细节：

• 缓存并非没生效，而是npm主动选择了不信本地缓存
• --offline 参数是强制关闭联网的开关，不是可选项
• 缓存路径必须显式指定，否则离线机读不到你辛苦预存的内容

如何正确预热并导出 npm 缓存

在有网机器上，只跑一次 npm install 是不够的。默认的缓存目录（~/.npm）里会混着元数据、tarball、索引文件，但npm并不保证所有内容都适用于离线安装。关键步骤有三：

第一，用专用命令安装依赖：npm install --cache /path/to/offline-cache --prefer-offline，确保tarball和 content-v2 元数据都写入指定路径，而不是散落在系统默认缓存里。

第二，执行 npm cache verify --cache /path/to/offline-cache 来检查完整性。这一步会清理掉损坏的条目，避免离线时因缓存文件不完整而出问题。

第三，打包整个缓存目录——不要只拷 _cacache 子目录。Windows下的典型路径是 C:UsersAppDataLocalnpm-cache，整个目录直接打包带走。

值得特别提醒的是：macOS和Linux的缓存文件无法直接在Windows上复用，反之亦然。如果需要跨平台部署，建议在对应平台上分别准备缓存。

离线机上必须加的三个参数

只写 npm install 会失败；只写 --offline 也可能导致问题——因为它不知道去哪个目录找缓存，结果会报 ENOENT: no such file or directory 的错误。真正有效的命令需要三个参数组合：

• --cache ./npm-cache：指向你拷贝过来的缓存目录。使用相对路径时，确保这个目录在项目根目录下。
• --offline：彻底关闭网络请求，不试探、不fallback、不报错——完全信任本地缓存。
• --no-package-lock：可选但强烈推荐。这个参数可以绕过 package-lock.json 中的integrity字段校验——该字段依赖远程registry签名，离线模式下必然失败。

完整的命令示例：npm install --cache ./npm-cache --offline --no-package-lock

VSCode 终端里跑不起来？检查这三件事

不少人在VSCode终端里执行上述命令时，依然会碰到问题。常见的原因有三：

第一，VSCode的内置终端默认不继承系统级的npm配置。尤其是在PowerShell环境下，npm 命令自身可能都无法正常调用。解决办法是确认终端启动的是你预期的shell（比如cmd.exe而非PowerShell），或者在设置里修改 terminal.integrated.defaultProfile.windows 为cmd。

第二，尽量不依赖全局安装的npm。推荐用 npx --no-install npm install --cache ... 来执行，这样可以绕过PATH查找的问题。

第三，如果项目中使用了 node_modules/.bin 下的本地二进制工具（例如 vue-cli-service），务必确保 node_modules 已存在且权限正常。离线部署时，这个目录容易被误删，或者解压后权限异常，导致工具链无法运行。

还有一个极易被忽视但后果严重的问题：缓存目录里的 content-v2 子目录必须完整。每个包的 .tgz 文件和对应的哈希文件缺一不可——少一个，npm在 --offline 模式下不会报错，而是静默跳过该包。最后你发现 node_modules 里缺模块，运行时才弹出 Cannot find module 的提示，但已经没法补救。所以，缓存预热这一步，务务必认真。