bunfig.toml

Bun 的行为可以使用其配置文件 bunfig.toml 进行配置。

一般来说，Bun 依赖预先存在的配置文件（如 package.json 和 tsconfig.json）来配置其行为。bunfig.toml 仅在配置 Bun 特定的内容时才需要。此文件是可选的，Bun 无需此文件即可正常工作。

全局与本地

一般来说，建议将 bunfig.toml 文件添加到项目根目录，与 package.json 放在一起。

要全局配置 Bun，还可以在以下路径之一创建 .bunfig.toml 文件：

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

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

运行时

Bun 的运行时行为使用 bunfig.toml 文件中的顶层字段进行配置。

`preload`

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

toml

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

`jsx`

配置 Bun 如何处理 JSX。也可以在 tsconfig.json 的 compilerOptions 中设置这些字段，但它们也支持用于非 TypeScript 项目。

toml

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

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

`smol`

启用 smol 模式。这会以减少性能为代价来减少内存使用。

toml

# 以减少性能为代价来减少内存使用
smol = true

`logLevel`

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

toml

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

`define`

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

toml

[define]
# 将 "process.env.bagel" 的任何使用替换为字符串 `lox`。
# 值被解析为 JSON，除了支持单引号字符串，并且 `'undefined'` 在 JS 中变为 `undefined`。
# 这可能会在未来的版本中改为普通的 TOML。这是 CLI 参数解析的遗留问题。
"process.env.bagel" = "'lox'"

`loader`

配置 Bun 如何将文件扩展名映射到加载器。这对于加载 Bun 不原生支持的文件很有用。

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 耗时多长等信息。

toml

telemetry = false

`console`

配置控制台输出行为。

`console.depth`

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

toml

[console]
depth = 3

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

测试运行器

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

toml

[test]
# 配置放在这里

`test.root`

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

toml

[test]
root = "./__tests__"

`test.preload`

与顶层 preload 字段相同，但仅适用于 bun test。

toml

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

`test.smol`

与顶层 smol 字段相同，但仅适用于 bun test。

toml

[test]
smol = true

`test.coverage`

启用覆盖率分析。默认值为 false。使用 --coverage 覆盖。

toml

[test]
coverage = false

`test.coverageThreshold`

指定覆盖率阈值。默认情况下，不设置阈值。如果你的测试套件未达到或超过此阈值，bun test 将以非零退出代码退出以指示失败。

toml

[test]

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

可以为行级、函数级和语句级覆盖率指定不同的阈值。

toml

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

`test.coverageSkipTestFiles`

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

toml

[test]
coverageSkipTestFiles = false

`test.coveragePathIgnorePatterns`

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

toml

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

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

`test.coverageReporter`

默认情况下，覆盖率报告将打印到控制台。对于 CI 环境和其他工具中的持久覆盖率报告，使用 lcov。

toml

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

`test.coverageDir`

设置保存覆盖率报告的路径。请注意，它仅适用于持久 coverageReporter（如 lcov）。

toml

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

`test.randomize`

按随机顺序运行测试。默认值为 false。

toml

[test]
randomize = true

这有助于通过每次以不同顺序运行测试来捕获与测试相互依赖性相关的错误。与 seed 结合使用时，随机顺序变得可重现。

--randomize CLI 标志在指定时将覆盖此设置。

`test.seed`

设置测试随机化的随机种子。此选项要求 randomize 为 true。

toml

[test]
randomize = true
seed = 2444615283

使用种子使随机测试顺序在多次运行中可重现，这对于调试不稳定测试很有用。当遇到启用随机化的测试失败时，你可以使用相同的种子重现确切的测试顺序。

--seed CLI 标志在指定时将覆盖此设置。

`test.rerunEach`

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

toml

[test]
rerunEach = 3

这对于捕获不稳定测试或非确定性行为很有用。每个测试文件将执行指定次数。

--rerun-each CLI 标志在指定时将覆盖此设置。

`test.concurrentTestGlob`

指定 glob 模式以自动运行匹配的测试文件并启用并发测试执行。匹配此模式的测试文件将表现得好像传递了 --concurrent 标志，并发运行这些文件中的所有测试。

toml

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

这对于以下情况很有用：

逐渐将测试套件迁移到并发执行
并发运行集成测试同时保持单元测试顺序执行
将快速并发测试与需要顺序执行的测试分开

--concurrent CLI 标志在指定时将覆盖此设置。

`test.onlyFailures`

启用时，输出中仅显示失败的测试。这有助于通过隐藏通过的测试来减少大型测试套件中的噪音。默认值为 false。

toml

[test]
onlyFailures = true

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

`test.reporter`

配置测试报告器设置。

`test.reporter.dots`

启用 dots 报告器，显示紧凑输出，每个测试显示一个点。默认值为 false。

toml

[test.reporter]
dots = true

`test.reporter.junit`

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

toml

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

这会生成可由 CI 系统和其他工具使用的 JUnit XML 报告。

包管理器

包管理是一个复杂的问题；为了支持一系列用例，bun install 的行为可以在 [install] 部分下配置。

toml

[install]
# 配置放在这里

`install.optional`

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

toml

[install]
optional = true

`install.dev`

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

toml

[install]
dev = true

`install.peer`

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

toml

[install]
peer = true

`install.production`

bun install 是否以"生产模式"运行。默认值为 false。

在生产模式下，不安装 "devDependencies"。你可以在 CLI 中使用 --production 覆盖此设置。

toml

[install]
production = false

`install.exact`

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

默认情况下，Bun 使用插入符号范围；如果包的 latest 版本是 2.4.1，则 package.json 中的版本范围将是 ^2.4.1。这表示从 2.4.1 到（但不包括）3.0.0 的任何版本都是可接受的。

toml

[install]
exact = false

`install.saveTextLockfile`

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

默认值为 true（自 Bun v1.2 起）。

toml

[install]
saveTextLockfile = false

`install.auto`

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

toml

[install]
auto = "auto"

有效值为：

值	描述
`"auto"`	如果存在本地 `node_modules` 则从中解析模块。否则，自动安装依赖。
`"force"`	始终自动安装依赖，即使 `node_modules` 存在。
`"disable"`	从不自动安装依赖。
`"fallback"`	首先检查本地 `node_modules`，然后自动安装任何未找到的包。你可以使用 `bun -i` 从 CLI 启用此功能。

`install.frozenLockfile`

当为 true 时，bun install 不会更新 bun.lock。默认值为 false。如果 package.json 和现有 bun.lock 不一致，这将报错。

toml

[install]
frozenLockfile = false

`install.dryRun`

bun install 是否实际安装依赖。默认值为 false。当为 true 时，等同于在所有 bun install 命令上设置 --dry-run。

toml

[install]
dryRun = false

`install.globalDir`

配置 Bun 放置全局安装包的目录。

环境变量：BUN_INSTALL_GLOBAL_DIR

toml

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

`install.globalBinDir`

配置 Bun 安装全局安装的二进制文件和 CLI 的目录。

环境变量：BUN_INSTALL_BIN

toml

[install]
# 全局安装包 bins 链接的位置
globalBinDir = "~/.bun/bin"

`install.registry`

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

toml

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

`install.linkWorkspacePackages`

要配置工作空间包如何链接，使用 install.linkWorkspacePackages 选项。

是否将工作空间包从 monorepo 根目录链接到它们各自的 node_modules 目录。默认值为 true。

toml

[install]
linkWorkspacePackages = true

`install.scopes`

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

toml

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

# 带用户名/密码的注册表
# 你可以引用环境变量
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# 带令牌的注册表
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

`install.ca` 和 `install.cafile`

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

toml

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

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

`install.cache`

配置缓存行为：

toml

[install.cache]

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

# 当为 true 时，不从全局缓存加载。
# Bun 可能仍然写入 node_modules/.cache
disable = false

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

`install.lockfile`

要配置锁文件行为，使用 install.lockfile 部分。

bun install 时是否生成锁文件。默认值为 true。

toml

[install.lockfile]
save = true

是否在 bun.lock 旁边生成非 Bun 锁文件。（始终会创建 bun.lock。）目前 "yarn" 是唯一支持的值。

toml

[install.lockfile]
print = "yarn"

`install.linker`

配置安装依赖的链接器策略。对于新工作空间默认为 "isolated"，对于新单包项目和现有项目（v1.3.2 之前创建）默认为 "hoisted"。

完整文档请参阅包管理器 > 隔离安装。

toml

[install]
linker = "hoisted"

有效值为：

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

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 安装安全扫描器：

bash

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

然后在 bunfig.toml 中配置它：

toml

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

当配置安全扫描器时：

自动禁用自动安装以确保安全
包在安装前被扫描
如果发现致命问题，安装被取消
安装期间显示安全警告

了解有关使用安全扫描器的更多信息。

`install.minimumReleaseAge`

配置 npm 包版本的最小年龄（以秒为单位）。比此阈值最近发布的包版本将在安装期间被过滤掉。默认值为 null（禁用）。

toml

[install]
# 仅安装至少 3 天前发布的包版本
minimumReleaseAge = 259200
# 这些包将绕过 3 天最小年龄要求
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

有关详细信息，请参阅安装文档中的最小发布年龄。

`bun run`

bun run 命令可以在 [run] 部分下配置。这些适用于 bun run 命令和运行可执行文件或脚本时的 bun 命令。

目前，bunfig.toml 仅在本地项目的 bun run 中自动加载（它不检查全局 .bunfig.toml）。

`run.shell` - 使用系统 shell 或 Bun 的 shell

通过 bun run 或 bun 运行 package.json 脚本时使用的 shell。在 Windows 上，默认为 "bun"，在其他平台上默认为 "system"。

要始终使用系统 shell 而不是 Bun 的 shell（除非 Windows 否则为默认行为）：

toml

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

要始终使用 Bun 的 shell 而不是系统 shell：

toml

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

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

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

这意味着如果你有一个运行 node 的脚本，它实际上将运行 bun，而无需更改脚本。这是递归工作的，所以如果你的脚本运行另一个运行 node 的脚本，它也将运行 bun。这也适用于 shebang，所以如果你有一个指向 node 的 shebang 脚本，它实际上将运行 bun。

默认情况下，如果你的 $PATH 中还没有 node，则启用此功能。

toml

[run]
# 等同于对所有 `bun run` 命令使用 `bun --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，这将禁用 node 符号链接。

`run.silent` - 抑制报告正在运行的命令

当为 true 时，抑制 bun run 或 bun 运行的命令输出。

toml

[run]
silent = true

没有此选项时，运行的命令将打印到控制台：

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

txt

Running "dev"...

使用此选项时，运行的命令将不会打印到控制台：

bun run dev

txt

Running "dev"...

这等同于将 --silent 传递给所有 bun run 命令：

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

全局与本地 ​

运行时 ​

preload ​

jsx ​

smol ​

logLevel ​

define ​

loader ​

telemetry ​

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 - 抑制报告正在运行的命令 ​

全局与本地

运行时

`preload`

`jsx`

`smol`

`logLevel`

`define`

`loader`

`telemetry`

`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` - 抑制报告正在运行的命令