Sinopia 私有仓库调研
本文最后更新于：2026年3月29日 晚上
Sinopia 私有仓库调研
tips：这篇记录的是围绕 Sinopia 的调研与部署思路。Sinopia 后来已经停止维护，如今如果重新做私有 npm 仓库，建议直接评估 Verdaccio。
为什么要用 Sinopia
前端团队一旦开始沉淀公共组件、工具库或者业务 SDK，很快就会遇到一个问题：这些包不适合直接发布到公共 npm，但又希望像普通 npm 包一样被安装、升级和版本管理。
如果没有私有仓库，常见做法通常只有几种：
- 直接把代码复制到各个项目里，版本很快就会失控。
- 用 git 地址引用依赖，可以用，但使用体验不如 npm 仓库完整。
- 手工打包再分发，流程重，维护成本也高。
Sinopia 解决的，就是“把公司内部包当成 npm 包一样管理”这个问题。它既能托管私有包，也能代理公共 npm 源，把团队常用依赖缓存到内网里。
Sinopia 是什么
Sinopia 本质上是一个私有的、带缓存能力的 npm 仓库服务。它的核心思路不是替代 npm，而是在团队内部加一层自己的 registry。它“够轻、够快、够容易”。
它比较适合三类场景：
- 发布公司内部私有包
- 缓存 npmjs.org 上的公共包
- 临时覆盖某个公共包的内部修订版本
吸引人的地方也很直接：
- 部署轻，不需要额外数据库，默认走文件系统存储。
- 一台能跑 Node 的内网机器就可以启动。
- 缺的包会回源 npmjs.org，请求过一次之后就会被缓存下来。
- 团队内部发布、安装、升级的流程和 npm 原生体验接近。
部署过程
1. 准备一台内网可访问的 Node 服务器
至少要满足两件事：
- 团队成员的电脑和 CI 都能访问到这台机器。
- 服务器上安装有 Node 和 npm 环境。
2. 安装并首次启动
先全局安装，然后直接跑一次，让它把默认配置文件生成出来：
1 | |
Sinopia 第一次启动时会自动生成 config.yaml。启动成功后，默认会监听 4873 端口，可以通过 http://[ip]:4873/ 打开页面。
3. 修改配置，让它能被内网访问
如果只是本机调试，默认配置够用；如果要给别人访问，至少要把监听地址改出来：
1 | |
除此之外，还要重点看这几类配置：
storage：包文件和缓存落盘的位置。auth：用户认证方式，常见的是htpasswd。uplinks：上游 npm 源地址。packages：哪些包允许访问、发布、是否需要走上游代理。
下面这段更适合作为“配置思路示例”，重点是看清楚几个角色：本地存储、认证、上游源、包权限。
1 | |
如果你的目的只是“公司内部私有包 + 公共 npm 缓存”，那上面这类思路就够了：私有 scope 允许内部用户发布，其他公共包走 npmjs 上游代理。
4. 把进程跑成常驻服务
手动执行 sinopia 只能临时起服务，真正部署时还得考虑进程守护和服务器重启后的自启动。
官方文档给的是 forever 思路，实际使用时也可以换成你团队更熟悉的 pm2 或 systemd。核心目标只有两个：
- 进程异常退出后能自动拉起。
- 机器重启后服务能自动恢复。
如果你准备把它长期跑在服务器上，最好再单独建一个运行用户，不要直接让业务机器所有人都用同一个高权限账号去启动服务。
团队内部怎么使用 Sinopia
1. 使用方式：全量接管
所有 npm 安装都走 Sinopia。
1 | |
2. 开发私有包，开发机先登录内部仓库
无论是发布还是安装私有包，第一步都是先登录内部 registry：
1 | |
登录成功后，认证信息会写进本机的 .npmrc。
3. 发布内部包
如果你准备给团队发布内部包，最好从一开始就用 scope 命名，比如：
1 | |
然后执行发布：
1 | |
这样别人一看到包名，就知道它是公司内部包，不容易和公共 npm 包混淆。
4. 安装内部包
团队其他成员只要本机 .npmrc 已经配好 scope 或默认 registry，就可以像装普通 npm 包一样安装：
1 | |
5. nrm 可以临时切源
像 nrm 这种工具可以帮个人快速切换 npm 源：
1 | |