Skip to main content
bunfig.toml 是 Bun 的配置文件。 Bun 在可能的情况下依赖于已有的配置文件,如 package.jsontsconfig.jsonbunfig.toml 仅用于 Bun 特定的设置。该文件是可选的,Bun 没有它也能正常工作。

全局配置 vs 本地配置

bunfig.toml 放在项目根目录,与 package.json 同级。 要全局配置 Bun,你还可以在以下路径之一创建 .bunfig.toml 文件:
  • $HOME/.bunfig.toml
  • $XDG_CONFIG_HOME/.bunfig.toml
如果 Bun 同时找到全局和本地的 bunfig,它会进行浅合并,本地设置覆盖全局设置。CLI 标志在适用时覆盖 bunfig 设置。

运行时

bunfig.toml 中的顶级字段配置 Bun 的运行行为。

preload

在运行文件或脚本之前执行的脚本/插件数组。
bunfig.toml

jsx

配置 Bun 如何处理 JSX。你也可以在 tsconfig.jsoncompilerOptions 中设置这些字段,但 bunfig.toml 为非 TypeScript 项目提供了支持。
bunfig.toml
请参阅 tsconfig 文档了解这些字段的更多信息。

smol

启用 smol 模式。这会减少内存使用,但会牺牲性能。
bunfig.toml

logLevel

设置日志级别:"debug""warn""error"
bunfig.toml

define

define 字段将全局标识符替换为常量表达式(在代码中所有出现处)。表达式应为 JSON 字符串。
bunfig.toml

loader

配置 Bun 如何将文件扩展名映射到加载器。用于加载 Bun 原生不支持的文件类型。
bunfig.toml
Bun 支持以下加载器:
  • jsx
  • js
  • ts
  • tsx
  • css
  • file
  • json
  • toml
  • wasm
  • napi
  • base64
  • dataurl
  • text

telemetry

telemetry 字段启用或禁用遥测功能。默认情况下,遥测是启用的。这相当于 DO_NOT_TRACK 环境变量。 我们目前不收集遥测数据;此设置仅控制匿名崩溃报告。我们计划收集诸如最常用哪些 Bun API 或 bun build 耗时等信息。
bunfig.toml

env

配置自动 .env 文件加载。Bun 默认会加载 .env 文件。要禁用此行为:
bunfig.toml
你也可以使用对象语法配合 file 属性:
bunfig.toml
在生产环境或 CI/CD 管道中使用,此时你希望仅依赖系统环境变量。 即使默认加载被禁用,通过 --env-file 显式传入的文件仍然会被加载。

console

配置控制台输出行为。

console.depth

设置 console.log() 对象检查的默认深度。默认值为 2
bunfig.toml
较大的值会显示更多嵌套属性,但对于复杂对象可能会产生冗长的输出。--console-depth CLI 标志会覆盖此设置。

Serve

[serve] 部分用于配置 HTTP 服务时的 Bun.servebun run

serve.port

Bun.serve 监听的默认端口。默认值为 3000。也可以通过 BUN_PORTPORT 环境变量或 --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
等价的 CLI 标志:--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
每次以不同顺序运行测试有助于发现与测试间依赖相关的 bug。当与 seed 结合使用时,随机顺序变得可重现。 --randomize CLI 标志会覆盖此设置。

test.seed

设置测试随机化的随机种子。此选项要求 randomizetrue
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
CI 系统和其他工具可以读取此报告。

包管理器

[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

如果为 falsebun 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.cainstall.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 runbun 运行 package.json 脚本的 shell。Windows 上默认为 "bun",其他平台上默认为 "system" 要始终使用系统 shell 而非 Bun 的 shell(除 Windows 外的默认行为):
bunfig.toml
要始终使用 Bun 的 shell 而非系统 shell:
bunfig.toml

run.bun - 自动将 node 别名为 bun

当为 true 时,这会在 $PATH 前添加一个指向 bun 二进制文件的 node 符号链接,适用于所有由 bun runbun 调用的脚本或可执行文件。 运行 node 的脚本会改为运行 bun,无需修改脚本。这可以递归工作,因此运行另一个运行 node 的脚本的脚本也会运行 bun,并且它适用于指向 node 的 shebang。 默认情况下,如果 $PATH 中尚未存在 node,则启用此功能。
bunfig.toml
你可以通过运行以下命令测试:
此选项等同于在所有 bun run 命令前加上 --bun
设置为 false 以禁用 node 符号链接。

run.silent - 禁止报告正在运行的命令

当为 true 时,bun runbun 不会打印正在运行的命令。
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