npm install断网默认失败是因为v6+版本强制联网校验元数据,需用--cache、--offline、--no-package-lock三参数组合才能离线安装,且缓存必须完整预热并避免跨平台拷贝。

能行,但必须提前在有网机器上完成缓存预热,且离线时不能依赖 npm install 的默认行为——它会主动联网校验,直接报错。
为什么 npm install 在断网时默认失败
npm 从 v6 开始默认启用 registry 连通性检测,即使本地有包,也会尝试向 registry.npmjs.org 发起 HEAD 请求验证元数据。断网时触发 network timeout 或 getaddrinfo ENOTFOUND registry.npmjs.org,安装中断。
- 不是缓存没生效,是 npm 主动“拒绝信任本地缓存”
-
--offline参数才是强制禁用网络的开关,不是可选项 - 缓存路径必须显式指定,否则离线机可能读不到你预存的缓存
如何正确预热并导出 npm 缓存
在有网机器上,不要只跑一次 npm install 就完事。缓存目录(~/.npm)里混着元数据、tarball、index,但 npm 不保证所有内容都可用于离线安装。
- 用
npm install --cache /path/to/offline-cache --prefer-offline安装依赖,确保 tarball 和content-v2元数据写入指定路径 - 执行
npm cache verify --cache /path/to/offline-cache确认完整性(会清理损坏条目) - 打包整个缓存目录(不是只拷
_cacache子目录),Windows 下常见路径是C:\Users\<user>\AppData\Local\npm-cache</user> - 避免跨平台拷贝:macOS/Linux 的缓存无法在 Windows 上直接复用
离线机上必须加的三个参数
只写 npm install 会失败;只写 --offline 会因找不到缓存路径而报 ENOENT: no such file or directory, open '/tmp/xxx/index.json'。
-
--cache ./npm-cache:指向你拷过来的缓存目录(相对路径需在项目根目录下) -
--offline:彻底关闭网络请求,不试探、不 fallback -
--no-package-lock(可选但推荐):避免生成或验证package-lock.json中的 integrity 字段——该字段依赖远程 registry 签名,离线时校验必挂
完整命令示例:npm install --cache ./npm-cache --offline --no-package-lock
VSCode 终端里跑不起来?检查这三件事
VSCode 内置终端默认不继承系统级 npm 配置,尤其在 Windows PowerShell 下,npm 命令本身可能就找不到。
- 确认 VSCode 终端启动的是你预期的 shell(比如 cmd.exe 而非 PowerShell),或在设置里改
terminal.integrated.defaultProfile.windows - 不要依赖全局
npm,改用npx --no-install npm install --cache ...,绕过 PATH 查找 - 如果项目用了
node_modules/.bin下的本地二进制(如vue-cli-service),确保node_modules已存在且权限正常——离线部署时它常被误删或解压损坏
最易被忽略的点:缓存目录里的 content-v2 子目录必须完整,里面每个包的 .tgz 文件和对应哈希文件缺一不可;少一个,--offline 模式下 npm 就会静默跳过该包,而不是报错提醒你——最后 node_modules 缺模块,运行时报 Cannot find module 才发现,但已没法补救。


















