bunfig.toml 配置文件

很多团队在把 Bun 真正接进项目后，很快会遇到一个问题：

• 安装策略放哪
• bun run 的行为怎么统一
• test runner 的默认参数怎么收口
• registry、workspace、lockfile 这些偏工程配置怎么落地

这时就会碰到 bunfig.toml。

bunfig.toml 是做什么的

官方文档里，bunfig.toml 用来配置 Bun 的行为。它覆盖的不是单条命令，而是会落到这些层：

• runtime
• test runner
• package manager
• bun run

也就是说，它更像 Bun 生态下的一份项目级配置入口。

一个最常见的起步配置

[install]
frozenLockfile = true
linkWorkspacePackages = true

[run]
shell = "system"

[test]
coverage = true
reporter = "dots"

这份配置已经覆盖了团队项目里最常见的几类诉求：

• 安装时锁文件更严格
• workspace 包默认联动
• bun run 统一 shell 行为
• 测试默认带覆盖率和报告器

配置文件一般放哪

通常就放在项目根目录：

project/
  bunfig.toml
  package.json
  bun.lock

如果仓库是 monorepo，这份配置更适合放在工作区根部统一管理。

[install] 这一层最常用

官方文档里，[install] 可以配置的项很多，但在前端项目里最常关注的通常是：

• frozenLockfile
• linkWorkspacePackages
• registry
• scopes
• cache
• lockfile

frozenLockfile

[install]
frozenLockfile = true

适合团队项目和 CI。这样可以尽量避免：

• lockfile 被意外更新
• 本地和 CI 安装结果分叉

linkWorkspacePackages

[install]
linkWorkspacePackages = true

如果仓库里大量依赖内部 workspace 包，这项会比较常见。

registry 和 scopes

[install]
registry = "https://registry.npmjs.org/"

[install.scopes]
"my-org" = { token = "$NPM_TOKEN", url = "https://registry.npmjs.org/" }

这一层很适合：

• 私有 npm 源
• 组织 scope 包
• CI 里统一 registry 策略

[run] 更适合管什么

官方文档里，[run] 直接影响 bun run 的行为。

最常见的几项是：

• shell
• bun
• silent

run.shell

[run]
shell = "system"

或：

[run]
shell = "bun"

这项的重点不是“哪个更高级”，而是团队脚本依赖的是哪种 shell 语义。

如果项目里已有很多 shell 脚本习惯，更稳的方式通常是先保守，用 system 看兼容。

run.bun

官方文档里，这项会影响 bun run 执行脚本时，是否把 node 自动映射到 bun。

这类选项在迁移阶段很关键，因为它会直接影响已有脚本的真实运行时。

[test] 这一层

如果项目已经准备使用 bun test，bunfig.toml 也能把常见测试配置收回来。

例如：

[test]
coverage = true
coverageDir = "coverage"
reporter = "dots"
timeout = 5000
retry = 1

这比把一长串测试参数全写在 CI 命令里更稳，也更容易统一本地和流水线。

一个更接近真实项目的配置参考

[install]
frozenLockfile = true
linkWorkspacePackages = true
registry = "https://registry.npmjs.org/"

[run]
shell = "system"
silent = false

[test]
coverage = true
coverageDir = "coverage"
reporter = "dots"
timeout = 5000
rerunEach = 0
retry = 1

这类配置适合：

• 前端应用
• monorepo
• 想把安装、脚本、测试都统一一点的团队

和 package.json scripts 的关系

bunfig.toml 不是用来替代 package.json scripts 的。

更稳的分工一般是：

• package.json：定义项目命令入口
• bunfig.toml：定义 Bun 在执行这些入口时的行为

这样职责更清楚。

什么时候值得早点加 bunfig.toml

• 团队已经准备统一使用 Bun
• monorepo 里有 shared workspace 行为
• CI 已经切到 Bun
• bun test 的默认参数不想散在命令行里

如果只是本地个人试用，短期内未必要立刻建这份配置。

更适合先记住的主线

bunfig.toml 更像一份“把 Bun 这套工具用法收口”的配置文件。

项目一旦从试用走到协作，它的价值会很快变明显。

参考来源

• bunfig.toml