bunfig.toml - Bun 中文文档

Bun 的行为可以通过其配置文件 bunfig.toml 进行配置。一般来说，Bun 依赖于已有的配置文件，如 package.json 和 tsconfig.json 来配置其行为。bunfig.toml 仅在配置 Bun 特定内容时才需要。此文件是可选的，Bun 在没有它的情况下也能开箱即用。

全局 vs. 本地

通常建议在项目根目录下添加一个 bunfig.toml 文件，与 package.json 并列。要进行全局配置，你也可以在以下路径之一创建 .bunfig.toml 文件：

$HOME/.bunfig.toml
$XDG_CONFIG_HOME/.bunfig.toml

如果同时检测到全局与本地的 bunfig，结果将进行浅合并，本地设置覆盖全局。在适用情况下，CLI 标志将覆盖 bunfig 设置。

运行时

Bun 的运行时行为通过 bunfig.toml 文件中的顶级字段进行配置。

`preload`

一个脚本/插件数组，在运行文件或脚本前执行。

bunfig.toml

# 在使用 `bun run` 运行文件或脚本前执行的脚本
# 通过添加到此列表来注册插件
preload = ["./preload.ts"]

`jsx`

配置 Bun 如何处理 JSX。你也可以在 tsconfig.json 的 compilerOptions 中设置这些字段，但这里为了非 TypeScript 项目同样支持这些配置。

bunfig.toml

jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"

有关这些字段的更多信息，请参考 tsconfig 文档：

`smol`

启用 smol 模式。此模式会降低内存使用，但会牺牲性能。

bunfig.toml

# 降低内存使用，牺牲性能
smol = true

`logLevel`

设置日志级别。可以是 "debug"、"warn" 或 "error"。

bunfig.toml

logLevel = "debug" # "debug" | "warn" | "error"

`define`

define 字段允许你用常量表达式替换特定的全局标识符。Bun 会将任何该标识符的使用替换为指定表达式。表达式应是 JSON 字符串。

bunfig.toml

[define]
# 将所有 "process.env.bagel" 的使用替换为字符串 `lox`
# 值会被解析为 JSON，但支持单引号字符串，且 `'undefined'` 在 JS 中表示 undefined。
# 未来版本可能改为普通的 TOML 格式，目前保留此用法是继承自 CLI 参数解析。
"process.env.bagel" = "'lox'"

`loader`

配置 Bun 如何将文件扩展名映射到加载器。适用于加载 Bun 本身不原生支持的文件。

bunfig.toml

[loader]
# 当导入 .bagel 文件时，将其视为 tsx 文件
".bagel" = "tsx"

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

telemetry = false

`env`

配置自动 .env 文件加载。默认情况下，Bun 会自动加载 .env 文件。如需禁用此行为：

bunfig.toml

# 禁用自动加载 .env 文件
env = false

也可以使用对象语法并设置 file 属性：

bunfig.toml

[env]
file = false

这在生产环境或 CI/CD 流水线中很有用，这类场景下通常只依赖系统环境变量。注：即使禁用默认加载，通过 --env-file 明确指定的环境文件仍会被加载。

`console`

配置控制台输出行为。

`console.depth`

设置 console.log() 对象检测的默认深度。默认值为 2。

bunfig.toml

[console]
depth = 3

此设置控制控制台输出中对象呈现的嵌套层数。值越高，显示的嵌套属性越多，但复杂对象时输出会较冗长。该设置可被 --console-depth CLI 标志覆盖。

测试运行器

测试运行器配置于 bunfig.toml 的 [test] 部分。

bunfig.toml

[test]
# 在这里进行配置

`test.root`

运行测试的根目录。默认 .。

bunfig.toml

[test]
root = "./__tests__"

`test.preload`

与顶级 preload 字段相同，但仅应用于 bun test。

bunfig.toml

[test]
preload = ["./setup.ts"]

`test.smol`

与顶级 smol 字段相同，但仅应用于 bun test。

bunfig.toml

[test]
smol = true

`test.coverage`

启用覆盖率报告。默认 false。可以使用 --coverage 来覆盖。

bunfig.toml

[test]
coverage = false

`test.coverageThreshold`

指定覆盖率门槛。默认无门槛。如果测试覆盖率未达到此门槛，bun test 会以非零退出码表示失败。

bunfig.toml

[test]

# 要求做到 90% 的行级和函数级覆盖率
coverageThreshold = 0.9

也可分别为行覆盖、函数覆盖和语句覆盖设置不同门槛。

bunfig.toml

[test]
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }

`test.coverageSkipTestFiles`

计算覆盖率统计时是否跳过测试文件。默认 false。

bunfig.toml

[test]
coverageSkipTestFiles = false

`test.coveragePathIgnorePatterns`

使用 glob 模式排除特定文件或模式在覆盖率报告中的统计。可以是单个字符串，也可以是模式数组。

bunfig.toml

[test]
# 单个模式
coveragePathIgnorePatterns = "**/*.spec.ts"

# 多个模式
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

`test.coverageReporter`

默认情况下，覆盖率报告会输出到控制台。为了 CI 环境中持久保存和供其他工具使用，请使用 lcov。

bunfig.toml

[test]
coverageReporter  = ["text", "lcov"]  # 默认 ["text"]

`test.coverageDir`

设置覆盖率报告保存路径。仅对持久化的 coverageReporter（如 lcov）有效。

bunfig.toml

[test]
coverageDir = "path/to/somewhere"  # 默认 "coverage"

`test.randomize`

以随机顺序运行测试。默认 false。

bunfig.toml

[test]
randomize = true

此功能有助于捕获测试间相互依赖导致的 Bug。配合 seed 使用，随机顺序可复现。当指定 --randomize CLI 标志时，会覆盖此设置。

`test.seed`

设置测试随机化的随机种子。需要 randomize 为 true。

bunfig.toml

[test]
randomize = true
seed = 2444615283

设置种子可使随机测试顺序在多次运行中可复现，便于调试不稳定的测试。遇到失败时可用相同种子重现当时顺序。 --seed CLI 标志会覆盖此设置。

`test.rerunEach`

每个测试文件重复运行指定次数。默认 0（运行一次）。

bunfig.toml

[test]
rerunEach = 3

此功能有助于捕获不稳定或非确定性行为的测试。每个测试文件将被执行指定次数。 --rerun-each CLI 标志会覆盖此设置。

`test.concurrentTestGlob`

指定一个 glob 模式，使匹配的测试文件自动启用并发执行。这些测试文件行为等同于使用了 --concurrent 标志，文件内所有测试将并发运行。

bunfig.toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"

适用场景：

逐步迁移测试套件至并发执行
并发运行集成测试，同时单线程运行单元测试
将快速并发测试与需要依序运行的测试分开

当指定 --concurrent CLI 标志时，会覆盖此设置。

`test.onlyFailures`

启用后，仅显示失败的测试结果，减少大型测试套件的输出噪声。默认 false。

bunfig.toml

[test]
onlyFailures = true

等同于运行 bun test 时使用 --only-failures。

`test.reporter`

配置测试报告器设置。

`test.reporter.dots`

启用点状报告器，输出紧凑模式，每个测试用点表示。默认 false。

bunfig.toml

[test.reporter]
dots = true

`test.reporter.junit`

启用 JUnit XML 报告，并指定输出文件路径。

bunfig.toml

[test.reporter]
junit = "test-results.xml"

生成的 JUnit XML 可用于 CI 系统及其他工具。

包管理器

包管理是复杂的问题；为支持多种使用场景，bun install 的行为可在 [install] 部分配置。

bunfig.toml

[install]
# 这里进行配置

`install.optional`

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

bunfig.toml

[install]
optional = true

`install.dev`

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

bunfig.toml

[install]
dev = true

`install.peer`

是否安装 peer 依赖。默认 true。

bunfig.toml

[install]
peer = true

`install.production`

bun install 是否以“生产模式”运行。默认 false。生产模式下，不安装 "devDependencies"。CLI 中可使用 --production 覆盖此设置。

bunfig.toml

[install]
production = false

`install.exact`

是否在 package.json 中设置精确版本号。默认 false。默认情况下，Bun 使用插入符号版本范围；例如包的最新版本为 2.4.1，则 package.json 中的版本范围是 ^2.4.1，表示接受 2.4.1 到（不含）3.0.0 之间的任意版本。

bunfig.toml

[install]
exact = false

`install.saveTextLockfile`

如果为 false，当执行 bun install 并且不存在锁文件时，会生成二进制格式的 bun.lockb，而非文本格式的 bun.lock。默认自 Bun v1.2 起为 true。

bunfig.toml

[install]
saveTextLockfile = false

`install.auto`

配置 Bun 的包自动安装行为。默认 "auto" —— 如果未找到 node_modules 文件夹，Bun 会在执行时自动安装依赖。

bunfig.toml

[install]
auto = "auto"

有效值说明：

值	描述
`"auto"`	如果存在本地 `node_modules`，则从中解析模块。否则，在执行时自动安装依赖。
`"force"`	即使存在 `node_modules`，也总是自动安装依赖。
`"disable"`	从不自动安装依赖。
`"fallback"`	先检查本地 `node_modules`，对未找到的包自动安装。CLI 可用 `bun -i` 启用。

`install.frozenLockfile`

为 true 时，bun install 不会更新 bun.lock。默认 false。如果 package.json 与现有 bun.lock 不匹配，则会报错。

bunfig.toml

[install]
frozenLockfile = false

`install.dryRun`

是否真正安装依赖。默认 false。为 true 则等同于所有 bun install 命令加上 --dry-run。

bunfig.toml

[install]
dryRun = false

`install.globalDir`

配置全局安装包的存放目录。环境变量：BUN_INSTALL_GLOBAL_DIR

bunfig.toml

[install]
# `bun install --global` 安装包的位置
globalDir = "~/.bun/install/global"

`install.globalBinDir`

配置全局安装的二进制文件和 CLI 的存放目录。环境变量：BUN_INSTALL_BIN

bunfig.toml

[install]
# 全局安装包的二进制文件链接存放位置
globalBinDir = "~/.bun/bin"

`install.registry`

默认注册表为 https://registry.npmjs.org/。可在全局的 bunfig.toml 中配置：

bunfig.toml

[install]
# 以字符串形式设置默认注册表
registry = "https://registry.npmjs.org"
# 设置 token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# 设置用户名/密码
registry = "https://username:[email protected]"

`install.linkWorkspacePackages`

配置工作区（monorepo）包的链接方式。是否将工作空间包从 monorepo 根目录链接到各自的 node_modules 目录。默认 true。

bunfig.toml

[install]
linkWorkspacePackages = true

`install.scopes`

为特定作用域（如 @myorg/<package>）配置注册表，使用 install.scopes。可通过 $variable 引用环境变量。

bunfig.toml

[install.scopes]
# 字符串格式注册表
myorg = "https://username:[email protected]/"

# 带用户名/密码，支持引用环境变量
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# 带 token
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

`install.ca` 和 `install.cafile`

配置 CA 证书，使用 install.ca 或 install.cafile 指定证书文件路径。

bunfig.toml

[install]
# CA 证书内容（字符串）
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# CA 证书文件路径，文件可以包含多个证书
cafile = "path/to/cafile"

`install.cache`

配置缓存行为：

bunfig.toml

[install.cache]

# 缓存目录
dir = "~/.bun/install/cache"

# 为 true 则不从全局缓存加载
# 但 Bun 仍可能写入 node_modules/.cache
disable = false

# 为 true 始终从注册表解析最新版本
disableManifest = false

`install.lockfile`

配置锁文件行为，使用 install.lockfile 部分。是否在 bun install 时生成锁文件。默认 true。

bunfig.toml

[install.lockfile]
save = true

是否在生成 bun.lock 之外，同时生成非 Bun 格式的锁文件。默认不生成。目前支持的取值只有 "yarn"。

bunfig.toml

[install.lockfile]
print = "yarn"

`install.linker`

配置安装依赖的链接策略。新工作区默认 "isolated"，新单包项目与现有项目（v1.3.2 以前版本）默认 "hoisted"。完整文档见包管理 > 隔离安装。

bunfig.toml

[install]
linker = "hoisted"

有效值：

值	描述
`"hoisted"`	链接依赖到共享的 `node_modules` 目录。
`"isolated"`	每个包安装内部各自链接依赖。

bunfig.toml

[debug]
# 访问 blob: 或 src: 链接时，在编辑器中打开文件
# 否则尝试 $EDITOR 或 $VISUAL
# 若失败，依次尝试 Visual Studio Code、Sublime Text 等编辑器
# 由 Bun.openInEditor() 使用
editor = "code"

# 支持的编辑器列表：
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"

`install.security.scanner`

配置安全扫描器，在安装前扫描包中的安全漏洞。首先，从 npm 安装安全扫描器：

terminal

bun add -d @acme/bun-security-scanner

然后在 bunfig.toml 配置：

bunfig.toml

[install.security]
scanner = "@acme/bun-security-scanner"

配置安全扫描器后：

自动安装功能自动禁用以保障安全
安装前扫描包
发现致命问题时取消安装
安装过程中显示安全警告

详细了解使用和编写安全扫描器。

`install.minimumReleaseAge`

配置 npm 包版本的最小发布日期（秒）。在安装时，会过滤掉比此阈值更新的版本。默认 null（禁用）。

bunfig.toml

[install]
# 只安装至少 3 天前发布的包版本
minimumReleaseAge = 259200
# 以下包绕过最小发布时间限制
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

更多详情见安装文档的最小发布年龄。

`bun run`

bun run 命令可在 [run] 部分配置。适用于 bun run 命令及 bun 命令运行文件、可执行程序或脚本时。当前，bunfig.toml 只会自动加载本地项目中的配置（不会检查全局 .bunfig.toml）。

`run.shell` — 使用系统 shell 还是 Bun 的 shell

通过 bun run 或 bun 运行 package.json 脚本时使用的 shell。Windows 默认 "bun"，其他平台默认 "system"。如需始终使用系统 shell（在非 Windows 上默认行为）：

bunfig.toml

[run]
# Windows 外的默认值
shell = "system"

如需始终使用 Bun 的 shell 而非系统 shell：

bunfig.toml

[run]
# Windows 默认值
shell = "bun"

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

为 true 时，会在所有由 bun run 或 bun 调用的脚本或可执行文件的 $PATH 前添加一个指向 bun 二进制的 node 符号链接。这意味着即使脚本内部调用 node，实际执行的也是 bun，无需更改脚本。此映射支持递归调用，对使用 node 的 shebang 同样生效。默认情况下，如果 $PATH 中尚无 node，此功能启用。

bunfig.toml

[run]
# 相当于对所有 `bun run` 命令启用 `--bun`
bun = true

你可以通过以下命令测试：

bun --bun which node # /path/to/bun
bun which node      # /path/to/node

此选项等同于为所有 bun run 命令加上 --bun 参数：

bun --bun run dev
bun --bun dev
bun run --bun dev

设置为 false 时禁用该功能。

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

为 true 时，禁止 bun run 或 bun 输出运行的命令信息。

bunfig.toml

[run]
silent = true

无此选项时，命令会打印如下：

terminal

bun run dev
echo "Running \"dev\"..."

Running "dev"...

启用该选项后，命令将不再打印：

bun run dev

Running "dev"...

这等同于对所有 bun run 命令使用 --silent 参数：

bun --silent run dev
bun --silent dev
bun run --silent dev

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

​全局 vs. 本地

​运行时

​preload

​jsx

​smol

​logLevel

​define

​loader

​telemetry

​env

​console

​console.depth

​测试运行器

​test.root

​test.preload

​test.smol

​test.coverage

​test.coverageThreshold

​test.coverageSkipTestFiles

​test.coveragePathIgnorePatterns

​test.coverageReporter

​test.coverageDir

​test.randomize

​test.seed

​test.rerunEach

​test.concurrentTestGlob

​test.onlyFailures

​test.reporter

​test.reporter.dots

​test.reporter.junit

​包管理器

​install.optional

​install.dev

​install.peer

​install.production

​install.exact

​install.saveTextLockfile

​install.auto

​install.frozenLockfile

​install.dryRun

​install.globalDir

​install.globalBinDir

​install.registry

​install.linkWorkspacePackages

​install.scopes

​install.ca 和 install.cafile

​install.cache

​install.lockfile

​install.linker

​install.security.scanner

​install.minimumReleaseAge

​bun run

​run.shell — 使用系统 shell 还是 Bun 的 shell

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

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

全局 vs. 本地

运行时

`preload`

`jsx`

`smol`

`logLevel`

`define`

`loader`

`telemetry`

`env`

`console`

`console.depth`

测试运行器

`test.root`

`test.preload`

`test.smol`

`test.coverage`

`test.coverageThreshold`

`test.coverageSkipTestFiles`

`test.coveragePathIgnorePatterns`

`test.coverageReporter`

`test.coverageDir`

`test.randomize`

`test.seed`

`test.rerunEach`

`test.concurrentTestGlob`

`test.onlyFailures`

`test.reporter`

`test.reporter.dots`

`test.reporter.junit`

包管理器

`install.optional`

`install.dev`

`install.peer`

`install.production`

`install.exact`

`install.saveTextLockfile`

`install.auto`

`install.frozenLockfile`

`install.dryRun`

`install.globalDir`

`install.globalBinDir`

`install.registry`

`install.linkWorkspacePackages`

`install.scopes`

`install.ca` 和 `install.cafile`

`install.cache`

`install.lockfile`

`install.linker`

`install.security.scanner`

`install.minimumReleaseAge`

`bun run`

`run.shell` — 使用系统 shell 还是 Bun 的 shell

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

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