用 3 行 bunfig.toml 接好 Bun 私有源：认证、离线与 CI 落地实操

用 3 行 bunfig.toml 接好 Bun 私有源认证、离线与 CI 落地实操【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun发版前夜 CI 变红bun install在acme/pay-sdk上报 401而本机一切正常。查下来发现 token 只存在某个同事的本地.npmrc里仓库从没配过公司私有源。这篇文章就从这次事故讲起把 Bun 自定义注册表与私有包管理走一遍bunfig.toml 三行配置、token 三种注入方式、依赖解析预览、离线安装以及 401 和版本冲突怎么定位。先判断你到底需不需要私有源不是所有项目都要动注册表配置对照这张表做个决定你的情况建议依赖全是公共 npm 包用默认 registry.npmjs.org什么都不用配自己的包在私有仓库带acme作用域bunfig.toml 里加一条作用域映射只让这个 scope 走私有源整个团队/公司统一走内网镜像改install.registry默认源构建机在隔离网络或内网先在线安装一次填满缓存再--offline离线安装原则有自有 scope 就只配 scope确实要全量走私有源才动默认注册表。配得越窄出问题的面越小。最小配置两分钟接上私有源这一节能让私有包在你机器上跑通。项目根目录bunfig.toml写三行[install.scopes] acme { url https://npm.acme.example/, token $NPM_TOKEN }然后设置本机环境变量NPM_TOKEN或直接写死 token执行bun install --verbose解析输出里应看到acme/pay-sdk从https://npm.acme.example/拉取、公共包仍走公共源。通了就算成功。几个细节install.scopes按作用域匹配配好acme后acme/*下所有包自动走该源不需要逐个包配置源不要求认证时可以直接写字符串acme https://npm.acme.example/不带作用域的内部包没有acme前缀没法用 scope 映射只能整体换默认源或干脆给它加上 scope现有.npmrc里的acme:registry...配置 Bun 也能直接读可以平滑过渡token 放哪里三种方式私有源基本都要认证token 可以放在三个地方按需选1. 直接写在 bunfig.toml仅本机调试[install.scopes] acme { url https://npm.acme.example/, token npm_abc123... }省事但 token 会跟着仓库进 git团队协作别用。2. 引用环境变量推荐[install.scopes] acme { url https://npm.acme.example/, token $NPM_TOKEN }$NPM_TOKEN在安装时取环境变量值仓库里只有变量名。临时覆盖也可以用BUN_CONFIG_TOKEN... bun install这类环境变量直接传。3. 兼容.npmrc团队已有.npmrc的不必迁移Bun 按 npm 语义原样读取acme:registryhttps://npm.acme.example/ //npm.acme.example/:_authToken${NPM_TOKEN}多处配置时的优先级从低到高~/.npmrc→ 项目.npmrc→bunfig.toml→BUN_CONFIG_TOKEN等环境变量 →--registry等命令行参数后者覆盖前者。安装之前先看包从哪来这一节解决不确定依赖解析来源的问题——先预览再落锁文件。bun install --dry-run不安装任何东西只打印每个依赖及其来源注册表。想看完整过程就加--verbosebun install --verbose规则很简单显式作用域配置优先于默认注册表命令行参数优先级最高。多个源冲突时先看--dry-run输出——如果该走私有源的包显示的是公共源说明作用域映射没生效拼错了或该包不在你的 scope 下。离线安装与全局缓存这一节服务隔离网络内网构建机、完全不通外网的环境。Bun 把下载过的每个包存进全局缓存~/.bun/install/cache/可用BUN_INSTALL_CACHE_DIR改路径。拷入node_modules时 Linux/Windows 用硬链接、macOS 用clonefile写时复制多个项目共享同一份数据磁盘上不重复占用。两个档位bun install --prefer-offline # 优先读缓存缺的才联网 bun install --offline # 完全不碰网络缺失直接报错bunfig.toml 里的常驻等价写法是install.prefer offline和install.offline true。推荐流程有网环境先bun install填满缓存隔离机再--offline。缓存维护bun pm cache ls # 查看缓存内容 bun pm cache rm # 清空缓存团队落地workspace、CI 与脚本安全这一节处理三件团队级的事配置共享、CI 认证、安装脚本安全。monorepo 共享配置。注册表写在根bunfig.tomlworkspaces下所有包自动生效不用逐包重复{ workspaces: [packages/*], trustedDependencies: [acme/build-tools] }Bun 默认不执行依赖的生命周期脚本只有白名单里的包放行这是防恶意postinstall的一道闸。想看当前哪些包还有未授信脚本bun pm untrustedCI 用 secret 注入 token。仓库里保持token $NPM_TOKEN流水线只负责注入密钥- run: bun install env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }}排障实录三个高频问题按报错 → 定位 → 修复讲。CI 报 401本机正常。真实报错error: 401 Unauthorized fetching .../acme%2fpay-sdk。这基本是认证问题而非网络问题。先核对作用域映射的 host 与 URL 是否一致——尾斜杠、路径差一点token 就会发错地方再确认 CI 机器上NPM_TOKEN真的注入了。验证 token 本身curl -H Authorization: Bearer npm_abc123... https://npm.acme.example/-/whoamiwhoami 能返回用户说明是配置没对上返回 401 就是 token 过期或权限不足找源的管理员换新的。同一个库出现多个版本。锁文件里lodash同时有 3.x 和 4.xpeer 依赖警告不断。这是公共包和私有包依赖同一库不同版本的经典冲突。用bun install --dry-run确认两个版本各自的来源然后在package.json里钉死{ overrides: { lodash: 4.17.21 } }之后bun install --force强制重新解析让整棵依赖树统一到一个版本。离线安装报缓存里没有。--offline时报某版本不在缓存。隔离机的缓存要么从没装过该版本要么被bun pm cache rm清掉了。到有网环境bun install --prefer-offline补一次缓存再把~/.bun/install/cache/同步到隔离机重新离线安装即可。附录命令速查目标命令 / 配置换默认注册表bunfig.toml 的install.registry作用域指向私有源bunfig.toml 的install.scopes预览解析不安装bun install --dry-run查看拉取来源bun install --verbose强制重新解析bun install --force离线安装bun install --offline/--prefer-offline查看 / 清理缓存bun pm cache ls/bun pm cache rm查看未授信依赖bun pm untrusted相关文档与源码install 命令文档作用域与注册表配置bunfig.toml 规范全局缓存机制.npmrc 兼容说明包管理器源码【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考