Skip to main content
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
只有包管理器命令(bun install、bun add、bun remove、bun update、bun pm、bunx 等)会读取全局文件。如果 Bun 同时找到全局和本地 bunfig,则会加载二者;本地文件中设置的键会覆盖全局文件中的同名键。适用时,CLI 标志会覆盖 bunfig 设置。

运行时

顶层字段用于配置 Bun 的运行时行为。

preload

一个脚本/插件数组,在运行文件或脚本前执行。
bunfig.toml

jsx

配置 Bun 处理 JSX 的方式。你也可以在 tsconfig.json 的 compilerOptions 中设置这些字段,但 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 流程中,如果你希望完全依赖系统环境变量,可以使用此配置。 即使禁用了默认加载,Bun 仍会加载通过 --env-file 显式传入的文件。

console

配置控制台输出行为。

console.depth

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

服务

[serve] 部分用于配置 Bun.serve 和提供 HTTP 服务时的 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 模式从测试发现中排除文件和目录。测试运行器会在扫描期间剪除匹配的目录,因此不会遍历其中的内容。如果项目包含带有 *.test.ts 文件、且不希望被 bun test 发现的子模块或 vendored 代码,可以使用此设置。
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
你可以为行覆盖率和函数覆盖率分别设置阈值。Bun 接受 statements 键,但目前不会强制执行该阈值。
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
CI 系统和其他工具可以使用此报告。

包管理器

[install] 部分配置 bun install 的行为。
bunfig.toml

install.optional

是否安装可选依赖。默认 true。
bunfig.toml

install.dev

是否安装开发依赖。默认 true。
bunfig.toml

install.peer

是否安装 peer 依赖。默认 true。
bunfig.toml

install.production

是否让 bun install 在“生产模式”下运行。默认 false。 在生产模式下,Bun 不会安装 "devDependencies",并会冻结锁文件(与 install.frozenLockfile 相同)。使用 --production CLI 标志可为单次安装启用此模式。由于生产模式会冻结锁文件,因此启用该模式时,bun add、bun remove 和 bun update 会失败。
bunfig.toml

install.exact

是否在 package.json 中设置精确版本号。默认 false。 默认情况下,Bun 使用 caret 范围。如果某个包的 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 文件。 默认自 Bun v1.2 起为 true。
bunfig.toml

install.auto

配置 Bun 的自动安装行为。默认值为 "auto"——找不到 node_modules 文件夹时,Bun 会在执行期间即时安装依赖。
bunfig.toml
有效值说明:

install.prefer

配置 Bun 在运行脚本时如何针对 npm 注册表解析包版本。默认 "online"。
bunfig.toml
有效值:

install.offline

当设置为 true 时,bun install 永远不会访问网络:包元数据和 tarball 必须已在缓存中,缺少任何内容都会报错。默认 false。等同于 bun install --offline。如需使用更宽松的“尽可能使用缓存”行为,请参阅 install.prefer = "offline" / --prefer-offline。
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

如需为特定作用域(例如 @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 始终会创建 bun.lock。)"yarn" 是唯一受支持的值。
bunfig.toml

install.linker

配置链接器策略:即 bun install 如何在 node_modules 中组织依赖。对于新的工作区,默认为 "isolated";对于新的单包项目和现有项目(在 v1.3.2 之前创建),默认为 "hoisted"。 请参阅隔离安装。
bunfig.toml
有效值:

install.globalStore

使用 "isolated" 链接器时,可在 <cache>/links/ 下的全局虚拟存储中共享多个项目之间的包安装。Bun 会将 node_modules/.bun/<pkg>@<ver> 链接到存储中,而不是将每个包实际写入项目目录。这样,在执行 rm -rf node_modules 后进行热安装,速度可提高一个数量级。默认 false。你也可以通过 BUN_INSTALL_GLOBAL_STORE 环境变量进行设置。 请参阅全局虚拟存储。
bunfig.toml

install.publicHoistPattern

使用 "isolated" 链接器时,Bun 会将匹配这些 glob 模式的包提升到根 node_modules 目录,使项目中的任何包都可以解析它们。默认 []。与 pnpm 的 public-hoist-pattern 类似。
bunfig.toml

install.hoistPattern

使用 "isolated" 链接器时,Bun 会将匹配这些 glob 模式的包提升到虚拟存储中的回退目录(node_modules/.bun/node_modules),使虚拟存储中的其他包可以解析它们。默认情况下,Bun 会将所有包提升到此目录中,等同于 ["*"]。与 pnpm 的 hoist-pattern 类似。
bunfig.toml

install.hoist

使用 "isolated" 链接器时,Bun 会创建 node_modules/.bun/node_modules。此回退目录包含指向每个已安装包的符号链接;如果设置了 install.hoistPattern,则只包含指向匹配包的符号链接。该目录位于存储中每个包的向上解析路径上,因此包仍可解析自己未声明的依赖(“幽灵依赖”)。将 hoist = false 可完全跳过此目录的创建。此时,除非导入的包已链接到项目根目录的 node_modules(即直接依赖、匹配 publicHoistPattern 的包或工作区包),否则存储中包的未声明导入会失败。项目自身的 node_modules 符号链接不会改变。默认 true。等同于 pnpm 的 hoist 设置,包括此处提到的根 node_modules 注意事项;其优先级高于 install.hoistPattern。 此设置仅适用于 "isolated" 链接器。提升式安装不受影响:在那里,扁平的 node_modules 树本身就是布局,而不是由此开关控制的内容。
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 包版本的最短发布时间(秒)。安装过程中,Bun 会筛除发布时间早于此阈值的包版本。默认 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
如需始终使用 Bun 的 shell 而非系统 shell:
bunfig.toml

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

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

run.silent — 静默运行,不输出命令提示

设为 true 时,bun run 和 bun 不会打印正在运行的命令。
bunfig.toml
如果不使用此选项,Bun 会将正在运行的命令打印到控制台:
terminal
使用此选项后,Bun 不会打印正在运行的命令:
这等同于对所有 bun run 命令使用 --silent 参数:

run.elide-lines - 截断过滤后的输出

在终端中使用 --filter 时,将每个脚本的输出截断为最后 N 行。默认 0(显示所有行)。等同于 --elide-lines 标志。
bunfig.toml

run.noOrphans - 不留下孤儿进程

设为 true 时,Bun 会监视启动它的进程,并在该父进程消失后立即退出,即使父进程被强制终止而来不及转发信号。当 Bun 自身退出时,也会终止所有后代进程,以确保它启动的进程不会继续运行。适用于由可能被强制终止的监控程序(Electron、CI 运行器或轻量级 shim)启动 Bun 的情况。 在 Linux 上,Bun 使用 prctl(PR_SET_PDEATHSIG) 和 /proc 后代进程遍历。在 macOS 上,Bun 使用事件循环 kqueue 上的 EVFILT_PROC/NOTE_EXIT 和 libproc 后代进程遍历。在 Windows 上,Bun 使用父进程句柄的线程池等待和关闭时终止进程的 Job Object。 等同于 --no-orphans CLI 标志或 BUN_FEATURE_FLAG_NO_ORPHANS=1 环境变量。
bunfig.toml