bunfig.toml – 运行时 | Bun 文档

可以通过配置文件 `bunfig.toml` 来配置 Bun 的行为。

通常情况下，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
wasm
napi
base64
dataurl
text

`telemetry`

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

telemetry = false

测试运行器

测试运行器在 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

包管理器

包管理是一个复杂的问题；为了支持一系列用例，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.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.lockb。默认值为 false。如果 package.json 和现有的 bun.lockb 不一致，这将出错。

[install]
frozenLockfile = false

`install.dryRun`

bun install 是否会实际安装依赖项。默认值为 false。如果为 true，则相当于在所有 bun install 命令上设置 --dry-run。

[install]
dryRun = false

`install.globalDir`

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

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

`install.globalBinDir`

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

# 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:[email protected]"

`install.scopes`

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

[install.scopes]
# registry as string
myorg = "https://username:[email protected]/"

# 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.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.lockb 旁边生成非 Bun 锁定文件。（始终会创建 bun.lockb。）目前 "yarn" 是唯一受支持的值。

[install.lockfile]
print = "yarn"

`bun run`

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

目前，bunfig.toml 并不总是自动加载到本地项目的 bun run 中（它确实会检查全局 bunfig.toml），因此您可能仍需要传递 -c 或 -c=bunfig.toml 来使用这些设置。

`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 时，这会在 $PATH 前面加上一个 node 符号链接，该符号链接指向 bun 二进制文件，用于 bun run 或 bun 调用的所有脚本或可执行文件。

这意味着，如果你有一个运行 node 的脚本，它实际上将运行 bun，而无需更改你的脚本。这是递归工作的，因此如果你的脚本运行另一个运行 node 的脚本，它也将运行 bun。这也适用于 shebang，因此如果你有一个指向 node 的 shebang 的脚本，它实际上将运行 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"...

这相当于将 --silent 传递给所有 bun run 命令

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