bunfig.toml – 运行时 | Bun 文档

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`

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

# scripts to run before `bun run`-ing a file or script
# register plugins by adding them to this list
preload = ["./preload.ts"]

`jsx`

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

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

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

`smol`

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

# Reduce memory usage at the cost of performance
smol = true

`logLevel`

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

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

`define`

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

[define]
# Replace any usage of "process.env.bagel" with the string `lox`.
# The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS.
# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing.
"process.env.bagel" = "'lox'"

`loader`

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

[loader]
# when a .bagel file is imported, treat it like a tsx file
".bagel" = "tsx"

Bun 支持以下加载器

jsx
js
ts
tsx
css
file
json
toml
yaml
wasm
napi
base64
dataurl
text

`telemetry`

telemetry 字段允许启用/禁用分析记录。Bun 记录捆绑时间（以便我们可以用数据回答“Bun 是否变得更快？”）和功能使用情况（例如，“人们真的在使用宏吗？”）。请求正文大小约为 60 字节，因此数据量不大。默认情况下，遥测功能已启用。等同于 DO_NOT_TRACK 环境变量。

telemetry = false

`console`

配置控制台输出行为。

`console.depth`

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

[console]
depth = 3

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

测试运行器

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

[test]
# configuration goes here

`test.root`

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

[test]
root = "./__tests__"

`test.preload`

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

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

`test.smol`

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

[test]
smol = true

`test.coverage`

启用覆盖率报告。默认值 false。使用 --coverage 覆盖。

[test]
coverage = false

`test.coverageThreshold`

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

[test]

# to require 90% line-level and function-level coverage
coverageThreshold = 0.9

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

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

`test.coverageSkipTestFiles`

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

[test]
coverageSkipTestFiles = false

`test.coveragePathIgnorePatterns`

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

[test]
# Single pattern
coveragePathIgnorePatterns = "**/*.spec.ts"

# Multiple patterns
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

`test.coverageReporter`

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

[test]
coverageReporter  = ["text", "lcov"]  # default ["text"]

`test.coverageDir`

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

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

`test.concurrentTestGlob`

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

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

这对于以下情况很有用

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

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

`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 标志时将覆盖此设置。

包管理器

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

[install]
# configuration here

`install.optional`

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

[install]
optional = true

`install.dev`

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

[install]
dev = true

`install.peer`

是否安装对等依赖项。默认值 true。

[install]
peer = true

`install.production`

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

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

[install]
production = false

`install.exact`

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

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

[install]
exact = false

`install.saveTextLockfile`

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

默认值 true (自 Bun v1.2 起)。

[install]
saveTextLockfile = false

`install.auto`

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

[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 不一致，这将报错。

[install]
frozenLockfile = false

`install.dryRun`

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

[install]
dryRun = false

`install.globalDir`

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

环境变量：BUN_INSTALL_GLOBAL_DIR

[install]
# where `bun install --global` installs packages
globalDir = "~/.bun/install/global"

`install.globalBinDir`

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

环境变量：BUN_INSTALL_BIN

# where globally-installed package bins are linked
globalBinDir = "~/.bun/bin"

`install.registry`

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

[install]
# set default registry as a string
registry = "https://registry.npmjs.org"
# set a token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# set a username/password
registry = "https://username:password@registry.npmjs.org"

`install.linkWorkspacePackages`

要配置工作区包的链接方式，请使用 install.linkWorkspacePackages 选项。

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

[install]
linkWorkspacePackages = true

`install.scopes`

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

[install.scopes]
# registry as string
myorg = "https://username:password@registry.myorg.com/"

# registry with username/password
# you can reference environment variables
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

`install.ca` 和 `install.cafile`

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

[install]
# The CA certificate as a string
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# A path to a CA certificate file. The file can contain multiple certificates.
cafile = "path/to/cafile"

`install.cache`

配置缓存行为

[install.cache]

# the directory to use for the cache
dir = "~/.bun/install/cache"

# when true, don't load from the global cache.
# Bun may still write to node_modules/.cache
disable = false

# when true, always resolve the latest versions from the registry
disableManifest = false

`install.lockfile`

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

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

[install.lockfile]
save = true

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

[install.lockfile]
print = "yarn"

`install.security.scanner`

配置安全扫描器以在安装前扫描包是否存在漏洞。

首先，从 npm 安装一个安全扫描器

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

然后在您的 bunfig.toml 中配置它

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

当配置了安全扫描器时

为安全起见，自动安装会自动禁用
在安装前扫描包
如果发现严重问题，则取消安装
安装期间显示安全警告

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

`install.linker`

配置默认的链接器策略。默认值 "hoisted"。

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

[install]
linker = "hoisted"

有效值为

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

`install.minimumReleaseAge`

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

[install]
# Only install package versions published at least 3 days ago
minimumReleaseAge = 259200
# These packages will bypass the 3-day minimum age requirement
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

有关更多详细信息，请参阅安装文档中的最小发布时间。

`bun run`

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

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

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

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

始终使用系统 shell 而不是 Bun 的 shell（除 Windows 外的默认行为）

[run]
# default outside of Windows
shell = "system"

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

[run]
# default on Windows
shell = "bun"

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

当为 true 时，这会将一个指向 bun 二进制文件的 node 软链接添加到所有通过 bun run 或 bun 调用的脚本或可执行文件的 $PATH 前面。

这意味着，如果您有一个运行 node 的脚本，它实际上会运行 bun，而无需更改您的脚本。这会递归地工作，因此如果您的脚本运行另一个运行 node 的脚本，它也会运行 bun。这同样适用于 shebangs，因此如果您有一个 shebang 指向 node 的脚本，它实际上会运行 bun。

默认情况下，如果 node 尚未在您的 $PATH 中，则此功能已启用。

[run]
# equivalent to `bun --bun` for all `bun run` commands
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 正在运行的命令的输出。

[run]
silent = true

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

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