一个二进制中的私有 + 代理模式
在同一个 /registry/npm/ 端点发布 scoped 或 unscoped 私有包,并透明镜像 registry.npmjs.org(或任何兼容 upstream)。私有发布始终优先于代理条目 — .npmrc 中无需 scope routing。
自托管 npm 仓库 — Pier
私有包 + 透明 npmjs.org 镜像,集成在一个 Rust 二进制中。兼容 npm 7–11、yarn classic、yarn berry 2/3/4、pnpm 和 bun — 无需 Verdaccio 容器。
兼容所有现代客户端
npm 7–11、yarn classic 1.22、yarn berry 2/3/4、pnpm 9/10 和 bun。所有认证、dist-tag、publish、install、deprecate 和 unpublish 流程都针对每个客户端进行了端到端测试。
懒加载 tarball 缓存 + LRU 淘汰
Upstream packument 被缓存并通过 If-None-Match 重新验证(304 短路)。tarball 在首次 install 时懒加载,后台 LRU GC 将磁盘缓存控制在可配置的上限内,避免磁盘悄然撑爆。
流式发布与下载
tarball 通过 axum::Body::from_stream 流式传输 — Pier 不会把 200 MiB 的 tarball 缓存到内存。热路径使用 tokio_util::ReaderStream,内存占用与包大小无关。
Web 登录流程(--auth-type=web)
npm login --auth-type=web 打开浏览器,用户在面板中使用 2FA 认证,长效 pier_npm_ token 自动写入 .npmrc — 无需手动复制粘贴。
从 UI 进行 pin、审计和查看
Mirror 标签页列出每个缓存的公共包,带版本数和磁盘占用。为团队关心的包加星标,过滤掉其余。每行链接到详情页,显示 dist-tags、版本和「下载最新」按钮。
把 npm 连接到你的 Pier 仓库
- 01
在面板中生成 token
打开 Packages → Manage tokens → New token。Pier 返回一个仅显示一次的 pier_npm_… 字符串 — 关闭弹窗前请先复制。
- 02
在项目中放置 .npmrc
registry=https://your-pier-host/registry/npm/,然后 //your-pier-host/registry/npm/:_authToken=pier_npm_…,加上 always-auth=true 以便 yarn 1 在 GET 时发送 bearer。
- 03
可选:启用 upstream 代理
Packages → Upstream proxy → 启用开关,默认 upstream 是 registry.npmjs.org。设置最大缓存大小(0 = 无限制)和 packument 重新验证的 TTL。
- 04
发布或安装
npm publish 发布私有包,或 npm install <任意公共包> 填充代理缓存。整个团队使用同一个 URL — 无需 scope routing。
常见问题
Pier 能取代 Verdaccio 吗?
在私有发布 + 代理镜像方面,可以 — Pier 支持相同的 npm 注册表 HTTP 协议,加上 dist-tag/deprecate/unpublish 命令和 web 登录流程。尚未对等的:npm search、npm owner/RBAC 和 audit 端点,这些在路线图中。其余所有功能在自动化客户端矩阵(npm/yarn1/yarn2/yarn3/yarn4/pnpm/bun)中均通过测试。
Pier 支持哪些 npm 客户端?
npm 7 到 11、yarn classic 1.22、yarn berry 2/3/4(在 .yarnrc.yml 中需要 npmAlwaysAuth: true)、pnpm 9 和 10、bun latest。每个客户端都在 CI 中针对真实 Pier 实例运行 pier-tests,确保升级时行为不变。
upstream 代理模式与 CDN 缓存有什么不同?
Pier 在元数据层(packument)永久缓存并基于 TTL 重新验证;在 tarball 层懒加载 — 只有客户端实际安装过的版本才落到磁盘。CDN 不透明地缓存 HTTP 响应;Pier 理解 npm 协议,因此可以提供 abbreviated packument、在 If-None-Match 时返回 304,并重写 dist.tarball URL 让所有安装都走你的主机。
Pier 支持 yarn 4(yarn berry)吗?
支持 — yarn 2/3/4 使用 .yarnrc.yml 而非 .npmrc,并需要 npmAlwaysAuth: true 在 GET 时发送 bearer。配置好这一行,完整的 install/publish 流程就能跑通 Pier;yarn berry 的文档页有完整 yarnrc 示例。
我能同时发布私有包和代理公共包吗?
可以 — 私有和代理条目都在同一个 /registry/npm/ 端点。同名情况下私有发布始终覆盖代理条目,所以你可以保留内部 @your-org/* scope,同时通过同一个 URL 安装 left-pad 或 next。
缓存需要多少磁盘?
packument 很小(每个包约 1–50 KB JSON)。tarball 占大头:一次 npm install next 大约会拉取 100 MiB(含所有传递依赖)。个人开发机 500 MiB 够用;小团队 2–5 GiB;共享 CI 镜像 20+ GiB。设最大缓存大小为 0 表示无限制。
npm publish 支持 2FA 吗?
token 在面板中生成,而面板会话强制 2FA — 所以 npm login --auth-type=web 流程天然继承 2FA。旧版 npm login(CouchDB 流程)今天不会提示 OTP;如果你要求每次 token 生成都走 2FA,建议在面板设置中禁用 CouchDB 流程。
有 CI 集成吗?
在 Packages → Manage tokens 中生成长效 token,在 CI 步骤中写同样的 .npmrc。文档的 CI 页面提供了 GitHub Actions 和 GitLab CI 的现成片段,适用于任何受支持的客户端。