HTTP 端点

pnpr 会暴露一组始终启用的端点（健康、用户账户和令牌）以及两个接口：

🌐 pnpr exposes a set of always-on endpoints (health, user accounts, and tokens) plus two surfaces:

• Registry surface - npm-compatible package and publish endpoints. Served exactly when at least one registry is declared under registries:; --disable-registry turns it off for one process.

• Resolver surface (resolver.enabled) - pnpr install-accelerator endpoints under /-/pnpr.

请参阅 配置 了解配置键，参阅 命令行参考 了解命令行覆盖项。

🌐 See Configuration for the config keys and CLI reference for the command-line overrides.

随时可用

🌐 Always available

方法	路径	描述
GET	/-/ping	健康检查。返回 {}。

下面的 用户和令牌端点 也始终可用，无论启用了哪些界面。

🌐 The user and token endpoints below are also always available, whichever surfaces are enabled.

注册表基址：/ 和 /~<name>/

🌐 Registry bases: / and /~<name>/

每个注册表 都作为完整的 npm 注册表在 /~<name>/ 提供服务 —— 打包文档和 tar 包读取、版本清单、发布标签、搜索、发布、撤销发布，以及登录/检查身份接口都可以在注册表前缀下使用。~ 前缀可以将注册表名称与包名命名空间隔开（包名永远不能以 ~ 开头）。

无路径基础（/）别名为由 defaultRegistry 命名的注册表；在未配置 defaultRegistry 的情况下，裸主机不提供任何注册表，只有 /~<name>/ 基础响应。

每个请求都通过注册表图路由：

🌐 Every request routes through the registry graph:

• A request to a router is answered by the first listed source whose declared packages: claim the name. A name that no source claims is a definitive 404 — there is no fall-through to another origin. A matched source that is unavailable is an error, never a 404.

• A registry's declared namespace is enforced on every path to it: a read of a name outside the namespace is a definitive 404 answered before storage or the upstream is consulted — through a router, on the path-less base, and at the registry's own /~<name>/ URL alike — and an off-namespace publish is rejected.

• Writes (publish, dist-tags, unpublish) must resolve to a hosted registry; a write that routes to an upstream is rejected.

• The serving registry's matching packages: rule is enforced on every read and write.

• Served dist.tarball URLs are rewritten onto the configured public_url and stay canonical for the base the client addressed (path-less or /~<name>/), so lockfiles don't bake in a registry name.

下面的端点表格显示无路径的形状；每个形状在 /~<name>/ 前缀下都同样可用。

解析器端点

🌐 Resolver endpoints

resolver.enabled 为 true 时，解析器端点会被挂载。POST 端点需要一个有效的 pnpr Authorization 头。

🌐 The resolver endpoints are mounted when resolver.enabled is true. The POST endpoints require a valid pnpr Authorization header.

方法	路径	描述
GET	/-/pnpr	功能握手。返回支持的协议版本，目前为 {"pnpr":{"versions":[0]}}。返回 404 表示服务器没有兼容的解析器接口。
POST	/-/pnpr/v0/resolve	根据客户端提供的注册表和策略解析单个项目或工作区。返回 application/x-ndjson 帧。
POST	/-/pnpr/v0/verify-lockfile	在客户端的注册表和策略设置下验证现有的锁文件，而无需重新解析。返回 application/x-ndjson 帧。

POST /-/pnpr/v0/resolve 接受如下字段：projects、dependencies、devDependencies、optionalDependencies、registry、namedRegistries、overrides、lockfile、frozenLockfile、preferFrozenLockfile、ignoreManifestCheck、trustLockfile、minimumReleaseAge、minimumReleaseAgeExclude、minimumReleaseAgeIgnoreMissingTime、trustPolicy、trustPolicyExclude 和 trustPolicyIgnoreAfter。

请求 pnpr 从中获取的每个注册表——registry 和 namedRegistries 源，以及依赖规范、覆盖项或输入锁定文件 tar 包中的任何直接 http(s)/git URL——必须在服务器的获取白名单上（配置的注册表、声明的公共路由、内置 npm 注册表以及 pnpr 自有的源）。不在白名单上的源会被直接拒绝，在任何服务器端获取之前。上游凭据从不取自客户端：pnpr 会为每个路由选择自身服务器拥有的凭据（参见安装加速），并且带有内联 user:pass@ 凭据的 URL 会被拒绝。

🌐 Every registry the request would make pnpr fetch from — the registry and namedRegistries origins, plus any direct http(s)/git URL in a dependency spec, an override, or an input-lockfile tarball — must be on the server's fetch allowlist (the configured registries, declared public routes, the built-in npm registry, and pnpr's own origin). An off-allowlist origin is rejected up front, before any server-side fetch. Upstream credentials are never taken from the client: pnpr selects its own server-owned credential per route (see Install acceleration), and a URL carrying inline user:pass@ credentials is rejected.

resolve 响应是一个 NDJSON 流：

🌐 The resolve response is an NDJSON stream:

框架	描述
package	一个已解析的 tar 包：id、name、version、integrity、tarball，以及可选的 unpackedSize / fileCount。
done	终端成功框架。对于 resolve，携带 lockfile 和 stats.totalPackages；对于 verify-lockfile，仅表示成功。
violations	终端策略失败框架。携带渲染的锁文件或 OSV 违规信息。
error	终端服务器端解析或验证错误。

注册表读取端点

🌐 Registry read endpoints

当提供注册表界面时，这些端点会被挂载。包读取会根据提供注册表的匹配packages:规则进行检查。

🌐 These endpoints are mounted when the registry surface is served. Package reads are checked against the serving registry's matching packages: rule.

方法	路径	描述
GET	/{name}	无作用域的包的包文档。
GET	/@scope/{name}	有作用域的包的包文档。
GET	/{name}/{version-or-tag}	按确切版本或发行标签的无作用域版本清单。
GET	/@scope/{name}/{version-or-tag}	按确切版本或发行标签的有作用域版本清单。
GET	/{name}/-/{filename}	无作用域 tar 包。
GET	/@scope/{name}/-/{filename}	有作用域 tar 包。
GET	/-/package/{package}/dist-tags	包 dist-tags 对象。使用百分比编码的作用域包名称，例如 @scope%2Fname。
GET	/-/v1/search?text=<query>&size=<n>	npm 搜索 v1 形式。通过包名子字符串搜索本地托管的包；搜索仅限本地，永远不会代理到上游。结果会根据访问策略进行过滤。

如果客户端发送 Accept: application/vnd.npm.install-v1+json，pnpr 会返回 npm 的简化版 install-v1 包文档格式。

🌐 If the client sends Accept: application/vnd.npm.install-v1+json, pnpr returns npm's abbreviated install-v1 packument shape.

当启用 OSV 检查时，易受攻击的版本将从包文档和 dist-tags 中移除。易受攻击版本的版本清单和压缩包将被拒绝。

🌐 When OSV checks are enabled, vulnerable versions are removed from packuments and dist-tags. Version manifests and tarballs for vulnerable versions are denied.

注册表写入端点

🌐 Registry write endpoints

当注册表界面被提供时，这些端点会被挂载。PUT 和 DELETE 请求需要凭证。只读的承载令牌不能使用写入方法，并且受 CIDR 限制的承载令牌会针对对等套接字地址进行检查。每个写入操作都通过注册表图路由，并且必须落在托管注册表上。

🌐 These endpoints are mounted when the registry surface is served. PUT and DELETE requests require credentials. A read-only bearer token cannot use write methods, and CIDR-restricted bearer tokens are checked against the peer socket address. Every write routes through the registry graph and must land on a hosted registry.

方法	路径	描述
PUT	/{name}	发布一个无范围的包。正文是包含 _attachments 的 npm 发布文档。需要 publish。
PUT	/@scope/{name}	发布一个作用域包。正文是带有 _attachments 的 npm 发布文档。需要 publish。
PUT	/-/pnpm/v1/publish	pnpm 批量发布。内容是 {"packages":[<publish document>, ...]}。批量操作是全有或全无的，每个包都需要 publish。
PUT	/{package}/-rev/{rev}	替换一个打包文档，用于部分取消发布。需要同时使用 publish 和 unpublish。使用百分号编码的作用域包名称，例如 @scope%2Fname。
DELETE	/{package}/-rev/{rev}	删除整个包，由强制取消发布使用。需要 unpublish。对于作用域包，使用百分号编码的作用域包名称。
DELETE	/{name}/-/{filename}/-rev/{rev}	移除未限定范围的 tar 包。需要 unpublish。
DELETE	/@scope/{name}/-/{filename}/-rev/{rev}	移除一个作用域的 tar 包。需要 unpublish。
PUT	/-/package/{package}/dist-tags/{tag}	添加或更新 dist-tag。正文是 JSON 字符串版本，例如 "1.0.0"。需要 publish。
DELETE	/-/package/{package}/dist-tags/{tag}	移除一个 dist-tag。需要 publish。

用户和令牌端点

🌐 User and token endpoints

这些端点总是挂载的，无论启用了哪些表面，并且它们是全局的——在无路径的基础路径和任何 /~<name>/ 前缀下提供的方式相同。因此，pnpm login 可以用于任何 pnpr URL，包括仅公开解析器而不公开注册表表面的服务器。

方法	路径	描述
PUT	/-/user/org.couchdb.user:{name}	npm adduser/login 端点。仅当 auth.htpasswd.max_users 允许注册时创建用户；现有用户可以使用正确的密码登录。返回一个承载令牌。
GET	/-/whoami	为经过身份验证的调用者返回 {"username": ...}。
GET	/-/npm/v1/user	npm 配置文件端点。返回经过身份验证的用户名和占位符配置文件字段。
GET	/-/npm/v1/tokens	列出经过身份验证的调用者的承载令牌，格式为 npm 兼容形态。
DELETE	/-/npm/v1/tokens/token/{key}	通过列表端的令牌键吊销调用者的一个令牌。
DELETE	/-/user/token/{token}	npm 注销端点。当路径中的原始承载令牌属于经过身份验证的调用者时，吊销该令牌。