npm install安装离线包的实现过程

npm install 完全可以安装离线包，但这需要你提前做好充分的准备工作。这是企业内网开发、构建安全环境（air-gapped environments）和确保依赖稳定性的核心技能。

核心原理是：

让 npm 绕过网络请求，直接从本地缓存或指定的本地文件/目录中获取包。

以下是几种不同的离线安装方法，每种方法适用于不同的场景：

方法一：使用 npm 的离线缓存（最常用、最推荐）

这是最标准的离线安装方式。它利用了 npm 自身的缓存机制。

工作原理

• 在线准备：在一台有网络的机器上，运行 npm install 将所有依赖（包括子依赖）完整地下载到 npm 的全局缓存目录（~/.npm）中。
• 转移缓存：将整个缓存目录打包，复制到离线机器上。
• 离线安装：在离线机器上，通过环境变量指向这个准备好的缓存目录，并使用 --offline 参数安装。

详细步骤

在线环境准备缓存：

# 1. 在联网机器上，进入项目目录，正常安装所有依赖
cd my-project
npm install

# 2. 此时所有包的.tgz文件都已存储在 ~/.npm 目录中
# 3. 将整个 ~/.npm 缓存目录打包拷贝到离线环境
tar -czf npm-cache.tar.gz ~/.npm

离线环境安装：

# 1. 将打包的缓存文件解压到离线机器的某个目录，例如 /path/to/offline-cache/
tar -xzf npm-cache.tar.gz -C /path/to/offline-cache/

# 2. 设置环境变量，让npm使用这个准备好的缓存
export npm_config_cache="/path/to/offline-cache/.npm"

# 3. 强制npm使用离线模式进行安装
npm install --offline

• 优点：能处理复杂的依赖树，是管理整个项目依赖的最佳实践。
• 缺点：需要提前准备整个缓存目录，可能会很大。

方法二：直接安装本地.tgz包文件

如果你只有一个单独的离线包文件（.tgz 格式），可以直接安装它。

操作步骤

# 在联网机器上，打包某个包
npm pack electron
# 这会生成一个类似 electron-28.0.0.tgz 的文件

如何获取 .tgz 文件？

从 npm registry 官网下载。

使用 npm pack 命令打包一个你已经有的包：

# 在联网机器上，打包某个包
npm pack electron
# 这会生成一个类似 electron-28.0.0.tgz 的文件

• 优点：非常简单直接，适合安装单个独立的包。
• 缺点：无法自动处理这个包所依赖的其他包。如果这个 .tgz 包有依赖，而你的离线环境没有，安装会失败。

方法三：从本地文件系统链接（file:协议）

你可以将依赖包放在一个本地文件夹中（比如一个U盘或内网文件共享），然后在 package.json 中直接指向它。

操作步骤

准备离线包目录：在离线环境中，创建一个目录（如 ./offline-packages/）存放所有你需要的包的 .tgz 文件。

修改 package.json：将依赖的版本号改为 file: 协议路径。

{
  "dependencies": {
    "electron": "file:./offline-packages/electron-v28.0.0.tgz",
    "lodash": "file:./offline-packages/lodash-4.17.21.tgz"
  }
}

运行安装：

npm install

• 优点：配置清晰，版本管理方便。
• 缺点：需要手动管理 package.json 中的路径，同样可能无法处理嵌套依赖。

方法四：搭建离线镜像仓库（最专业）

对于大型团队或企业，最彻底的方法是搭建一个内网专用的 npm 镜像仓库。

常用工具：Verdaccio、nexus Repository Manager

工作流程：

• 在可联网的机器上搭建 Verdaccio。
• 通过 Verdaccio 代理所有 npm 请求，它会自动缓存所有下载过的包。
• 将这台机器上的 Verdaccio 存储目录打包，迁移到离线网络。
• 在离线网络中的机器上配置 npm registry 指向内网的 Verdaccio 地址（如 http://internal-ip:4873/）。
• 此后，所有 npm install 命令都会从这个内网镜像获取包。

优点：对开发者最透明，体验与联网几乎无异，能完美处理所有依赖。

缺点：搭建和维护有一定复杂度。

重要注意事项总结

1.处理嵌套依赖：方法一（缓存）和方法四（镜像）是唯一能自动处理嵌套依赖的方法。方法二和方法三需要你手动下载所有子依赖的包，非常繁琐。

2.Electron 等二进制包：对于像 electron 这样包含平台特定二进制文件的包，离线安装需要额外步骤。除了 npm 缓存，你还需要：

• 提前下载好对应平台的 Electron .zip 文件。
• 设置 ELECTRON_MIRROR 或 ELECTRON_OVERRIDE_DIST_PATH 环境变量来指向这些文件的存放位置。否则，安装脚本依然会尝试联网下载二进制文件而导致失败。

3.版本一致性：离线环境下，必须严格保证你准备的离线包版本与 package.json 中要求的版本完全匹配，否则安装会失败。

结论

答案是肯定的，npm install 能安装离线包。 

其中，使用 --offline 参数并配合准备好的 npm 缓存目录（方法一） 是最通用、最可靠的方式，适用于绝大多数项目离线部署的场景。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

最新评论