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 设置。

Runtime

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 文档。

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

 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 env 变量。

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

指定覆盖率阈值。默认情况下，不设置阈值。如果您的测试套件未达到或超过此阈值，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

包管理器

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

[install]
# configuration here

install.optional

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

[install]
optional = true

install.dev

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

[install]
dev = true

install.peer

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

[install]
peer = true

install.production

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

[install]
production = false

install.exect

是否在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"

有效值为：

Value价值	Description描述
"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:password@registry.npmjs.org"

install.scopes

要配置缓存行为，请执行以下操作：

[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.lockb始终会被创建)，目前仅支持“yarn”这一值。