云上免费 npm 私有源怎么起步：从发包到公开分发

要发 @company/sdk，又不想先买机跑 Verdaccio——可以先走云服务：控制台建 npm 仓，开发机只配一个 registry，CI 用 Deploy Token（常见前缀 repod_）发布。合作方不愿收令牌时，再把交付 HOSTED 标公开，让对方在 /explore 复制免认证安装命令。

结论： 云服务可托管私有 npm；安装走 GROUP、发布走 HOSTED；PROXY 缓存 npmjs；公开分发用独立 public-* HOSTED + 主机路径 /explore。不要把含私有成员的 GROUP 勾公开。权限 = 仓库 ACL + 令牌，没有开箱 tenant_id。

需要自己装社区版、从零跑 install.sh 时，见文末参考：npm 私服怎么搭。国内直连 npmjs 不稳时的诊断与 PROXY 缓存验收，见文末参考：国内访问 npmjs 不稳怎么办——本文只写云起步与公开发现，不展开排障长文。

1. 云服务还是社区自建

路径	适用	说明
云服务	不想自管机与证书	托管 HTTPS；示例主机 https://repo.anguskit.com。具体租户接入主机以控制台「接入配置」为准
社区版私有化	数据必须进内网	GPL-3.0；机器、证书与网络自担

用量与限额以控制台当前租户显示为准；触顶后 publish / 上传会被拒绝。

2. 最小拓扑（云上同样三仓）

仓库名示例	类型	干什么
npm-hosted	HOSTED	npm publish 唯一目标；建议禁止覆盖正式版
npmjs-proxy	PROXY	远程 https://registry.npmjs.org，只读缓存
npm-all	GROUP	开发机 / CI 的统一 registry；成员顺序 hosted → proxy

口诀：拉 GROUP，推 HOSTED，PROXY 只读。

GROUP 的 packument 按成员取并集；同名冲突时 HOSTED 优先，有助于降低依赖混淆。开发者日常只记一个安装 URL。

CI (repod_) ──publish──► npm-hosted (HOSTED)
开发机 ──registry──► npm-all (GROUP) ──► hosted + npmjs-proxy
合作方 ──匿名──► /explore ──► public-npm (公开 HOSTED，另建)

3. 可操作步骤

3.1 控制台建仓与令牌

1. 登录云控制台，创建上表三个 npm 仓（名称可自定，后面配置保持一致）。
2. 为 CI 建 Deploy Token（常见前缀 repod_），对 npm-hosted 开 Write；开发者对 npm-all 开 Read。个人调试也可用门户签发的用户访问令牌（PAT）。
3. 令牌只显示一次：放进 CI Secret / 本地环境变量，不要写进 Git。

字段与路径以控制台「接入配置」为准；格式细节见文末参考：npm 格式手册。完整私有化安装不在本文，见文末参考：npm 私服怎么搭。

3.2 项目 .npmrc（HTTPS）

迁移期推荐：只切公司 scope（公共包仍走原源）：

@mycompany:registry=https://repo.anguskit.com/npm/npm-all/
//repo.anguskit.com/npm/npm-all/:_authToken=${NPM_TOKEN}
//repo.anguskit.com/npm/npm-hosted/:_authToken=${NPM_TOKEN}

整仓默认走私服：

registry=https://repo.anguskit.com/npm/npm-all/
//repo.anguskit.com/npm/npm-all/:_authToken=${NPM_TOKEN}
//repo.anguskit.com/npm/npm-hosted/:_authToken=${NPM_TOKEN}

三个高频坑：

1. registry 末尾要有 /，漏掉是最常见的低级错误。
2. _authToken 行不要带 https://，主机路径须与 registry 一致（含路径与末尾斜杠）。
3. 旧 package-lock.json 会锁公网 registry——迁源后删 lock 重装，或批量改 resolved，否则仍会打到 npmjs。

npm CLI 自 7.10 起已移除 always-auth，写了也不生效——靠 URL 作用域的 _authToken 覆盖元数据与 tarball。pnpm ≥11.5.3 对项目级 ${...} 凭据行另有限制，见文末参考：pnpm / yarn 私有源。

3.3 发布与安装闭环（验收）

export NPM_TOKEN="你的令牌"   # CI 用 Secret 注入

# 先确认令牌对 HOSTED 生效
npm whoami --registry https://repo.anguskit.com/npm/npm-hosted/

# 发布到 HOSTED（scoped 包默认私有发布）
npm publish --registry https://repo.anguskit.com/npm/npm-hosted/ --access restricted

# 干净目录验证安装走 GROUP
npm view @mycompany/hello --registry https://repo.anguskit.com/npm/npm-all/
npm install @mycompany/hello --registry https://repo.anguskit.com/npm/npm-all/

验收勾选：whoami 成功 → publish 成功 → 另一干净目录经 GROUP view/install 成功。whoami 失败就先别 publish。401 / scope 错位见文末参考：npm publish 401 排查。

同一台机器上再跑一次「假干净」核对，避免本机缓存骗过验收：

# 看生效 registry，确认不是全局仍指向 npmjs
npm config get registry
# 若项目用了 scope 映射，还应看到 @mycompany 指向 GROUP
npm config get @mycompany:registry

公共包是否命中 PROXY、直连不稳怎么排，见文末参考：国内访问 npmjs 不稳怎么办——勿与本文起步步骤混读成两篇同构教程。

4. 用 /explore 做公开发现

合作方不愿收令牌时：

1. 单独建 public-npm（HOSTED），勾选公开（isPublic）。不要公开日常 npm-hosted，也不要公开聚合了私有仓的 GROUP。
2. 用 Write 令牌（repod_ 或 PAT）只往 public-npm 发正式版（禁 SNAPSHOT）。
3. 无痕浏览器打开 https://repo.anguskit.com/explore（或 /explore/artifacts 搜包），在详情页复制免认证安装命令，在干净环境执行。

公开门户规则与验收清单见文末参考：私有仓制品怎么公开下载。门户与控制台同一实例；勾选公开后索引可能有数十秒～数分钟延迟。门户顶栏「文档」仍禁用时，外链应指向 AngusKit 文档站，勿承诺门户内文档。

5. 边界与翻车表

现象	常见原因	处理
存储写满 / publish 被拒	用量触顶（以控制台当前租户为准）	清理旧包或旧版本；或改社区自建
publish 401	Token 绑错仓、路径少 /、混用 HTTP	对照接入配置与 _authToken 主机路径
install 仍走 npmjs	registry 未指 GROUP，或 lock 锁旧源	npm config list；清 lock 重装
合作方 401	链到了私有仓	用 /explore 详情页生成的匿名命令
无法再建仓	仓数触顶（以控制台为准）	合并 HOSTED/PROXY/GROUP/公开仓用途
依赖混淆	内部名与公共包同名且 GROUP 顺序错误	HOSTED 优先；内部用公司 scope

门禁默认关；Repo 做轻量执法，深度 Finding 在 AngusSecurity——入库被拦见文末参考：制品入库门禁。

FAQ

云服务能发生产包吗？

技术上能发。是否够用看控制台当前租户的用量与限额；生产流量与合规要求高时可改社区自建。

和 Verdaccio / 自建有什么差别？

云服务省掉 Compose 与证书运维；拓扑仍是 HOSTED / PROXY / GROUP。要内网断网构建，见文末参考：离线构建预热。

/explore 能代替 ACL 吗？

不能。公开只解决匿名只读分发；按人授权仍用仓库 ACL + 令牌。

用量触顶后会怎样？

以控制台当前租户显示的用量与限额为准；触顶后 publish / 上传会被拒绝。清理旧包或改社区自建后再试。

小结

• 云服务可跑通私有 npm 主路径（三仓拓扑）。
• 开发机一个 GROUP；CI 只写 HOSTED（repod_）。
• 对外分发：public-npm + /explore，禁 SNAPSHOT。

参考文章

• npm 私服怎么搭（私有化）：https://www.anguskit.com/zh/blog/npm-private-registry
• npm 格式手册：https://www.anguskit.com/zh/docs/repo/manual/05-formats/03-npm
• 公开门户手册：https://www.anguskit.com/zh/docs/repo/manual/15-portal
• 私有仓制品怎么公开下载：https://www.anguskit.com/zh/blog/public-portal-launch
• Deploy Token 与 ACL：https://www.anguskit.com/zh/blog/angusrepo-deploy-token-pat-acl-guide
• pnpm / yarn 私有源：https://www.anguskit.com/zh/blog/pnpm-yarn-private-registry
• npm publish 401 排查：https://www.anguskit.com/zh/blog/npm-publish-401-troubleshooting
• 制品入库门禁：https://www.anguskit.com/zh/blog/artifact-repo-vulnerability-license-scanning
• 离线构建预热：https://www.anguskit.com/zh/blog/offline-build-maven-npm-warm-cache
• 国内访问 npmjs 不稳怎么办：https://www.anguskit.com/zh/blog/npmjs-registry-alternative

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/u013731477/article/details/168446705