news 2026/8/29 8:39:45

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

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
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 按以下顺序加载配置，后面的来源覆盖前面的同名配置：

  1. ~/.npmrc（用户级）
  2. ./.npmrc（项目级）
  3. bunfig.toml（全局，然后项目）
  4. 环境变量BUN_CONFIG_REGISTRY/BUN_CONFIG_TOKEN（兼容 npm 的NPM_CONFIG_REGISTRY/NPM_CONFIG_TOKEN）
  5. 命令行参数，如--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:registry=https://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/utils@1.2.3 子目录 $ bun pm cache ~/.bun/install/cache $ ls ~/.bun/install/cache | grep company @company/utils@1.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 install

404：作用域包没走私有源

原因：.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 配置项目根.npmrc
CI 注入令牌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），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/8/29 8:39:27

CNN-LSTM多输入回归预测全解析：从原理到评价指标

简介&#xff1a;时间序列预测是机器学习与工程实践中的核心任务之一&#xff0c;尤其在风速预测、电力负荷预测和设备寿命预测等场景中&#xff0c;准确建模多变量输入与目标输出之间的映射关系至关重要。传统方法中&#xff0c;长短期记忆网络擅长捕捉长期依赖&#xff0c;但…

作者头像 李华
网站建设 2026/8/29 8:39:19

Nexus 5变身GSM语音网关：Ubuntu下AT指令实现同时接听来电与去电

GSM 话机、Linux 网关、自动化语音系统之间一直有一个常见需求&#xff1a;把一台 Nexus 5 放到 Ubuntu 服务器旁边&#xff0c;让 Ubuntu 接管这台手机的来去电能力&#xff0c;从而实现自动拨号、自动接听&#xff0c;甚至在通话中处理第二个来电。标题里的“同时接听来电去电…

作者头像 李华
网站建设 2026/8/29 8:36:01

弹窗首帧不卡顿：Godot PackedScene 动态实例化场景管理上手指南

弹窗首帧不卡顿&#xff1a;Godot PackedScene 动态实例化场景管理上手指南 【免费下载链接】godot Godot Engine – Multi-platform 2D and 3D game engine 项目地址: https://gitcode.com/GitHub_Trending/go/godot 上次给聊天系统加第 4 种弹窗时&#xff0c;首帧直接…

作者头像 李华
网站建设 2026/8/29 8:35:15

MAS激活脚本指南：Windows免费激活最快路径

MAS激活脚本指南&#xff1a;Windows免费激活最快路径 【免费下载链接】Microsoft-Activation-Scripts Open-source Windows and Office activator featuring HWID, Ohook, TSforge, and Online KMS activation methods, along with advanced troubleshooting. 项目地址: htt…

作者头像 李华
网站建设 2026/8/29 8:34:12

车企造人形机器人：技术复用与量产挑战

最近几年&#xff0c;新能源车企的竞争已经不只是“车”本身&#xff0c;而是开始往“人形机器人”方向延伸。特斯拉、小鹏、小米、比亚迪等新造车或新能源产业链玩家&#xff0c;陆续展示机器人原型、投资初创公司、申请专利&#xff0c;甚至成立独立事业部。行业里把这件事叫…

作者头像 李华
网站建设 2026/8/29 8:31:08

Ant Design 紧凑模式：3 种开关 + 4 个坑一次讲清

Ant Design 紧凑模式&#xff1a;3 种开关 4 个坑一次讲清 【免费下载链接】ant-design An enterprise-class UI design language and React UI library 项目地址: https://gitcode.com/GitHub_Trending/an/ant-design 屏幕空间有限、内容却越堆越多&#xff1f;Ant De…

作者头像 李华