手把手教你离线部署 Verdaccio：让内网也能拥有自己的 npm 私仓

🐳 手把手教你离线部署 Verdaccio：让内网也能拥有自己的 npm 私仓

前言：当你的服务器“与世隔绝”

想象一下这个场景：你带着你的代码项目，来到一个没有互联网接入的内网环境，准备大干一场。项目依赖了几十个 npm 包，然而npm install就像石沉大海，没有任何回应。你手里只有一个 U 盘和一台能上网的笔记本，该怎么办？

别慌，今天这篇文章就是你的“救星”。我们将一步步搭建一个完全离线可用的 npm 私有仓库 —— Verdaccio，并且使用 Docker 这种优雅的方式，让整个过程像复制粘贴文件一样简单。

目标读者：对 Docker 和 npm 有基本概念，但苦于内网环境无法直接拉取镜像的小白同学。我会尽量用“说人话”的方式解释每一步的原理。

第一章：工欲善其事，必先利其器 —— 认识 Verdaccio 与 Docker

1.1 Verdaccio 是什么？

简单来说，Verdaccio 是一个轻量级的私有 npm 仓库。它可以在你的电脑或服务器上运行，充当一个“本地淘宝镜像”。当你执行npm install时，请求会先发到 Verdaccio，如果它本地有缓存的包，就直接返回给你；如果没有，它才会去外网帮你下载并缓存下来。

在没有外网的内网环境中，我们事先把需要用到的包“喂”给 Verdaccio，它就能让内网的所有机器正常安装依赖。

1.2 为什么要用 Docker？

手动安装 Verdaccio 需要 Node.js 环境，还得处理一大堆依赖关系，稍有不慎就会遇到类似Cannot find module 'clipanion'这样的错误。而Docker 就像一个“集装箱”，它把 Verdaccio 和它需要的所有运行环境（操作系统、Node、依赖库）全部打包在一起。你只需要把这个“集装箱”搬到任何一台支持 Docker 的机器上，它就能立刻运行，完全不用担心环境差异。

第二章：出师不利 —— 联网拉取镜像为何超时？

一切美好的计划，在第一步就遇到了拦路虎：

dockerpull verdaccio/verdaccio# 结果：Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

为什么会出现这个错误？

Docker 默认会去官方仓库registry-1.docker.io拉取镜像，但这个服务器位于国外。由于网络波动或者某些众所周知的网络限制，直接访问很容易超时。

解决方法：配置国内镜像加速器

我们需要告诉 Docker：“别去国外找了，先去国内的‘镜像站点’看看有没有一样的货。” 这些镜像站点（如阿里云、DaoCloud）会定时同步官方镜像，速度飞快。

具体操作如下（以 Linux 服务器为例）：

1. 创建或修改 Docker 配置文件：

   sudomkdir-p/etc/dockersudotee/etc/docker/daemon.json>/dev/null<<'EOF' { "registry-mirrors": [ "https://docker.m.daocloud.io", "https://huecker.io", "https://dockerhub.timeweb.cloud", "https://noohub.ru" ] } EOF

   （小贴士：这些是常用的公共加速器，你可以根据自己的网络情况替换成阿里云或其他源）

2. 重启 Docker 服务让配置生效：

   sudosystemctl daemon-reloadsudosystemctl restartdocker

3. 验证配置是否成功：

   dockerinfo|grep-A5"Registry Mirrors"

   如果看到你刚才填入的地址列表，就说明配置好了。

此时再次运行docker pull verdaccio/verdaccio，你就会看到进度条飞快滚动，镜像顺利下载到本地了。

第三章：打包“集装箱” —— 把镜像变成可以拷贝的文件

现在，在你的联网笔记本上，已经有了 Verdaccio 的 Docker 镜像。但镜像默认是存储在 Docker 的内部存储空间里的，不能直接拷贝。我们需要把它“压缩打包”成一个普通的.tar文件，就像把集装箱装到平板车上。

# 语法：docker save -o 输出文件名.tar 镜像名:标签dockersave-overdaccio.tar verdaccio/verdaccio

执行完毕后，你会得到一个verdaccio.tar文件（大小约 200MB+）。这个文件就是我们要带去内网的“万能钥匙”。

验证文件是否生成：

ls-lhverdaccio.tar

第四章：内网启航 —— 加载并运行离线镜像

把verdaccio.tar拷贝到你的内网服务器上（U 盘、内网共享、甚至刻光盘都行）。

4.1 加载镜像到 Docker

内网服务器不需要联网，只需要已经安装好 Docker 环境。执行以下命令将“集装箱”导入仓库：

dockerload-iverdaccio.tar

加载完成后，可以通过docker images查看，你应该能看到verdaccio/verdaccio出现在列表中。

4.2 启动 Verdaccio 容器

最关键的一步来了！运行以下命令：

dockerrun-itd--nameverdaccio-p4873:4873 verdaccio/verdaccio

参数详解（新手必看）：

• -itd：组合参数，让容器在后台运行（detach 模式）。
• --name verdaccio：给容器起个好记的名字，方便后续管理。
• -p 4873:4873：端口映射。冒号前面是宿主机的端口（内网服务器的门牌号），冒号后面是容器内部的端口（集装箱内部的门牌号）。意思是：如果有人来敲服务器 4873 这扇门，请把请求转交给容器里的 4873 门。

4.3 验证服务是否跑起来了

在服务器本机执行：

curlhttp://localhost:4873

如果返回了一堆 HTML 代码或者 JSON 数据，恭喜你，Verdaccio 已经成功在内网扎根了！

第五章：让局域网的小伙伴也能用 —— 打通网络访问

现在服务只在服务器本机（127.0.0.1）上能访问，内网的其他电脑怎么连呢？

5.1 获取服务器内网 IP

# Linuxipaddr show# Windowsipconfig

假设你的服务器 IP 是192.168.1.100。

5.2 设置 npm 源（客户端操作）

在内网任意一台开发电脑上，执行：

npmconfigsetregistry http://192.168.1.100:4873

之后npm install就会从这个内网源拉包了。

5.3 常见踩坑：Windows 防火墙与 WSL2

• 防火墙拦截：如果 Windows 服务器开启了防火墙，首次启动 Docker 映射端口时，系统会弹窗询问是否允许Docker Desktop Backend访问网络，务必点击“允许”。
• WSL2 网络问题：如果 Docker 跑在 WSL2 模式下，内网其他机器可能无法直接访问192.168.1.100:4873。此时可以在管理员 PowerShell中设置端口转发：

  netsh interface portproxy add v4tov4 listenport=4873 listenaddress=0.0.0.0 connectport=4873 connectaddress=127.0.0.1

第六章：发布你的离线包 —— 让 Verdaccio “有货可卖”

服务跑起来了，但仓库是空的。还记得开头提到的airgap-packages吗？那是你在有网环境打包好的项目依赖。现在需要把这些包“上架”到 Verdaccio。

使用我们之前提到的pnpm-airgap工具：

# 先登录（如果没设置匿名发布）npmlogin--registryhttp://localhost:4873# 发布包nodecli.cjs publish-p./airgap-packages-rhttp://localhost:4873

完成这一步后，内网所有机器就都能通过 Verdaccio 安装完整的项目依赖了。

第七章：总结与最佳实践

回顾一下我们的“三步走”战略：

1. 联网端准备：配置镜像加速 → 拉取镜像 → 保存为tar文件。
2. 离线端部署：加载tar镜像 → 运行容器 → 打通防火墙。
3. 内容填充：登录 → 发布离线依赖包 → 内网npm install起飞。

进阶建议：

• 数据持久化：上面的命令重启容器后，上传的包会丢失。建议在docker run时加上-v /宿主机目录:/verdaccio/storage来挂载数据卷。
• 匿名发布：内网测试环境可以配置 Verdaccio 允许匿名发布（修改config.yaml中的publish: $all），省去登录步骤。

写在最后

掌握了 Docker 离线部署的能力，你就拥有了在任何“断网孤岛”中搭建开发环境的超能力。无论是 Verdaccio 还是其他数据库、中间件，这套“联网拉取 → 打包保存 → 离线加载”的组合拳都能通吃。

希望这篇指南能帮你顺利攻克内网环境部署的难关。如果觉得有用，欢迎分享给更多被困在内网里的战友们！🚀