bunfig.toml

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

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

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

jsx

配置 Bun 处理 JSX 的方式。你也可以在 tsconfig.json 的 compilerOptions 中设置这些字段，但 bunfig.toml 支持在非 TypeScript 项目中使用它们。

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

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

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

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

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

logLevel

设置日志级别："debug"、"warn" 或 "error"。

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

define

define 字段会将全局标识符替换为常量表达式，无论它们出现在哪里。该表达式应为 JSON 字符串。

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

loader

配置 Bun 将文件扩展名映射到加载器的方式。使用此配置可以加载 Bun 原生不支持的文件类型。

[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 花费多长时间等信息。

telemetry = false

env

配置自动加载 .env 文件的行为。Bun 默认会加载 .env 文件。要禁用此行为：

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

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

[env]
file = false

在生产环境或 CI/CD 流程中，如果你希望完全依赖系统环境变量，可以使用此配置。

即使禁用了默认加载，Bun 仍会加载通过 --env-file 显式传入的文件。

console

配置控制台输出行为。

console.depth

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

[console]
depth = 3

较高的值会显示更多嵌套属性，但对于复杂对象可能会产生冗长的输出。--console-depth CLI 标志会覆盖此设置。

服务

[serve] 部分用于配置 Bun.serve 和提供 HTTP 服务时的 bun run。

serve.port

Bun.serve 监听的默认端口。默认值为 3000。你也可以通过 BUN_PORT 或 PORT 环境变量，或 --port 标志进行设置。

[serve]
port = 3000

测试运行器

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

[test]
# 在这里进行配置

test.root

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

[test]
root = "./__tests__"

test.preload

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

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

test.pathIgnorePatterns

使用 glob 模式从测试发现中排除文件和目录。测试运行器会在扫描期间剪除匹配的目录，因此不会遍历其中的内容。如果项目包含带有 *.test.ts 文件、且不希望被 bun test 发现的子模块或 vendored 代码，可以使用此设置。

[test]
pathIgnorePatterns = ["vendor/**", "submodules/**", "fixtures/**"]

等效 CLI 标志：--path-ignore-patterns。CLI 标志完全覆盖 bunfig.toml 的值。

test.smol

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

[test]
smol = true

test.coverage

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

[test]
coverage = false

test.coverageThreshold

覆盖率阈值。默认不设置阈值。如果测试套件未达到该阈值，bun test 将以非零退出代码退出。

[test]

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

你可以为行覆盖率和函数覆盖率分别设置阈值。Bun 接受 statements 键，但目前不会强制执行该阈值。

[test]
coverageThreshold = { lines = 0.7, functions = 0.8 }

test.coverageSkipTestFiles

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

[test]
coverageSkipTestFiles = false

test.coverageIgnoreSourcemaps

是否报告转译后的输出覆盖率，而不是通过 sourcemaps 将行号映射回原始源码。默认 false。主要用于调试。

[test]
coverageIgnoreSourcemaps = false

test.coveragePathIgnorePatterns

使用 glob 模式从覆盖率报告中排除文件。可以接受单个模式或模式数组。

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

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

test.coverageReporter

默认情况下，测试运行器会将覆盖率报告打印到控制台。如需生成 CI 和其他工具可读取的持久化报告，请使用 lcov。

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

test.coverageDir

设置保存覆盖率报告的路径。此配置仅适用于 lcov 等持久化报告器。

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

test.randomize

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

[test]
randomize = true

每次以不同顺序运行测试有助于发现与测试相互依赖相关的错误。与 seed 结合使用时，随机顺序可以复现。

--randomize CLI 标志会覆盖此设置。

test.seed

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

[test]
randomize = true
seed = 2444615283

随机种子可以让测试顺序在多次运行之间保持可复现，从而有助于调试不稳定的测试。

--seed CLI 标志会覆盖此设置。

test.rerunEach

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

[test]
rerunEach = 3

可以使用此配置来发现不稳定的测试或非确定性行为。

--rerun-each CLI 标志会覆盖此设置。

test.retry

所有测试的默认重试次数。测试运行器最多会重试失败的测试指定次数。每个测试的 { retry: N } 设置会覆盖此值。默认 0（不重试）。

[test]
retry = 3

--retry CLI 标志会覆盖此设置。

test.concurrentTestGlob

匹配此 glob 模式的测试文件将并发运行其中的所有测试，就像传入了 --concurrent 标志一样。

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

可以使用此配置逐步将测试套件迁移到并发执行，或在保持单元测试顺序执行的同时并发运行集成测试。

--concurrent CLI 标志会覆盖此设置。

test.onlyFailures

启用后，输出中只显示失败的测试，从而减少大型测试套件中的冗余信息。默认 false。

[test]
onlyFailures = true

等效于 --only-failures 标志。

test.reporter

配置测试报告器设置。

test.reporter.dots

启用点号报告器，每个测试打印一个点。默认 false。

[test.reporter]
dots = true

test.reporter.junit

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

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

CI 系统和其他工具可以使用此报告。

包管理器

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

[install]
# 这里进行配置

install.optional

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

[install]
optional = true

install.dev

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

[install]
dev = true

install.peer

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

[install]
peer = true

install.production

是否让 bun install 在“生产模式”下运行。默认 false。

在生产模式下，Bun 不会安装 "devDependencies"，并会冻结锁文件（与 install.frozenLockfile 相同）。使用 --production CLI 标志可为单次安装启用此模式。由于生产模式会冻结锁文件，因此启用该模式时，bun add、bun remove 和 bun update 会失败。

[install]
production = false

install.exact

是否在 package.json 中设置精确版本号。默认 false。

默认情况下，Bun 使用 caret 范围。如果某个包的 latest 版本为 2.4.1，Bun 会在你的 package.json 中写入 ^2.4.1。该范围接受从 2.4.1 起、但不包括 3.0.0 的任何版本。

[install]
exact = false

install.ignoreScripts

安装期间是否跳过生命周期脚本。默认 false。等同于 --ignore-scripts 标志。

当设置为 true 时，Bun 不会运行任何 preinstall / install / postinstall / prepare 脚本，包括项目中的脚本和 trustedDependencies 中包的脚本。请参阅生命周期脚本。

[install]
ignoreScripts = false

install.concurrentScripts

一次可并发运行的生命周期脚本最大数量。默认为 CPU 核心数的两倍。等同于 --concurrent-scripts 标志。

[install]
concurrentScripts = 5

install.saveTextLockfile

如果为 false，当不存在锁文件时，bun install 会生成二进制 bun.lockb，而不是基于文本的 bun.lock 文件。

默认自 Bun v1.2 起为 true。

[install]
saveTextLockfile = false

install.auto

配置 Bun 的自动安装行为。默认值为 "auto"——找不到 node_modules 文件夹时，Bun 会在执行期间即时安装依赖。

[install]
auto = "auto"

有效值说明：

install.prefer

配置 Bun 在运行脚本时如何针对 npm 注册表解析包版本。默认 "online"。

[install]
prefer = "online"

有效值：

install.offline

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

[install]
offline = true

install.frozenLockfile

当设置为 true 时，bun install 不会更新 bun.lock。默认 false。如果 package.json 与现有的 bun.lock 不一致，安装会报错。

[install]
frozenLockfile = false

install.dryRun

是否让 bun install 解析依赖但不安装。默认 false。当设置为 true 时，等同于向所有 bun install 命令传入 --dry-run。

[install]
dryRun = false

install.globalDir

Bun 存放全局安装包的目录。

环境变量：BUN_INSTALL_GLOBAL_DIR

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

install.globalBinDir

Bun 链接全局安装包二进制文件的目录。

环境变量：BUN_INSTALL_BIN

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

install.registry

默认注册表为 https://registry.npmjs.org/。如需更改：

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

install.linkWorkspacePackages

是否将工作区包从 monorepo 根目录链接到各自的 node_modules 目录。默认 true。

[install]
linkWorkspacePackages = true

install.scopes

如需为特定作用域（例如 @myorg/<package>）配置注册表，请使用 install.scopes。你可以使用 $variable 语法引用环境变量。

[install.scopes]
# 字符串格式注册表
myorg = "https://username:password@registry.myorg.com/"

# 带用户名/密码，支持引用环境变量
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 设置为证书文件的路径。

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

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

install.cache

配置缓存行为：

[install.cache]

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

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

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

install.lockfile

是否在执行 bun install 时生成锁文件。默认 true。

[install.lockfile]
save = true

是否在 bun.lock 之外同时生成非 Bun 锁文件。（Bun 始终会创建 bun.lock。）"yarn" 是唯一受支持的值。

[install.lockfile]
print = "yarn"

install.linker

配置链接器策略：即 bun install 如何在 node_modules 中组织依赖。对于新的工作区，默认为 "isolated"；对于新的单包项目和现有项目（在 v1.3.2 之前创建），默认为 "hoisted"。

请参阅隔离安装。

[install]
linker = "hoisted"

有效值：

install.globalStore

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

请参阅全局虚拟存储。

[install]
globalStore = true

install.publicHoistPattern

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

[install]
publicHoistPattern = ["*eslint*", "*prettier*"]

install.hoistPattern

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

[install]
hoistPattern = ["*"]

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 树本身就是布局，而不是由此开关控制的内容。

[install]
hoist = false

install.logLevel

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

[install]
logLevel = "warn"

install.security.scanner

配置安全扫描器，在安装前扫描包中的安全漏洞。

首先，从 npm 安装安全扫描器：

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

然后在你的 bunfig.toml 中进行配置：

[install.security]
scanner = "@oven/bun-security-scanner" # 示例名称，请替换为你的扫描器包名

配置安全扫描器后：

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

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

install.minimumReleaseAge

配置 npm 包版本的最短发布时间（秒）。安装过程中，Bun 会筛除发布时间早于此阈值的包版本。默认 null（禁用）。

[install]
# 只安装至少 3 天前发布的包版本
minimumReleaseAge = 259200

请参阅最短发布时间。

install.minimumReleaseAgeExcludes

从 minimumReleaseAge 检查中排除的包名数组。默认 []。

[install]
minimumReleaseAge = 259200
# 这些包将绕过 3 天的最小发布时间要求
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

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 外所有平台上的默认设置）：

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

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

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

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

当设置为 true 时，对于由 bun run 或 bun 调用的所有脚本或可执行文件，Bun 会在 $PATH 前添加一个指向 bun 二进制文件的 node 符号链接。

运行 node 的脚本会改为运行 bun，无需修改脚本。此行为会递归应用，因此，如果某个脚本运行另一个会运行 node 的脚本，该脚本也会运行 bun。此别名也适用于指向 node 的 shebang。

默认情况下，如果 $PATH 中尚无 node，此功能启用。

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

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

bun --bun which node # bun 二进制文件的路径
bun which node      # node 二进制文件的路径

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

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

设为 false 可禁用 node 符号链接。

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

设为 true 时，bun run 和 bun 不会打印正在运行的命令。

[run]
silent = true

如果不使用此选项，Bun 会将正在运行的命令打印到控制台：

bun run dev
echo "正在运行 \"dev\"..."

正在运行 "dev"...

使用此选项后，Bun 不会打印正在运行的命令：

bun run dev

正在运行 "dev"...

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

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

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

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

[run]
elide-lines = 10

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 环境变量。

[run]
noOrphans = true