离线安装npm包的核心是固化完整依赖树：推荐用package-lock.json配合npm install --offline打包缓存；或用npm pack生成tgz包；或搭本地registry。须确保Node/npm版本一致、原生模块架构匹配、严格依赖lock文件。
在离线环境打包和传输 npm 依赖包，核心是把 完整的、可复现的依赖树 提前从联网机器上“固化”为本地可搬运的文件，再安全转移到目标机器。不靠拷 node_modules（易出兼容问题），也不靠临时手动下载（漏依赖风险高）。关键在于利用 npm 自身机制生成确定性产物。
用 package-lock.json + npm install --offline 打包缓存
这是最推荐、最接近标准流程的方法，适用于整个项目部署。
- 在联网机器上，确保项目有
package-lock.json（没有就先npm install生成） - 执行
npm install --prefer-offline，让 npm 尽可能只读缓存，避免触发新下载 - 运行
npm config get cache查到缓存路径（如~/.npm），然后完整打包：tar -czf npm-cache.tar.gz ~/.npm - 把
npm-cache.tar.gz和项目目录（含package.json、package-lock.json）一起拷到离线机 - 在离线机解压缓存，并设置环境变量：
export npm_config_cache="/path/to/extracted/.npm"
再进项目目录执行：npm install --offline
用 npm pack 批量生成 .tgz 包
适合需要分发、归档或上传到私有仓库的场景，产物是每个包独立的 name-version.tgz 文件。
- 在联网机器的项目目录下，先确保
node_modules已完整安装 - 运行脚本（或使用社区工具如
npm-pack-all）遍历node_modules，对每个子模块执行：npm pack <package-name>@<version>（版本必须精确匹配package-lock.json中的 resolved 字段） - 所有生成的
.tgz文件统一移入packs/目录 - 把整个
packs/目录拷到离线机，在目标项目中逐个安装：npm install ./packs/lodash-4.17.21.tgz ./packs/axios-1.6.8.tgz ...
用 npm ci + 自定义 registry 搭建轻量本地源
适合团队长期维护多个离线环境，一次准备、多次复用。
立即学习“Java免费学习笔记（深入）”；
- 在联网机上，用
verdaccio启动一个本地 registry：docker run -it --name verdaccio -p 4873:4873 verdaccio/verdaccio - 配置 npm 使用该源：
npm config set registry http://localhost:4873 - 用
npm install触发所有依赖下载到 verdaccio 的存储目录（默认./storage） - 把
./storage整个目录打包，传到离线机；离线机启动相同 verdaccio 容器并挂载该目录 - 目标项目只需设
npm config set registry http://离线机IP:4873，再运行npm ci即可全量安装
注意事项与避坑点
无论选哪种方式，都要注意：
-
Node.js 和 npm 版本必须一致：离线机的
node -v和npm -v必须与联网机准备时完全相同，否则package-lock.json解析可能失败 -
原生模块需额外处理：像
sqlite3、sharp这类含二进制的包，必须在目标系统架构（Linux/macOS/Windows）和 CPU 类型（x64/arm64）相同的机器上打包，否则无法加载 -
不要跳过 lock 文件：仅靠
package.json安装会导致版本漂移，离线环境下必须严格依赖package-lock.json或yarn.lock -
验证安装结果：离线安装完成后，建议运行
npm ls <package-name>确认版本和路径，再执行简单 require 测试是否能加载
