配置 npm 与 pnpm 代理缓存

为 npm、pnpm、Yarn 和 Bun 配置 Depsilo 代理缓存：使用项目级 registry，保留 lockfile，并区分元数据请求与包文件缓存命中。

之前https://registry.npmjs.org

之后http://localhost:23333/npm/

npm、pnpm、Yarn 和 Bun 都使用 Depsilo 的 /npm/ 路由。Depsilo 转发上游的包文档与 tarball，客户端仍会校验 lockfile 中的 integrity。

配置客户端

在项目根目录的 .npmrc 中合并以下设置，npm 与 pnpm 都可以使用。先记录原来的 registry，保留文件中的其他设置：

registry=http://localhost:23333/npm/

也可以在项目根目录运行 npm 命令，明确指定写入项目配置：

npm config set registry http://localhost:23333/npm/ --location=project
npm config get registry

npm config set 不带 --location=project 时默认修改用户配置。只有需要影响当前用户的所有项目时，才改用 --location=user，并先备份该文件。配置范围见 npm 官方文档。

Yarn 2+ 使用 npmRegistryServer。本地 HTTP 实例还需要把主机名加入 unsafeHttpWhitelist：

npmRegistryServer: "http://localhost:23333/npm/"
unsafeHttpWhitelist:
  - localhost

使用 HTTPS 时无需为 Depsilo 添加 HTTP 白名单，保留其他源已有的配置。远程部署时，将 URL 中的 localhost 换成客户端可达的实例地址，并在白名单中填写对应主机名，不要包含协议、端口或路径。项目已有 .yarnrc.yml 时，只合并这两项配置并保留其他字段；若已有 unsafeHttpWhitelist，向现有列表添加主机名，不要覆盖整个文件。Portal 生成的本地 HTTP 白名单如果包含 :23333，请按上述规则去掉端口。

Bun 使用 bunfig.toml 中的 [install].registry：

[install]
registry = "http://localhost:23333/npm/"

验证请求

查询包的版本元数据
终端窗口
```
npm view is-number version
```
在配置完成的项目目录执行。这条命令不写入 node_modules，也不会下载包的 tarball。
在 Admin 中确认流量

打开 Admin 的 Access logs（/admin/logs），按本次请求时间核对 npm 生态、包名与响应状态。元数据日志只能确认元数据请求经过 Depsilo；客户端也可能复用本地缓存，没有新的日志时不能声称本次请求经过了服务端。
单独验证包文件缓存

按验证缓存取得实例返回的 tarball 地址，再用 curl 独立下载同一制品两次，核对对应的两条制品日志。缓存已经预热时，第一次也可能命中；重复 npm install 或 npm view 不能单独证明服务端复用了包文件。

常见问题

只配置某个 scope 可以吗？

可以。把 .npmrc 中的 registry 换成 @scope:registry 只会重定向该 scope；其余依赖仍使用默认 registry。需要统一入口时，设置项目的默认 registry，并检查已有的 scope 专用 registry 是否仍指向其他地址。

CI 里应该怎么写？

在 CI 中设置 npm_config_registry 环境变量即可，无需改写 lockfile：

export npm_config_registry=http://depsilo.internal:23333/npm/
npm ci

容器中的 localhost 指向容器自身，必须换成 Runner 实际可达的地址。

如何回滚？

在本次修改的配置范围内恢复原 registry；原来没有该项时，只移除新增的 registry 项，保留其他配置。项目配置可用 npm config delete registry --location=project 移除。不要保留一个并行的公网 registry 作为“回滚”。