Bun 私有包注册表配置指南：bunfig.toml 与 .npmrc 配置、认证及离线安装实战

Bun 私有包注册表配置指南bunfig.toml 与 .npmrc 配置、认证及离线安装实战【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun本文覆盖 Bun 包管理器自定义 npm 注册表的完整场景在bunfig.toml或.npmrc中配置私有源与作用域路由、注入认证令牌、隔离网络下的离线缓存策略以及 401/404/证书三类常见故障的排查路径。以下配置均以 Bun 1.3.x 的行为为准关键结论可直接在仓库文档中对照源码核实。场景还原私有包安装报 404 或 401在装了私有源的项目里执行bun add company/utils两种报错最常见$ bun add company/utils error: Package not found (404) —— 注册表返回了 404 # 或者 error: Request to registry failed (401) —— 凭据未匹配404 通常意味着请求根本没走到私有源作用域键名写错、.npmrc被更高优先级的配置覆盖401 则意味着请求走对了但令牌没被送到——凭据按主机路径匹配URL 差一个字符都会匹配失败。原理速览Bun 从哪里读取注册表配置Bun 按以下顺序加载配置后面的来源覆盖前面的同名配置~/.npmrc用户级./.npmrc项目级bunfig.toml全局然后项目环境变量BUN_CONFIG_REGISTRY/BUN_CONFIG_TOKEN兼容 npm 的NPM_CONFIG_REGISTRY/NPM_CONFIG_TOKEN命令行参数如--registry凭据独立于注册表 URL 匹配.npmrc里//host/path/:_authToken形式的凭据只要主机和路径与目标注册表一致就会生效即使注册表 URL 本身是在bunfig.toml里设置的。先确认你手里的配置到底来自哪里再动手改# 打印项目实际加载的注册表与作用域配置含 token 时仅显示占位信息 $ bun pm ls company/utils --verbose如果输出里没有你预期的私有源地址说明配置没被加载或被覆盖了按上表从后往前排查。配置 bunfig.toml默认源与作用域Bun 私有包注册表的标准写法位于bunfig.toml的[install]和[install.scopes]两个段落。默认源用[install] registry按组织划分的私有包用[install.scopes]。token、password处用your-xxx-here占位实际使用时替换为真实值切勿提交到版本控制。# 方式一推荐作用域注册表 环境变量令牌token 不落盘 [install] # 未命中任何 scope 的包仍走此默认源保证公共包解析不受影响 registry https://registry.npmjs.org/ [install.scopes] # 键名必须带 值支持字符串或 { url, token, username, password } 对象 company { url https://npm.company.com/, token $NPM_TOKEN } # 方式二用户名/密码认证$npm_password 从环境变量注入 vendor { username ci-bot, password $npm_password, url https://npm.vendor.com/ }字符串形式也合法但无法携带认证信息仅适合内网匿名源[install.scopes] # 内网匿名源整个注册表地址作为字符串 intranet https://10.0.0.8:4873/与 npm 不同[install.scopes]的键是精确匹配的作用域名不带 会报错不支持internal-*这类通配符。非作用域包想改源只能改[install] registry让它整体指向私有源如 Verdaccio 这类同时代理公共包的镜像。迁移现有 .npmrc最小改动路径如果团队已经在用.npmrc管理私有源不必重写Bun 直接兼容读取且支持${VAR}环境变量替换# .npmrc作用域路由 按主机匹配的令牌凭据 # ${NPM_TOKEN} 在运行时替换变量未设置时原样保留不会静默置空 company:registryhttps://npm.company.com/ //npm.company.com/:_authToken${NPM_TOKEN}两个.npmrc特有的坑_password需要你自己 base64 编码而bunfig.toml的password字段写明文Bun 负责编码。凭据前缀//host/path/:必须与注册表 URL 的主机、路径完全一致少一个/都会 401。验证令牌本身是否有效绕开 Bun 直接请求私有源# 期望返回用户信息 JSON返回 401 说明令牌过期或权限不足问题在凭据而非 Bun $ curl -sf -H Authorization: Bearer your-npm-token-here https://npm.company.com/-/whoami验证配置生效三步确认法配置改完后按干跑 → 安装 → 查缓存三步验证避免直接全量安装。第一步干跑检查解析流程不会写任何文件# 只解析不落盘期望看到 resolved 计数且无 401/404 $ bun install --dry-run resolved 142 packages, audited in 1.2s第二步正常安装注意输出中的 resolved/downloaded 计数$ bun add company/utils company/utils 1.2.3 2 packages installed [812.00ms]第三步确认私有包确实从私有源拉取并进了全局缓存# 打印全局缓存目录期望看到 company/utils1.2.3 子目录 $ bun pm cache ~/.bun/install/cache $ ls ~/.bun/install/cache | grep company company/utils1.2.3离线与缓存隔离网络下的安装策略私有源在内网、构建机没有外网时Bun 的缓存机制让二次安装完全离线。缓存位于~/.bun/install/cache可用BUN_INSTALL_CACHE_DIR或[install.cache] dir改路径包以${name}${version}子目录存储同一包的多版本可共存。# 完全离线元数据与包体必须全部命中缓存缺失即报错 $ bun install --offline # 软性离线缓存命中直接用仅缺失项才访问网络 $ bun install --prefer-offline也可以写进配置让 CI 默认走缓存优先[install] # 等价于 --prefer-offline脚本运行时跳过注册表版本检查 prefer offline [install.cache] # 自建缓存盘时可指定独立目录 dir /data/bun-cache注意缓存命中判定的是版本区间内有缓存副本Cache-Control缓存还会让元数据最多滞后约 5 分钟——刚发布的私有包版本可能暂时解析不到这属于正常延迟而非配置错误。常见故障排查401令牌未送达原因凭据的主机/路径前缀与注册表 URL 不匹配或环境变量未导出。解法# 打印实际生效的凭据配置token 显示为占位核对主机与路径 $ bun pm ls --verbose # 确认导出后再执行 $ echo $NPM_TOKEN bun install404作用域包没走私有源原因.npmrc的scope:registry写成了scope:registry少了 或键名与包名大小写不一致。解法# 干跑观察解析目标确认 company/* 走私有源 $ bun install --dry-run # 修正键名后强制重新解析 $ bun install --force证书错误自签名私有源被拒原因公司内网私有源使用自签名证书默认 CA 链校验失败。解法在bunfig.toml注入内部 CA或在.npmrc用cafile指向证书文件[install] # cafile 指向内部 CA 证书路径也可直接在 ca 字段粘贴证书字符串 cafile /etc/ssl/company-ca.crt速查清单场景命令 / 配置位置配置作用域私有源bunfig.toml的[install.scopes]复用现有 npm 配置项目根.npmrcCI 注入令牌NPM_TOKEN环境变量 ${NPM_TOKEN}验证配置bun install --dry-run查看缓存目录bun pm cache清理缓存bun pm cache rm完全离线安装bun install --offline查看被拦截的脚本bun pm untrusted完整字段定义见 docs/pm/scopes-registries.mdx、docs/pm/npmrc.mdx注册表解析的实现位于 src/bunfig/ 与 src/install/配置行为有出入时可对照源码提 issue。输出文章 /输出文章【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考