在 Pier 中使用 npm

Pier 的仓库完整遵循 npm 仓库 HTTP 规范，因此从 7 到 11 的每个 npm 版本都能直接配合它使用，无需任何专门的标志。

配置

在项目根目录创建 .npmrc（或在 ~/.npmrc 中设置全局默认值）：

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

always-auth=true 在 npm 7+ 上无害，而 yarn 1 则必须使用它——保留它可以让同一份 .npmrc 同时适用于这两种客户端。

安装

# 公共包——如果开启了上游代理，则从 npmjs.org 代理获取
npm install left-pad

# 私有包
npm install @your-org/internal-lib

# 指定 dist-tag
npm install @your-org/internal-lib@beta

发布

# 版本号由 package.json 携带
npm publish

# 或在不改动 .npmrc 的情况下指定目标仓库
npm publish --registry=https://YOUR-PIER-HOST/registry/npm/

登录（浏览器流程）

npm login --auth-type=web --registry=https://YOUR-PIER-HOST/registry/npm/
# → 打开浏览器，在 Pier 面板中完成身份验证（含 2FA）
# → pier_npm_… 令牌会自动写入 .npmrc

传统的 npm login（不带 --auth-type=web）使用 CouchDB 用户创建流程——同样受支持。Web 流程会继承面板的 2FA；而 CouchDB 流程不会提示输入 OTP。如果你要求每次签发令牌都进行 2FA，请在面板设置中禁用 CouchDB 登录。

Dist-tags

npm dist-tag add @your-org/[email protected] beta
npm dist-tag ls @your-org/lib
npm dist-tag rm @your-org/lib beta

弃用

npm deprecate @your-org/[email protected] "use 1.2.x"
npm deprecate @your-org/[email protected] ""   # 取消弃用

取消发布

npm unpublish @your-org/[email protected]
npm unpublish @your-org/lib --force    # 整个包

版本矩阵

npm 版本	状态	说明
7	✓	开箱即用
8	✓	开箱即用
9	✓	开箱即用
10	✓	开箱即用
11	✓	always-auth 配置警告无害

常见错误

• 安装时出现 401 Unauthorized——令牌缺失，或 .npmrc 中没有 always-auth=true。参见故障排查。
• 发布时出现 409 Conflict——版本已存在。请在 package.json 中提升版本号。
• npm 11 上出现 npm warn Unknown project config "always-auth"——该标志虽已弃用，但仍被识别。可以忽略此警告。

相关链接

• 安装设置 —— 初始配置详解。
• 发布 —— 完整的发布流程。
• CI 集成 —— 在 GitHub Actions 和 GitLab CI 中使用 npm。