搭建私有npm仓库之sinopia

Posted on Views:

在 JavaScript 开发中，Sinopia 是一个非常经典的、基于 Node.js 的私有npm缓存和注册中心服务器。虽然它目前在社区中已经停止维护（大家大多转向了它的分支 Verdaccio），但它的核心理念和工作原理依然非常重要。

1. 核心功能与工作原理

Sinopia 的角色就像是一个智能中转站（反向代理）：

  • 私有包托管：你可以把公司内部开发的、不便公开的 npm 组件包发布到 Sinopia 上，只有内部团队可以下载。
  • 公共包缓存：当有人向 Sinopia 请求一个公共包（比如 lodash）时，如果 Sinopia 本地没有，它会去官方 npm registry 下载并缓存在本地。下一个人再安装时，直接从本地内网服务器获取，速度极快。
  • 离线可用：一旦公共包被缓存，即使外网断开，内网开发者依然可以正常安装这些包。

2. 为什么现在更推荐 Verdaccio？

Sinopia 大约在 2015 年左右就停止了主线更新。由于 npm 协议的升级和 Node.js 版本的演进，直接使用原版 Sinopia 可能会遇到兼容性问题。

社区在其基础上分叉（Fork）出了一个新项目——Verdaccio。

  • 100% 兼容：Verdaccio 完全继承了 Sinopia 的轻量、零配置特性。
  • 持续维护：支持最新的 npm、yarn 和 pnpm 协议，修复了诸多安全漏洞，并自带更现代化的 Web UI 界面。

建议：如果你现在要真正落地自建 npm 仓库，强烈建议直接安装 Verdaccio，两者的使用方法和配置逻辑几乎一模一样。

3. 快速搭建与使用流程（以 Verdaccio/Sinopia 为例）

搭建过程极其简单，不需要配置繁重的数据库，它默认直接使用本地文件系统存储。

第一步：安装与启动

1
2
3
4
5
# 全局安装（这里以更稳定的 Verdaccio 为例，若坚持用原版可换成 sinopia）
npm install -g verdaccio

# 启动服务
verdaccio

启动后，终端会提示你服务运行在 http://localhost:4873。

第二步：配置 npm 源

开发者需要将本地的 npm 指向你的私有仓库地址：

1
2
# 修改 npm 全局镜像源
npm config set registry http://localhost:4873

第三步：创建用户与发布包

1
2
3
4
5
# 在私有仓库中注册一个账号（按提示输入用户名、密码和邮箱）
npm adduser

# 在你的 npm 项目根目录下，直接发布
npm publish

发布成功后，打开 http://localhost:4873 的网页端，就能看到你们团队自己托管的私有包了！

4. 核心配置文件（config.yaml）

Sinopia/Verdaccio 的精髓在于它的配置文件，你可以在里面轻松实现：

  • 权限控制：限制谁可以查看、下载（access）或发布（publish）特定的包。
  • 上游代理（Uplinks）：默认上游是 npm 官方源，在中国国内通常会将其修改为淘宝镜像源（https://registry.npmmirror.com/），从而让公共包的缓存下载速度翻倍。