Bun 自定义注册表实战快速接入私有包源与排错避坑指南【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun上周 CI 构建失败日志停在很具体的一行公网的lodash装上了私有的acme/ui-kit报 404。包管理器明明工作正常私有包却一件都拉不下来——问题出在私有源根本没配或者配错了地方。Bun 把「按 scope 路由到不同注册表」这件事做成了bunfig.toml里的一小段配置私有包管理的门槛因此低了很多。这篇文章讲三件事私有包到底怎么被 Bun 解析、最小可行配置怎么写、以及离线发版和 CI 里怎么不出事。私有包是怎么被 Bun 找到的核心机制一句话按包名前缀路由没命中的走默认源。带acme前缀的包去[install.scopes]里配的那条 URL 找没有任何规则命中的包去install.registry指定的默认注册表找不配就是registry.npmjs.org。配置不是只有一个入口。Bun 按下面的顺序加载后加载的覆盖先加载的~/.npmrc项目里的.npmrcbunfig.toml全局再到项目环境变量BUN_CONFIG_REGISTRY/BUN_CONFIG_TOKEN命令行参数--registry所以老项目的.npmrc不用急着改Bun 直接读。想统一配置时官方建议迁移到bunfig.toml。注册表这部分配置参考仓库内文档docs/pm/scopes-registries.mdx.npmrc兼容细节在docs/pm/npmrc.mdx。最小可行配置一条 scope 规则三步搞定改bunfig.toml→ 验证 → 装包。第 1 步在项目根目录的bunfig.toml里加一段[install.scopes] acme { url https://npm.acme.dev/, token $NPM_TOKEN }第 2 步先别急着装预览一下解析结果bun install --dry-run第 3 步像装公网包一样装私有包bun add acme/ui-kit几个细节值得记住scope作用域就是包名里的acme部分Bun 靠它决定包去哪找。认证不用 token 也行用户名密码同样支持acme { url https://npm.acme.dev/, username ci, password $NPM_PASSWORD }token 写$NPM_TOKEN而不是明文Bun 会替换环境变量。bunfig.toml通常要提交进仓库token 永远走环境变量注入。离线发版缓存 两个开关装过的包不会消失。Bun 把每个包存进全局缓存~/.bun/install/cache按「包名版本」分目录多个版本可以共存拷进node_modules时走 Linux/Windows 硬链接、macOS 写时复制磁盘上只存一份多个项目共享。缓存机制说明在仓库文档docs/pm/global-cache.mdx。离线场景两个开关级别不同--prefer-offline缓存优先缓存里缺的才联网补--offline完全不碰网络缺包直接报错逼你提前备齐。bun install --offline --frozen-lockfile「预热好的缓存 --frozen-lockfile--offline」组合可以让 CI 构建完全确定、完全不联网——这是内网发版能跑通的底牌。CI 集成把 token 从代码里挪走CI 里做两件事用bun ci代替bun install。它等价于install --frozen-lockfile版本号锁定在bun.lock上且package.json与 lockfile 不一致时直接失败而不是悄悄帮你改 lockfiletoken 走 CI secrets 注入环境变量命令前缀即可NPM_TOKEN$NPM_TOKEN bun ci.npmrc写法同样支持变量引用//npm.acme.dev/:_authToken${NPM_TOKEN}。 装完如果怀疑有包带「偷跑」的安装脚本Bun 默认拦截依赖的生命周期脚本只有列进package.json的trustedDependencies才放行。跑一下bun pm untrusted就能看到被拦下的是谁确认无误后用bun pm trust 包名显式放行。踩过的坑按错误反查配置401 Unauthorized先跑bun pm whoami验证当前 token 对哪个源有效再确认 scope 指向的 URL 和 token 签发的源是同一个。最常见的原因是 token 换了没同步或 scope 配错了源。404 / 包走了错误的源通常是 scope 拼写和包名前缀对不上acme配成ACME这类。用bun install --dry-run看解析预览一眼能看出包被路由去了哪。版本像被钉死了怀疑缓存里是旧元数据清掉全局缓存重拉bun pm cache rm本地和 CI 结果对不上先确认bun.lock提交了、两边都用bun ci再用bun why 包名打印依赖链看它到底是哪条路径拉进来的。什么时候配、配多少你的场景需要做的纯公网依赖什么都不用配一个组织一批私有包[install.scopes]里一条规则完事多个私有源混用默认install.registry兜底 每条 scope 精确匹配内网发版 / 离线环境预热缓存 --offline --frozen-lockfile已在用 npm / yarn.npmrc原样保留就能跑之后逐步迁到bunfig.toml最后给一句选型建议配置越少越容易维护。能一条 scope 规则解决的就别去动默认注册表能复用.npmrc的就先跑起来再迁移。Bun 这套注册表机制的边界很清晰——路由、认证、缓存三件事各管一段把这三段想明白私有包管理基本不会再给你挖坑。【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考