跳转到内容
[ PIER ]

发布私有包

Pier 接受标准的 npm publish 流程，适用于带 scope（@org/name）和不带 scope（name）的包。该协议是 CouchDB 风格的、带 _attachments 的 PUT —— 与每个 npm CLI 发送给 npmjs.org 的线缆格式完全相同。

发布一个带 scope 的包

Section titled “发布一个带 scope 的包”
Terminal window
# package.json
{
  "name": "@your-org/my-lib",
  "version": "1.0.0",
  "publishConfig": {
    "registry": "https://YOUR-PIER-HOST/registry/npm/"
  }
}
Terminal window
npm publish
# published @your-org/[email protected]

publishConfig 是固定单个包发布目标而不改动全局仓库的标准做法。如果你不设置它，npm 会使用你 .npmrc 中的 registry。

发布一个不带 scope 的包

Section titled “发布一个不带 scope 的包”

流程相同，只是没有 @scope/：

Terminal window
# package.json
{
  "name": "my-internal-lib",
  "version": "1.0.0"
}
Terminal window
npm publish --registry=https://YOUR-PIER-HOST/registry/npm/

如果你同时开启了上游代理，不带 scope 的私有包会与公共命名空间发生冲突。如果 my-internal-lib 已经存在于 npmjs.org，Pier 仍会接受你的发布，并且你的私有版本会遮蔽代理条目。为清晰起见，我们建议使用带 scope 的名称（@your-org/…）。

完整性校验

Section titled “完整性校验”

如果你的 CLI 在发布请求体中发送了 dist.integrity，Pier 会将其与上传 tarball 的 sha512 进行比对，并以 400 拒绝不匹配的情况。如果未发送，Pier 会从字节计算完整性并存储它。无论哪种方式，每个已存储的 tarball 都拥有经过校验的 sha512。

Dist-tag

Section titled “Dist-tag”
Terminal window
npm dist-tag add @your-org/[email protected] beta
npm dist-tag ls @your-org/my-lib
# latest: 1.2.0
# beta: 1.2.0
npm dist-tag rm @your-org/my-lib beta

latest 是唯一必需的 tag。你可以拥有任意数量的命名 tag，指向任意版本。

弃用某个版本

Section titled “弃用某个版本”
Terminal window
npm deprecate @your-org/[email protected] "use 1.2.x"

弃用消息会写入 npm_versions.manifest_json.deprecated，显示在包详情页上，并在安装时通过 npm warn 出现在客户端中。要取消弃用，传入一条空消息：

Terminal window
npm deprecate @your-org/[email protected] ""

撤销发布（Unpublish）

Section titled “撤销发布（Unpublish）”
Terminal window
# single version
npm unpublish @your-org/[email protected]


# whole package
npm unpublish @your-org/my-lib --force

Pier 会删除版本行（对整包 unpublish 则删除包行 + 所有版本），从磁盘移除 tarball，并写入一个墓碑标记，使得重新发布相同的 名称+版本 会被拒绝 —— 与 npm 政策一致。

Unpublish 是唯一可通过 CLI 触发的破坏性操作。请小心 —— 没有撤销。

发布的认证

Section titled “发布的认证”

npm publish 会发送 .npmrc 中的 bearer 令牌：

//YOUR-PIER-HOST/registry/npm/:_authToken=pier_npm_…

或者使用 npm login --auth-type=web 走 OAuth 风格的浏览器流程（强制 2FA）：

Terminal window
npm login --auth-type=web --registry=https://YOUR-PIER-HOST/registry/npm/
# Opens the browser → authenticate in Pier panel → token in .npmrc

常见错误

Section titled “常见错误”
  • E409 Conflict —— 你正在重新发布一个已存在的版本。在 package.json 中提升版本号。（完整列表见 故障排查。）
  • 401 Unauthorized —— 令牌缺失或已被撤销。在 Packages → Manage tokens 中签发一个新的。
  • 400 attachment name mismatch —— 你的 CLI 发送了一个非预期的 _attachments 键。大多数客户端发送 @scope/name-version.tgz（完整）或 name-version.tgz（简短）—— Pier 两者都接受。

后续步骤

Section titled “后续步骤”