前端项目离线打包方案

各位大佬早上好、中午好、晚上好

在现代前端开发中，项目通常通过包管理工具（如npm、yarn或pnpm）来管理第三方依赖。这些工具通过执行npm install xxx 、yarn add xxx 或pnpm add xxx等命令，从npm仓库下载所需的包及其依赖项，并将其安装到项目的node_modules目录中。

需求场景

在某些特殊环境下（如企业内网、保密项目或网络受限场景），我们需要实现前端项目的离线打包能力，确保在没有互联网连接的情况下也能完成项目的构建和部署。

开发流程分析

标准的前端项目开发流程通常包含以下步骤：

项目拉取

通过git clone <项目地址> 命令将项目代码克隆到本地

依赖安装

执行npm install（或yarn/pnpm等效命令），该命令会：

a. 读取项目package.json文件

b. 解析所有直接依赖和间接依赖

c. 从npm仓库下载所有依赖包

d. 将依赖安装到node_modules目录

项目启动

执行npm run start命令，此时构建工具（如webpack、vite等）会在开发环境下进行打包，这一过程通常不需要网络连接。

构建阶段分析

执行npm run build命令时，构建工具会：

● 读取项目源代码和node_modules中的依赖

● 进行代码转换、打包和优化

● 生成最终的生产环境构建产物

关键点：构建过程本身不需要网络连接，只要确保node_modules中包含所有必需的依赖即可。

离线环境解决方案

方案一：预先下载所有依赖

在有网络的环境中：

a. 执行npm install下载完整依赖

b. 将整个node_modules目录备份或归档

在离线环境中：

a. 恢复node_modules目录到项目根目录

b. 执行构建命令

当项目需要新增第三方库时（例如需要安装quill富文本编辑器），可采用以下方法：

在有网络的环境中：

a. 执行npm install quill下载该库及其依赖

b. 将新增的依赖从node_modules中提取出来

c. 通过移动存储设备将这些依赖拷贝到离线环境

d. 将新增依赖手动放入项目的node_modules目录

e. 更新package.json和package-lock.json（或yarn.lock/pnpm-lock.yaml）文件

f. 执行构建命令

使用npm-pack-all工具

a. 为了将npm库打包成.tgz文件，需要安装npm-pack-all工具

css 复制代码

npm install -g npm-pack-all

b. 下载需要打包的npm库

复制代码

npm install -g quill

这会将 selenium-webdriver 及其依赖项安装到 %userprofile%\AppData\Roaming\npm\node_modules 目录下

c. 生成.tgz文件：进入到上面node_modules/quill下执行npm-pack-all命令，将其依赖项打包，执行完后，您将在当前目录下生成一个以 .tgz 为后缀的压缩文件

d. 将 .tgz 文件复制到离线环境中的项目目录。

e. 在该目录下执行以下命令安装包

bash 复制代码

npm install ./xxx.tgz

这将安装 quill 及其依赖项，而无需访问外部网络.

方案一有很大缺陷就是需要人工手动维护依赖，复杂且易出错。

方案二：使用verdaccio

Verdaccio 是一个轻量级、开源的私有 npm 代理注册表（npm registry），专为 Node.js 开发者设计，用于搭建企业或团队内部的 npm 包管理仓库。它支持缓存公共 npm 包、托管私有包，并提供灵活的权限控制和存储管理。

核心功能

私有包托管

a. 允许团队在内部发布、存储和管理私有 npm 包，避免敏感代码泄露到公共 registry。

公共包缓存

a. 自动缓存从 npm 或其他源（如 Yarn）下载的公共包，加速后续安装并减少对外网依赖。

多源代理

a. 可配置多个上游 registry（如 npm、淘宝镜像等），根据需求自动切换。

权限控制

a. 通过插件支持用户认证（如账号密码、HTTPS）、细粒度的包访问权限（读/写/发布）。

轻量易扩展

a. 基于 Node.js 开发，支持插件化扩展（存储、认证、UI 等），配置文件简单（config.yaml）。

适用场景

● 企业开发：内部共享私有模块，统一管理依赖。

● 离线环境：缓存公共包，确保无外网时仍能正常开发。

● CI/CD 优化：加速构建流程，减少对外部 registry 的请求。

● 安全合规：避免直接依赖不可控的外部源。

快速入门

安装

通过 npm 或 yarn 全局安装：

csharp 复制代码

npm install -g verdaccio
# 或
yarn global add verdaccio

启动服务

运行命令后，默认监听 http://localhost:4873：

配置 npm 客户端

将 npm 或 yarn 的 registry 指向 Verdaccio：

arduino 复制代码

npm set registry http://localhost:4873

发布私有包

在项目目录下登录并发布：

bash 复制代码

npm login  # 输入 Verdaccio 的账号（默认允许匿名）
npm publish

配置文件

默认配置文件位于 ~/.config/verdaccio/config.yaml，常见配置项：

yaml 复制代码

storage: ./storage      # 包存储目录
auth:
  htpasswd:
    file: ./htpasswd     # 用户密码文件
uplinks:
  npmjs:
    url: https://registry.npmjs.org/  # 上游 registry

实操

登录到目标服务器xxx
全局安装 verdaccio

npm install -g verdaccio
启动verdaccio

arduino 复制代码

verdaccio --listen 0.0.0.0:4873

Verdaccio 会启动一个 Web 服务器，并在 http://0.0.0.0:4873/ 提供服务。开发人员可以通过配置文件来自定义其行为，例如修改仓库的存储路径、配置用户认证等等。

配置文件地址： ~./verdaccio、config.yaml

设置yarn或者 npm仓库地址

arduino 复制代码

npm set registry http://0.0.0.0:4873/
yarn config set registry http://0.0.0.0:4873/

这样，所有的 npm install 和 npm publish 操作都会使用本地的 Verdaccio 仓库。
删除原来node_modules
git pull
yarn：主要在执行安装的时候请不要关闭启动verdaccio的客户端
yarn build:prod

志哥我想说

第一中方案适合个人开发者或者小公司，无需共享组件库代码的时候，而第二种方式适合小团队

贴一下官网的介绍：

它是基于 Node.js 的网页应用程序
它是私有的 npm 注册中心
它是本地网络代理
它是可插拔的应用程序
它相当容易安装和使用
我们提供 Docker 和 Kubernetes 支持
它与 yarn, npm 和 pnpm 100% 兼容
Verdaccio 的意思是 一种在中世纪末意大利流行的壁画的绿色。

官网地址：verdaccio.org/zh-CN/