bunfig.toml 是 Bun 的配置文件。
Bun 在可能的情况下依赖于已有的配置文件,如 package.json 和 tsconfig.json;bunfig.toml 仅用于 Bun 特定的设置。该文件是可选的,Bun 没有它也能正常工作。
全局配置 vs 本地配置
将bunfig.toml 放在项目根目录,与 package.json 同级。
要全局配置 Bun,你还可以在以下路径之一创建 .bunfig.toml 文件:
$HOME/.bunfig.toml$XDG_CONFIG_HOME/.bunfig.toml
bunfig,它会进行浅合并,本地设置覆盖全局设置。CLI 标志在适用时覆盖 bunfig 设置。
运行时
bunfig.toml 中的顶级字段配置 Bun 的运行行为。
preload
在运行文件或脚本之前执行的脚本/插件数组。
bunfig.toml
jsx
配置 Bun 如何处理 JSX。你也可以在 tsconfig.json 的 compilerOptions 中设置这些字段,但 bunfig.toml 为非 TypeScript 项目提供了支持。
bunfig.toml
smol
启用 smol 模式。这会减少内存使用,但会牺牲性能。
bunfig.toml
logLevel
设置日志级别:"debug"、"warn" 或 "error"。
bunfig.toml
define
define 字段将全局标识符替换为常量表达式(在代码中所有出现处)。表达式应为 JSON 字符串。
bunfig.toml
loader
配置 Bun 如何将文件扩展名映射到加载器。用于加载 Bun 原生不支持的文件类型。
bunfig.toml
jsxjststsxcssfilejsontomlwasmnapibase64dataurltext
telemetry
telemetry 字段启用或禁用遥测功能。默认情况下,遥测是启用的。这相当于 DO_NOT_TRACK 环境变量。
我们目前不收集遥测数据;此设置仅控制匿名崩溃报告。我们计划收集诸如最常用哪些 Bun API 或 bun build 耗时等信息。
bunfig.toml
env
配置自动 .env 文件加载。Bun 默认会加载 .env 文件。要禁用此行为:
bunfig.toml
file 属性:
bunfig.toml
--env-file 显式传入的文件仍然会被加载。
console
配置控制台输出行为。
console.depth
设置 console.log() 对象检查的默认深度。默认值为 2。
bunfig.toml
--console-depth CLI 标志会覆盖此设置。
Serve
[serve] 部分用于配置 HTTP 服务时的 Bun.serve 和 bun run。
serve.port
Bun.serve 监听的默认端口。默认值为 3000。也可以通过 BUN_PORT 或 PORT 环境变量或 --port 标志设置。
bunfig.toml
测试运行器
bunfig.toml 的 [test] 部分用于配置测试运行器。
bunfig.toml
test.root
运行测试的根目录。默认为 .。
bunfig.toml
test.preload
与顶层的 preload 字段相同,但仅适用于 bun test。
bunfig.toml
test.pathIgnorePatterns
使用 glob 模式从测试发现中排除文件和目录。匹配的目录会在扫描过程中被修剪,因此不会遍历其内容。当你的项目包含子模块或供应商代码且其中包含你不想让 bun test 检测到的 *.test.ts 文件时使用。
bunfig.toml
--path-ignore-patterns。CLI 标志会完全覆盖 bunfig.toml 中的值。
test.smol
与顶层的 smol 字段相同,但仅适用于 bun test。
bunfig.toml
test.coverage
启用覆盖率报告。默认为 false。使用 --coverage 覆盖。
bunfig.toml
test.coverageThreshold
覆盖率阈值。默认情况下未设置阈值。如果测试套件未达到该值,bun test 以非零退出码退出。
bunfig.toml
bunfig.toml
test.coverageSkipTestFiles
是否在计算覆盖率统计信息时跳过测试文件。默认为 false。
bunfig.toml
test.coverageIgnoreSourcemaps
是否针对转译后的输出报告覆盖率,而不是通过 sourcemaps 将行号映射回原始源代码。默认为 false。主要用于调试。
bunfig.toml
test.coveragePathIgnorePatterns
使用 glob 模式从覆盖率报告中排除文件。接受单个模式或模式数组。
bunfig.toml
test.coverageReporter
默认情况下,覆盖率报告会打印到控制台。对于 CI 和其他工具可以读取的持久化报告,请使用 lcov。
bunfig.toml
test.coverageDir
设置覆盖率报告的保存路径。这仅适用于持久化报告器(如 lcov)。
bunfig.toml
test.randomize
以随机顺序运行测试。默认为 false。
bunfig.toml
seed 结合使用时,随机顺序变得可重现。
--randomize CLI 标志会覆盖此设置。
test.seed
设置测试随机化的随机种子。此选项要求 randomize 为 true。
bunfig.toml
--seed CLI 标志会覆盖此设置。
test.rerunEach
将每个测试文件重新运行指定次数。默认为 0(运行一次)。
bunfig.toml
--rerun-each CLI 标志会覆盖此设置。
test.retry
所有测试的默认重试次数。失败的测试最多会重试此次数。单个测试的 { retry: N } 会覆盖此值。默认为 0(不重试)。
bunfig.toml
--retry CLI 标志会覆盖此设置。
test.concurrentTestGlob
匹配此 glob 模式的测试文件会以并发方式运行其所有测试,就像传递了 --concurrent 标志一样。
bunfig.toml
--concurrent CLI 标志会覆盖此设置。
test.onlyFailures
启用后,只显示失败的测试,从而减少大型测试套件中的噪音。默认为 false。
bunfig.toml
--only-failures 标志。
test.reporter
配置测试报告器设置。
test.reporter.dots
启用点报告器,每个测试打印一个点。默认为 false。
bunfig.toml
test.reporter.junit
启用 JUnit XML 报告并指定输出文件路径。
bunfig.toml
包管理器
[install] 部分配置 bun install 的行为。
bunfig.toml
install.optional
是否安装可选依赖。默认为 true。
bunfig.toml
install.dev
是否安装开发依赖。默认为 true。
bunfig.toml
install.peer
是否安装对等依赖。默认为 true。
bunfig.toml
install.production
bun install 是否以”生产模式”运行。默认为 false。
在生产模式下,"devDependencies" 不会安装。--production CLI 标志会覆盖此设置。
bunfig.toml
install.exact
是否在 package.json 中设置精确版本。默认为 false。
默认情况下,Bun 使用插入符范围;如果某个包的 latest 版本是 2.4.1,Bun 会在 package.json 中写入 ^2.4.1,这接受从 2.4.1 到(但不包括)3.0.0 的任何版本。
bunfig.toml
install.ignoreScripts
是否在安装期间跳过生命周期脚本。默认为 false。等同于 --ignore-scripts 标志。
当为 true 时,Bun 不会运行任何 preinstall / install / postinstall / prepare 脚本,无论是对于你的项目还是对于 trustedDependencies 中的包。参见生命周期脚本。
bunfig.toml
install.concurrentScripts
同时运行的最大生命周期脚本数量。默认为 CPU 核心数的两倍。等同于 --concurrent-scripts 标志。
bunfig.toml
install.saveTextLockfile
如果为 false,bun install 在无锁定文件时会生成二进制 bun.lockb 而不是基于文本的 bun.lock 文件。
默认为 true(自 Bun v1.2 起)。
bunfig.toml
install.auto
配置 Bun 的自动安装行为。默认为 "auto"——当找不到 node_modules 文件夹时,Bun 会在执行期间动态安装依赖。
bunfig.toml
install.prefer
配置 Bun 在运行脚本时如何针对 npm 注册表解析包版本。默认为 "online"。
bunfig.toml
install.frozenLockfile
当为 true 时,bun install 不会更新 bun.lock。默认为 false。如果 package.json 和现有的 bun.lock 不一致,安装会报错。
bunfig.toml
install.dryRun
bun install 是否实际安装依赖。默认为 false。当为 true 时,等同于向所有 bun install 命令传递 --dry-run。
bunfig.toml
install.globalDir
Bun 放置全局安装包的目录。
环境变量:BUN_INSTALL_GLOBAL_DIR
bunfig.toml
install.globalBinDir
Bun 链接全局安装包的二进制文件的目录。
环境变量:BUN_INSTALL_BIN
bunfig.toml
install.registry
默认注册表为 https://registry.npmjs.org/。要修改:
bunfig.toml
install.linkWorkspacePackages
是否将 monorepo 根目录的工作区包链接到各自的 node_modules 目录。默认为 true。
bunfig.toml
install.scopes
要为特定 scope(例如 @myorg/<package>)配置注册表,请使用 install.scopes。你可以使用 $variable 语法引用环境变量。
bunfig.toml
install.ca 和 install.cafile
要配置 CA 证书,将 install.ca 设置为证书字符串或将 install.cafile 设置为证书文件路径。
bunfig.toml
install.cache
配置缓存行为:
bunfig.toml
install.lockfile
是否在 bun install 时生成锁定文件。默认为 true。
bunfig.toml
bun.lock 之外生成非 Bun 锁定文件。(始终会创建 bun.lock。)"yarn" 是唯一支持的值。
bunfig.toml
install.linker
配置链接器策略:bun install 如何在 node_modules 中布局依赖。新工作区默认为 "isolated",新的单包项目和已有项目(v1.3.2 之前创建)默认为 "hoisted"。
参见隔离安装。
bunfig.toml
install.globalStore
使用 "isolated" 链接器时,在 <cache>/links/ 的全局虚拟存储中共享项目间的包安装,并将 node_modules/.bun/<pkg>@<ver> 链接到其中,而不是将每个包实例化到项目中。这使得 rm -rf node_modules 之后的冷安装快一个数量级。默认为 false。也可以通过 BUN_INSTALL_GLOBAL_STORE 环境变量设置。
参见全局虚拟存储。
bunfig.toml
install.publicHoistPattern
使用 "isolated" 链接器时,匹配这些 glob 模式的包会被提升到根 node_modules 目录,以便项目中的任何包都可以解析它们。默认为 []。类似 pnpm 的 public-hoist-pattern。
bunfig.toml
install.hoistPattern
使用 "isolated" 链接器时,匹配这些 glob 模式的包会被提升到虚拟存储根目录(node_modules/.bun),以便虚拟存储中的其他包可以解析它们。默认为 []。类似 pnpm 的 hoist-pattern。
bunfig.toml
install.logLevel
设置 bun install 的日志级别。可以是 "debug"、"warn" 或 "error"。
bunfig.toml
install.security.scanner
配置安全扫描器以在安装前扫描包的漏洞。
首先,从 npm 安装安全扫描器:
terminal
@oven/bun-security-scanner 是一个示例包名,并非真实包。请替换为你想要使用的扫描器,并查阅该扫描器的文档获取确切的包名和安装说明。大多数扫描器使用 bun add 安装。bunfig.toml 中配置:
bunfig.toml
- 为安全考虑,自动安装会自动禁用
- 包在安装前会被扫描
- 如果发现致命问题,安装会被取消
- 安装期间会显示安全警告
install.minimumReleaseAge
配置 npm 包版本的最小发布年龄(以秒为单位)。发布比此阈值更新的包版本会在安装期间被过滤掉。默认为 null(禁用)。
bunfig.toml
install.minimumReleaseAgeExcludes
免除 minimumReleaseAge 检查的包名数组。默认为 []。
bunfig.toml
bun run
[run] 部分配置 bun run 命令。这些设置也适用于运行文件、脚本或可执行文件时的 bun 命令。
对于 bun run,Bun 只自动加载本地项目的 bunfig.toml(它不会检查全局的 .bunfig.toml)。
run.shell - 使用系统 shell 或 Bun 的 shell
用于通过 bun run 或 bun 运行 package.json 脚本的 shell。Windows 上默认为 "bun",其他平台上默认为 "system"。
要始终使用系统 shell 而非 Bun 的 shell(除 Windows 外的默认行为):
bunfig.toml
bunfig.toml
run.bun - 自动将 node 别名为 bun
当为 true 时,这会在 $PATH 前添加一个指向 bun 二进制文件的 node 符号链接,适用于所有由 bun run 或 bun 调用的脚本或可执行文件。
运行 node 的脚本会改为运行 bun,无需修改脚本。这可以递归工作,因此运行另一个运行 node 的脚本的脚本也会运行 bun,并且它适用于指向 node 的 shebang。
默认情况下,如果 $PATH 中尚未存在 node,则启用此功能。
bunfig.toml
bun run 命令前加上 --bun:
false 以禁用 node 符号链接。
run.silent - 禁止报告正在运行的命令
当为 true 时,bun run 和 bun 不会打印正在运行的命令。
bunfig.toml
terminal
bun run 命令传递 --silent:
run.elide-lines - 截断过滤后的输出
使用 --filter 时,每个脚本显示的脚本输出行数。默认为 10。设置为 0 以显示所有行。等同于 --elide-lines 标志。
bunfig.toml
run.noOrphans - 不留下孤儿进程
当为 true 时,Bun 会监视生成它的进程,并在父进程消失后立即退出,即使父进程是被强制杀死且从未有机会转发信号。Bun 自身退出时,也会终止每个后代进程,以确保它产生的任何进程都不会比它更长寿。当 Bun 由可能被强制杀死的监管程序(Electron、CI 运行器、薄 shim)启动时非常有用。
在 Linux 上,这使用 prctl(PR_SET_PDEATHSIG) 和 /proc 后代遍历;在 macOS 上,使用事件循环的 kqueue 上的 EVFILT_PROC/NOTE_EXIT 和 libproc 后代遍历;在 Windows 上,使用线程池等待父进程句柄和关闭时的 Job Object 终止。
等同于 --no-orphans CLI 标志或 BUN_FEATURE_FLAG_NO_ORPHANS=1 环境变量。
bunfig.toml