离线安装npm包的几种方法

在开发环境中，网络不稳定或完全离线的情况时有发生。无论是企业内部封闭网络、移动设备开发，还是需要严格管控依赖版本的场景，离线安装npm包的能力都显得尤为重要。本文将系统梳理四种主流的离线安装方法，涵盖从基础缓存利用到高级私有仓库搭建的全流程，并提供可落地的操作指南。

一、依赖本地缓存安装

npm默认会将下载的包存储在本地缓存目录（~/.npm或%APPDATA%\npm-cache），这一机制为离线安装提供了基础支持。

1.1 缓存目录定位与验证

首先确认缓存目录位置：

npm config get cache
# 或通过环境变量
echo $npm_config_cache  # Linux/macOS
echo %npm_config_cache% # Windows

进入目录后，可见按包名和版本号组织的子目录，例如@angular/core@12.0.0。每个子目录包含完整的包文件（.tgz压缩包）和元数据。

1.2 离线安装流程

步骤1：提前缓存目标包

npm install <package-name> --cache-min 999999999  # 强制使用缓存

--cache-min参数确保即使存在更新版本，npm也会优先使用本地缓存。

步骤2：离线安装
断开网络后执行：

npm install <package-name> --offline

若提示--offline不可用，可手动指定缓存路径：

npm install <package-name> --cache=./custom-cache --preferred-cache=./custom-cache

1.3 局限性

• 仅适用于已缓存的包版本，新版本需重新联网下载
• 依赖树中的间接依赖需手动确保缓存
• Windows系统可能因路径长度限制导致缓存失败

二、使用verdaccio搭建私有仓库

Verdaccio是一个轻量级的私有npm代理仓库，支持离线环境下的包管理。

2.1 安装与配置

npm install -g verdaccio
verdaccio --config ./custom-config.yaml  # 自定义配置文件

配置文件示例：

storage: ./storage  # 本地存储路径
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    cache: true  # 启用缓存
packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs

2.2 离线使用流程

步骤1：初始化缓存

npm set registry http://localhost:4873
npm install <package-name>  # 首次下载会缓存到verdaccio存储

步骤2：离线模式
修改配置文件关闭uplinks或直接断开网络，后续安装将直接从本地存储获取：

npm install <package-name> --registry=http://localhost:4873

2.3 高级功能

• 权限控制：通过auth配置实现用户认证
• 镜像同步：定时同步远程仓库到本地
• 多环境隔离：为不同项目配置独立存储路径

三、打包压缩依赖并手动解压

适用于完全无网络的环境，需提前准备依赖包。

3.1 生成依赖包

npm pack <package-name>  # 生成.tgz文件
# 或打包整个node_modules
tar -czvf dependencies.tar.gz node_modules/

3.2 离线安装

方法1：直接安装.tgz文件

npm install ./<package-name>-<version>.tgz

方法2：解压后安装

tar -xzvf dependencies.tar.gz
cd node_modules/<package-name>
npm install --production  # 仅安装生产依赖

3.3 注意事项

• 需同时打包package-lock.json或yarn.lock确保版本一致
• 间接依赖需递归打包
• Windows系统建议使用7-Zip等工具处理.tar.gz文件

四、配置离线镜像源

适用于有内部网络但无法访问公网的场景。

4.1 搭建内部镜像

使用Nexus、Artifactory等工具搭建私有仓库，或通过npm mirror脚本同步：

git clone https://github.com/rlidwka/sinopia-npm-mirror.git
cd sinopia-npm-mirror
node mirror.js  # 同步指定包到本地目录

4.2 配置客户端

修改.npmrc文件：

registry=http://internal-mirror:8080/
strict-ssl=false  # 若使用自签名证书

4.3 批量同步策略

• 增量同步：通过npm view <package> versions获取版本列表，仅下载新版本
• 全量同步：定期执行完整镜像，适合依赖稳定的项目
• 差分同步：对比本地与远程仓库的元数据，仅传输变更部分

五、最佳实践建议

1. 版本锁定：始终使用package-lock.json或yarn.lock固定版本
2. 混合策略：核心依赖用私有仓库，临时依赖用本地缓存
3. 自动化工具：编写脚本自动打包依赖并生成安装指南
4. 安全审计：离线安装前验证包的完整性和来源
5. 文档记录：维护离线包清单，包括版本、哈希值和获取来源

六、常见问题解决

• 缓存失效：清除缓存后重新下载（npm cache clean --force）
• 权限错误：确保对缓存目录有读写权限
• 依赖冲突：使用npm ls检查依赖树，手动解决版本冲突
• 性能优化：对大体积包启用压缩传输（npm config set progress false）

通过综合运用上述方法，开发者可以构建适应不同离线场景的依赖管理体系。实际选择时需权衡部署复杂度、维护成本和功能需求，例如小型项目适合本地缓存，大型团队推荐私有仓库方案。