Skip to main content

Documentation Index

Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

Bun 的行为可以通过其配置文件 bunfig.toml 进行配置。 一般来说,Bun 依赖于已有的配置文件,如 package.jsontsconfig.json 来配置其行为。bunfig.toml 仅在配置 Bun 特定内容时才需要。此文件是可选的,Bun 在没有它的情况下也能开箱即用。

全局 vs. 本地

通常建议在项目根目录下添加一个 bunfig.toml 文件,与 package.json 并列。 要进行全局配置,你也可以在以下路径之一创建 .bunfig.toml 文件:
  • $HOME/.bunfig.toml
  • $XDG_CONFIG_HOME/.bunfig.toml
如果同时检测到全局与本地的 bunfig,结果将进行浅合并,本地设置覆盖全局。在适用情况下,CLI 标志将覆盖 bunfig 设置。

运行时

Bun 的运行时行为通过 bunfig.toml 文件中的顶级字段进行配置。

preload

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

jsx

配置 Bun 如何处理 JSX。你也可以在 tsconfig.jsoncompilerOptions 中设置这些字段,但这里为了非 TypeScript 项目同样支持这些配置。
bunfig.toml
jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"
有关这些字段的更多信息,请参考 tsconfig 文档:

smol

启用 smol 模式。此模式会降低内存使用,但会牺牲性能。
bunfig.toml
# 降低内存使用,牺牲性能
smol = true

logLevel

设置日志级别。可以是 "debug""warn""error"
bunfig.toml
logLevel = "debug" # "debug" | "warn" | "error"

define

define 字段允许你用常量表达式替换特定的全局标识符。Bun 会将任何该标识符的使用替换为指定表达式。表达式应是 JSON 字符串。
bunfig.toml
[define]
# 将所有 "process.env.bagel" 的使用替换为字符串 `lox`
# 值会被解析为 JSON,但支持单引号字符串,且 `'undefined'` 在 JS 中表示 undefined。
# 未来版本可能改为普通的 TOML 格式,目前保留此用法是继承自 CLI 参数解析。
"process.env.bagel" = "'lox'"

loader

配置 Bun 如何将文件扩展名映射到加载器。适用于加载 Bun 本身不原生支持的文件。
bunfig.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 运行时长等信息。
bunfig.toml
telemetry = false

env

配置自动 .env 文件加载。默认情况下,Bun 会自动加载 .env 文件。如需禁用此行为:
bunfig.toml
# 禁用自动加载 .env 文件
env = false
也可以使用对象语法并设置 file 属性:
bunfig.toml
[env]
file = false
这在生产环境或 CI/CD 流水线中很有用,这类场景下通常只依赖系统环境变量。 注:即使禁用默认加载,通过 --env-file 明确指定的环境文件仍会被加载。

console

配置控制台输出行为。

console.depth

设置 console.log() 对象检测的默认深度。默认值为 2
bunfig.toml
[console]
depth = 3
此设置控制控制台输出中对象呈现的嵌套层数。值越高,显示的嵌套属性越多,但复杂对象时输出会较冗长。该设置可被 --console-depth CLI 标志覆盖。

Serve

Bun.servebun run 在提供 HTTP 服务时的选项配置在 [serve] 部分下。

serve.port

Bun.serve 监听的默认端口。默认 3000。也可以通过 BUN_PORTPORT 环境变量,或 --port 标志设置。
bunfig.toml
[serve]
port = 3000

测试运行器

测试运行器配置于 bunfig.toml[test] 部分。
bunfig.toml
[test]
# 在这里进行配置

test.root

运行测试的根目录。默认 .
bunfig.toml
[test]
root = "./__tests__"

test.preload

与顶级 preload 字段相同,但仅应用于 bun test
bunfig.toml
[test]
preload = ["./setup.ts"]

test.pathIgnorePatterns

使用 glob 模式从测试发现中排除文件和目录。匹配的目录在扫描过程中会被剪枝,因此其内容不会被遍历。当你的项目包含子模块或带有 *.test.ts 文件的 vendored 代码,而你不想让 bun test 检测到时,这非常有用。
bunfig.toml
[test]
pathIgnorePatterns = ["vendor/**", "submodules/**", "fixtures/**"]
等效 CLI 标志:--path-ignore-patterns。CLI 标志完全覆盖 bunfig.toml 的值。

test.smol

与顶级 smol 字段相同,但仅应用于 bun test
bunfig.toml
[test]
smol = true

test.coverage

启用覆盖率报告。默认 false。可以使用 --coverage 来覆盖。
bunfig.toml
[test]
coverage = false

test.coverageThreshold

指定覆盖率门槛。默认无门槛。如果测试覆盖率未达到此门槛,bun test 会以非零退出码表示失败。
bunfig.toml
[test]

# 要求做到 90% 的行级和函数级覆盖率
coverageThreshold = 0.9
也可分别为行覆盖、函数覆盖和语句覆盖设置不同门槛。
bunfig.toml
[test]
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }

test.coverageSkipTestFiles

计算覆盖率统计时是否跳过测试文件。默认 false
bunfig.toml
[test]
coverageSkipTestFiles = false

test.coverageIgnoreSourcemaps

是否报告转译后的输出覆盖率,而不是通过 sourcemaps 将行号映射回原始源码。默认 false。主要用于调试。
bunfig.toml
[test]
coverageIgnoreSourcemaps = false

test.coveragePathIgnorePatterns

使用 glob 模式排除特定文件或模式在覆盖率报告中的统计。可以是单个字符串,也可以是模式数组。
bunfig.toml
[test]
# 单个模式
coveragePathIgnorePatterns = "**/*.spec.ts"

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

test.coverageReporter

默认情况下,覆盖率报告会输出到控制台。为了 CI 环境中持久保存和供其他工具使用,请使用 lcov
bunfig.toml
[test]
coverageReporter  = ["text", "lcov"]  # 默认 ["text"]

test.coverageDir

设置覆盖率报告保存路径。仅对持久化的 coverageReporter(如 lcov)有效。
bunfig.toml
[test]
coverageDir = "path/to/somewhere"  # 默认 "coverage"

test.randomize

以随机顺序运行测试。默认 false
bunfig.toml
[test]
randomize = true
此功能有助于捕获测试间相互依赖导致的 Bug。配合 seed 使用,随机顺序可复现。 当指定 --randomize CLI 标志时,会覆盖此设置。

test.seed

设置测试随机化的随机种子。需要 randomizetrue
bunfig.toml
[test]
randomize = true
seed = 2444615283
设置种子可使随机测试顺序在多次运行中可复现,便于调试不稳定的测试。遇到失败时可用相同种子重现当时顺序。 --seed CLI 标志会覆盖此设置。

test.rerunEach

每个测试文件重复运行指定次数。默认 0(运行一次)。
bunfig.toml
[test]
rerunEach = 3
此功能有助于捕获不稳定或非确定性行为的测试。每个测试文件将被执行指定次数。 --rerun-each CLI 标志会覆盖此设置。

test.retry

所有测试的默认重试次数。失败的测试会被重试最多该次数。单个测试通过 { retry: N } 覆盖此值。默认 0(不重试)。
bunfig.toml
[test]
retry = 3
--retry CLI 标志会覆盖此设置。

test.concurrentTestGlob

指定一个 glob 模式,使匹配的测试文件自动启用并发执行。这些测试文件行为等同于使用了 --concurrent 标志,文件内所有测试将并发运行。
bunfig.toml
[test]
concurrentTestGlob = "**/concurrent-*.test.ts"
适用场景:
  • 逐步迁移测试套件至并发执行
  • 并发运行集成测试,同时单线程运行单元测试
  • 将快速并发测试与需要依序运行的测试分开
当指定 --concurrent CLI 标志时,会覆盖此设置。

test.onlyFailures

启用后,仅显示失败的测试结果,减少大型测试套件的输出噪声。默认 false
bunfig.toml
[test]
onlyFailures = true
等同于运行 bun test 时使用 --only-failures

test.reporter

配置测试报告器设置。

test.reporter.dots

启用点状报告器,输出紧凑模式,每个测试用点表示。默认 false
bunfig.toml
[test.reporter]
dots = true

test.reporter.junit

启用 JUnit XML 报告,并指定输出文件路径。
bunfig.toml
[test.reporter]
junit = "test-results.xml"
生成的 JUnit XML 可用于 CI 系统及其他工具。

包管理器

包管理是复杂的问题;为支持多种使用场景,bun install 的行为可在 [install] 部分配置。
bunfig.toml
[install]
# 这里进行配置

install.optional

是否安装可选依赖。默认 true
bunfig.toml
[install]
optional = true

install.dev

是否安装开发依赖。默认 true
bunfig.toml
[install]
dev = true

install.peer

是否安装 peer 依赖。默认 true
bunfig.toml
[install]
peer = true

install.production

bun install 是否以“生产模式”运行。默认 false 生产模式下,不安装 "devDependencies"。CLI 中可使用 --production 覆盖此设置。
bunfig.toml
[install]
production = false

install.exact

是否在 package.json 中设置精确版本号。默认 false 默认情况下,Bun 使用插入符号版本范围;例如包的最新版本为 2.4.1,则 package.json 中的版本范围是 ^2.4.1,表示接受 2.4.1 到(不含)3.0.0 之间的任意版本。
bunfig.toml
[install]
exact = false

install.ignoreScripts

安装期间是否跳过生命周期脚本。默认 false。等同于 --ignore-scripts 标志。 当为 true 时,Bun 不会运行任何 preinstall / install / postinstall / prepare 脚本——包括你的项目以及 trustedDependencies 中的包。更多详情请参见生命周期脚本
bunfig.toml
[install]
ignoreScripts = false

install.concurrentScripts

一次可并发运行的生命周期脚本最大数量。默认为 CPU 核心数的两倍。等同于 --concurrent-scripts 标志。
bunfig.toml
[install]
concurrentScripts = 5

install.saveTextLockfile

如果为 false,当执行 bun install 并且不存在锁文件时,会生成二进制格式的 bun.lockb,而非文本格式的 bun.lock 默认自 Bun v1.2 起为 true
bunfig.toml
[install]
saveTextLockfile = false

install.auto

配置 Bun 的包自动安装行为。默认 "auto" —— 如果未找到 node_modules 文件夹,Bun 会在执行时自动安装依赖。
bunfig.toml
[install]
auto = "auto"
有效值说明:
描述
"auto"如果存在本地 node_modules,则从中解析模块。否则,在执行时自动安装依赖。
"force"即使存在 node_modules,也总是自动安装依赖。
"disable"从不自动安装依赖。
"fallback"先检查本地 node_modules,对未找到的包自动安装。CLI 可用 bun -i 启用。

install.prefer

配置 Bun 在运行脚本时如何针对 npm 注册表解析包版本。默认 "online"
bunfig.toml
[install]
prefer = "online"
有效值:
描述
"online"默认。按需检查注册表中是否有过期包。
"offline"跳过过期检查,并从本地缓存解析包。等同于 --prefer-offline
"latest"始终向 npm 检查最新的匹配版本。等同于 --prefer-latest

install.frozenLockfile

为 true 时,bun install 不会更新 bun.lock。默认 false。如果 package.json 与现有 bun.lock 不匹配,则会报错。
bunfig.toml
[install]
frozenLockfile = false

install.dryRun

是否真正安装依赖。默认 false。为 true 则等同于所有 bun install 命令加上 --dry-run
bunfig.toml
[install]
dryRun = false

install.globalDir

配置全局安装包的存放目录。 环境变量:BUN_INSTALL_GLOBAL_DIR
bunfig.toml
[install]
# `bun install --global` 安装包的位置
globalDir = "~/.bun/install/global"

install.globalBinDir

配置全局安装的二进制文件和 CLI 的存放目录。 环境变量:BUN_INSTALL_BIN
bunfig.toml
[install]
# 全局安装包的二进制文件链接存放位置
globalBinDir = "~/.bun/bin"

install.registry

默认注册表为 https://registry.npmjs.org/。可在全局的 bunfig.toml 中配置:
bunfig.toml
[install]
# 以字符串形式设置默认注册表
registry = "https://registry.npmjs.org"
# 设置 token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# 设置用户名/密码
registry = "https://username:[email protected]"

install.linkWorkspacePackages

配置工作区(monorepo)包的链接方式。 是否将工作空间包从 monorepo 根目录链接到各自的 node_modules 目录。默认 true
bunfig.toml
[install]
linkWorkspacePackages = true

install.scopes

为特定作用域(如 @myorg/<package>)配置注册表,使用 install.scopes。可通过 $variable 引用环境变量。
bunfig.toml
[install.scopes]
# 字符串格式注册表
myorg = "https://username:[email protected]/"

# 带用户名/密码,支持引用环境变量
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

install.cainstall.cafile

配置 CA 证书,使用 install.cainstall.cafile 指定证书文件路径。
bunfig.toml
[install]
# CA 证书内容(字符串)
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

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

install.cache

配置缓存行为:
bunfig.toml
[install.cache]

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

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

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

install.lockfile

配置锁文件行为,使用 install.lockfile 部分。 是否在 bun install 时生成锁文件。默认 true
bunfig.toml
[install.lockfile]
save = true
是否在生成 bun.lock 之外,同时生成非 Bun 格式的锁文件。默认不生成。目前支持的取值只有 "yarn"
bunfig.toml
[install.lockfile]
print = "yarn"

install.linker

配置安装依赖的链接策略。新工作区默认 "isolated",新单包项目与现有项目(v1.3.2 以前版本)默认 "hoisted" 完整文档见 包管理 > 隔离安装
bunfig.toml
[install]
linker = "hoisted"
有效值:
描述
"hoisted"链接依赖到共享的 node_modules 目录。
"isolated"每个包安装内部各自链接依赖。

install.globalStore

When using the "isolated" linker, share package installations across projects in a global virtual store at <cache>/links/ and link node_modules/.bun/<pkg>@<ver> into it instead of materializing each package into the project. Makes warm installs after rm -rf node_modules an order of magnitude faster. Default false. Can also be set with the BUN_INSTALL_GLOBAL_STORE environment variable. 完整文档请参见包管理器 > 全局虚拟存储
bunfig.toml
[install]
globalStore = true

install.publicHoistPattern

在使用 "isolated" 链接器时,匹配这些 glob 模式的包会被提升到根 node_modules 目录,以便项目中的任何包都能解析它们。默认 []。类似于 pnpm 的 public-hoist-pattern
bunfig.toml
[install]
publicHoistPattern = ["*eslint*", "*prettier*"]

install.hoistPattern

在使用 "isolated" 链接器时,匹配这些 glob 模式的包会被提升到虚拟存储根目录(node_modules/.bun),以便虚拟存储中的其他包能够解析它们。默认 []。类似于 pnpm 的 hoist-pattern
bunfig.toml
[install]
hoistPattern = ["*"]

install.logLevel

设置 bun install 的日志级别。可以是 "debug""warn""error"
bunfig.toml
[install]
logLevel = "warn"

install.security.scanner

配置安全扫描器,在安装前扫描包中的安全漏洞。 首先,从 npm 安装安全扫描器:
terminal
bun add -d @acme/bun-security-scanner
然后在 bunfig.toml 配置:
bunfig.toml
[install.security]
scanner = "@acme/bun-security-scanner"
配置安全扫描器后:
  • 自动安装功能自动禁用以保障安全
  • 安装前扫描包
  • 发现致命问题时取消安装
  • 安装过程中显示安全警告
详细了解使用和编写安全扫描器

install.minimumReleaseAge

配置 npm 包版本的最小发布日期(秒)。在安装时,会过滤掉比此阈值更新的版本。默认 null(禁用)。
bunfig.toml
[install]
# 只安装至少 3 天前发布的包版本
minimumReleaseAge = 259200
更多详情见安装文档的最小发布年龄

install.minimumReleaseAgeExcludes

排除在 minimumReleaseAge 检查之外的包名数组。默认 []
bunfig.toml
[install]
minimumReleaseAge = 259200
# 这些包将绕过 3 天的最小发布时间要求
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

bun run

bun run 命令可在 [run] 部分配置。适用于 bun run 命令及使用 bun 命令运行文件、可执行程序或脚本时。 当前,bunfig.toml 只会自动加载本地项目中的配置(不会检查全局 .bunfig.toml)。

run.shell — 使用系统 shell 还是 Bun 的 shell

通过 bun runbun 运行 package.json 脚本时使用的 shell。Windows 默认 "bun",其他平台默认 "system" 如需始终使用系统 shell(非 Windows 上的默认行为):
bunfig.toml
[run]
# 非 Windows 的默认值
shell = "system"
如需始终使用 Bun 的 shell 而非系统 shell:
bunfig.toml
[run]
# Windows 的默认值
shell = "bun"

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

设为 true 时,会在所有由 bun runbun 调用的脚本或可执行文件的 $PATH 前添加一个指向 bun 二进制的 node 符号链接。 这意味着即使脚本内部调用 node,实际执行的也是 bun,无需修改脚本。此映射支持递归调用,对使用 node 的 shebang 同样生效。 默认情况下,如果 $PATH 中尚无 node,此功能启用。
bunfig.toml
[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 时禁用该功能。

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

设为 true 时,bun runbun 不会输出发送的命令信息。
bunfig.toml
[run]
silent = true
未启用该选项时,命令会打印如下内容:
terminal
bun run dev
echo "正在运行 \"dev\"..."
正在运行 "dev"...
启用该选项后,命令将不再打印:
bun run dev
正在运行 "dev"...
这等同于对所有 bun run 命令使用 --silent 参数:
bun --silent run dev
bun --silent dev
bun run --silent dev

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

使用 --filter 时,每个脚本显示的脚本输出行数。默认值为 10。设为 0 可显示全部行。等同于 --elide-lines 标志。
bunfig.toml
[run]
elide-lines = 10

run.noOrphans - 不留下孤儿进程

设为 true 时,Bun 会监视启动它的进程,并在该父进程消失后立即退出——即使父进程被 SIGKILL,也不会有机会转发信号。在退出时,Bun 还会递归地对其创建的所有后代进程发送 SIGKILL,确保它启动的进程不会比它活得更久。适用于 Bun 由某个监督程序(Electron、CI 运行器、轻量级 shim)启动,而该监督程序可能被强制终止的场景。 仅适用于 Linux 和 macOS(在 Windows 及其他平台上无效)。等同于 --no-orphans CLI 标志或 BUN_FEATURE_FLAG_NO_ORPHANS=1 环境变量。
bunfig.toml
[run]
noOrphans = true