启用仓库

每个 Pier 安装默认都启用了仓库。你只需要：

1. 在面板中签发一个个人令牌。
2. 在项目里放一个 .npmrc（yarn berry 则用 .yarnrc.yml）。
3. 如果你也想缓存公共包，可选地开启上游代理。

1. 签发令牌

1. 打开 Pier 面板，进入 Packages → Manage tokens。
2. 点击 New token，给它起个名字，例如 laptop-2026。
3. Pier 会只显示一次明文令牌 —— 立即复制它。格式为 pier_npm_…。

该令牌绑定到你的面板账户。你可以随时在同一界面撤销它 —— 每个正在使用该令牌的现有客户端会立即开始收到 401。

2. 配置你的客户端

最小化的 .npmrc（适用于 npm、pnpm、bun，以及多加一行后的 yarn classic）：

registry=https://YOUR-PIER-HOST/registry/npm/
//YOUR-PIER-HOST/registry/npm/:_authToken=pier_npm_…
always-auth=true

yarn 1.x 需要 always-auth=true（否则它在 GET 请求中会省略 bearer），而对 npm/pnpm/bun 来说它无害。

对于 yarn berry（2/3/4），配置文件不同 —— 参见 在 Pier 中使用 yarn 2/3/4。

3. 验证是否生效

curl https://YOUR-PIER-HOST/registry/npm/-/ping
# {}

成功返回 {} 即确认仓库可达。接着：

npm whoami
# tester

如果收到 401，请重新检查令牌和 always-auth=true。如果收到 503，说明 Traefik 还没启动 —— 在刚执行完 bash install.sh 后给它 30 秒。

4.（可选）启用上游代理

如果你想通过 Pier 镜像 npmjs.org，让团队使用单一 URL：

1. 打开 Packages → Upstream proxy。
2. 打开 Enable upstream proxy 开关。
3. Upstream URL 默认为 https://registry.npmjs.org —— 除非你要镜像内部的 NPM Enterprise 实例，否则保持不变。
4. Packument TTL (seconds) —— 600（10 分钟）是合理的默认值；如果你希望减少与上游的往返，可以调到 3600。
5. Max cache size (MiB) —— 0 表示无限制（在磁盘充裕的主机上推荐）。小团队设 2–5 GiB；CI 镜像设 20+ GiB。
6. 点击 Save。

整个 Mirror 标签页现在会列出团队通过 Pier 安装过的每一个公共包。给你关心的包加星标，并用 Pinned only 进行筛选。

5. 选择你的客户端指南

• 使用 npm —— npm 7 到 11。
• 使用 yarn 1.x —— always-auth 的怪癖。
• 使用 yarn 2 / 3 / 4 —— .yarnrc.yml 配置。
• 使用 pnpm —— workspaces 小贴士。
• 使用 bun —— 关于精简版 packument 的说明。

下一步：发布或安装

• 想发布一个私有包？前往 发布私有包。
• 想让 CI 通过 Pier 安装？参见 CI 集成。
• 遇到障碍了？故障排查 涵盖了常见的 401/409/304 情况。