当前位置：首页 > news >正文

npm install 安装离线包的方法

news 2025/8/29 10:27:35

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
工作流程：
1. 在可联网的机器上搭建 Verdaccio。
2. 通过 Verdaccio 代理所有 npm 请求，它会自动缓存所有下载过的包。
3. 将这台机器上的 Verdaccio 存储目录打包，迁移到离线网络。
4. 在离线网络中的机器上配置 npm registry 指向内网的 Verdaccio 地址（如 http://internal-ip:4873/）。
5. 此后，所有 npm install 命令都会从这个内网镜像获取包。

优点：对开发者最透明，体验与联网几乎无异，能完美处理所有依赖。
缺点：搭建和维护有一定复杂度。

重要注意事项总结

处理嵌套依赖：方法一（缓存）和方法四（镜像）是唯一能自动处理嵌套依赖的方法。方法二和方法三需要你手动下载所有子依赖的包，非常繁琐。
Electron 等二进制包：对于像 electron 这样包含平台特定二进制文件的包，离线安装需要额外步骤。除了 npm 缓存，你还需要：
- 提前下载好对应平台的 Electron .zip 文件。
- 设置 ELECTRON_MIRROR 或 ELECTRON_OVERRIDE_DIST_PATH 环境变量来指向这些文件的存放位置。否则，安装脚本依然会尝试联网下载二进制文件而导致失败。
版本一致性：离线环境下，必须严格保证你准备的离线包版本与 package.json 中要求的版本完全匹配，否则安装会失败。