本文使用「署名 4.0 国际 (CC BY 4.0)」许可协议,欢迎转载、或重新修改使用,但需要注明来源。 [署名 4.0 国际 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.zh)
本文作者: 苏洋
创建时间: 2024年12月01日
统计字数: 14005字
阅读时间: 28分钟阅读
本文链接: https://soulteary.com/2024/12/01/use-open-source-software-to-build-a-lightweight-npm-private-repository-verdaccio.html
-----
# 使用开源软件搭建轻量的 NPM 私有仓库:Verdaccio
本篇内容,我们来聊聊使用开源软件 Verdaccio 搭建轻量的 NPM 私有仓库。
## 写在前面
最近折腾项目,经常遇到需要进行前端构建的需求。
其实在几年前,也因为 CI/CD 的需求,写过一些和[软件仓库相关的实践](https://soulteary.com/tags/%e8%bd%af%e4%bb%b6%e4%bb%93%e5%ba%93.html),不过马上都 2025 年了,或许应有更新、更简单的方案。
## 为什么需要私有 NPM 仓库?
在实际开发中,我们经常会遇到以下场景:
1. 需要管理企业内部的私有包,避免核心代码泄露
2. 希望降低对公共 NPM 仓库的依赖,提升安装速度
3. 想要对第三方包进行定制化修改
4. 需要在内网环境下确保依赖包的可用性
Verdaccio 恰好能够完美解决这些问题。
### 关于轻量级 NPM 开源仓库:Verdaccio
[Verdaccio](https://github.com/verdaccio/verdaccio) 是一个轻量级的私有 NPM 包管理工具,项目创建以来接受了来自 docker、crowdin、netlify、jetbrains、algolia、SheetJs、GatsbyJs、pintura 等知名项目和组织的支持。
核心特点:
1. 零配置开箱即用,自带轻量级数据库,不需要额外的数据库支持
2. 支持代理和缓存公共仓库(npmjs.org),可以加快包的下载速度
3. 内置用户认证和私有包权限管理,适合企业和团队内部使用
4. 支持扩展存储方案,可以对接 S3、Google Cloud Storage 等
5. 适合用于前端项目的端到端测试
6. 资源占用少,易于部署和维护
主要使用场景:
1. 企业私有包管理:比如公司内部的通用组件库、工具库等,可以通过 Verdaccio 进行私密发布和管理,避免将源码发布到公网。
2. 加速包下载:通过缓存机制,只需从公共仓库下载一次包,后续可直接使用本地缓存,大大提升安装速度。
3. 离线开发环境:在内网环境下,可以使用 Verdaccio 搭建本地仓库,确保依赖包的可用性。
4. 测试和调试:很多开源项目如 create-react-app、babel.js 等都使用 Verdaccio 进行端到端测试。
软件的基本使用方法:
```bash
# 私有仓库服务端
# 安装
npm install -g verdaccio
# 启动服务
verdaccio
# 用户端使用
# 配置 registry
npm set registry http://localhost:4873/
# 创建用户
npm adduser --registry http://localhost:4873
# 发布包
npm publish --registry http://localhost:4873
```
Verdaccio 的特点是轻量、简单、易用,特别适合中小型团队使用。它不仅可以管理私有包,还能作为公共 NPM 仓库的缓存层,提升团队的开发效率。
## 实践部署:面向本地开发场景
因为 Verdaccio 足够轻量,所以除了能够服务私有网络中的开发之外,还可以实现本地开发前端项目时的依赖包安装加速。
### 1. 基础环境准备
首先,确保服务器已安装 Node.js 18 或更高版本:
```bash
# 确认版本
# node -v
v22.11.0
```
我使用的是 `v22.11.0` 版本的 Node.js,如果你已经安装了 NVM,可以通过下面的命令,快速下载安装这个版本的 Node.js:
```bash
# NVM_NODEJS_ORG_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/ nvm install v22.11.0
Downloading and installing node v22.11.0...
Downloading https://mirrors.tuna.tsinghua.edu.cn/nodejs-release//v22.11.0/node-v22.11.0-darwin-arm64.tar.xz...
################################################################################################################ 100.0%
Computing checksum with shasum -a 256
Checksums matched!
Now using node v22.11.0 (npm v10.9.0)
```
然后,将系统中的 Node 版本切换为刚刚下载后的版本:
```bash
# nvm use v22.11.0
Now using node v22.11.0 (npm v10.9.0)
# nvm alias default 22.11.0
default -> 22.11.0 (-> v22.11.0)
```
### 2. 安装软件
软件的安装很简单,我们可以借助国内的 NPM 加速镜像来完成工具的下载:
```bash
npm install --registry=https://registry.npmmirror.com -g verdaccio
```
### 3. 使用软件
想要使用软件,只需要执行 `verdaccio` 这个命令:
```bash
# verdaccio
(node:39844) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
info --- config file - /Users/soulteary/.config/verdaccio/config.yaml
info --- the "crypt" algorithm is deprecated consider switch to "bcrypt" in the configuration file. Read the documentation for additional details
info --- using htpasswd file: /Users/soulteary/.config/verdaccio/htpasswd
info --- plugin successfully loaded: verdaccio-htpasswd
info --- plugin successfully loaded: verdaccio-audit
warn --- http address - http://localhost:4873/ - verdaccio/6.0.2
```
当服务启动后,我们就可以通过访问 `http://localhost:4873/` 来使用它了。
![默认的 WebUI 界面](https://attachment.soulteary.com/2024/12/01/npm-webui.jpg)
### 4. 默认配置
默认情况下,程序会使用系统用户目录中的默认配置,如:
```bash
/Users/soulteary/.config/verdaccio/config.yaml
```
默认配置文件如下(我进行了一些翻译):
```yaml
#
# 这是默认配置文件。
#
# 查看更多配置文件示例:
# https://github.com/verdaccio/verdaccio/tree/6.x/conf
#
# 阅读最佳实践
# https://verdaccio.org/docs/best
# 存储所有包的目录路径
storage: ./storage
# 包含插件的目录路径
plugins: ./plugins
# https://verdaccio.org/docs/webui
web:
title: Verdaccio
# 注释此行以禁用 gravatar 支持
# gravatar: false
# 默认情况下包按升序排列 (asc|desc)
# sort_packages: asc
# 将您的 UI 转换为暗色模式
# darkMode: true
# html_cache: true
# 默认情况下显示所有功能
# login: true
# showInfo: true
# showSettings: true
# 结合 darkMode,您可以强制使用特定主题
# showThemeSwitch: true
# showFooter: true
# showSearch: true
# showRaw: true
# showDownloadTarball: true
# 在manifest 之后注入的 HTML 标签
# scriptsBodyAfter:
# - ''
# 在 结束前注入的 HTML 标签
# metaScripts:
# - ''
# - ''
# - ''
# 在