bunfig.toml 是 Bun 的配置文件。
Bun 会尽可能使用现有的配置文件,例如 package.json 和 tsconfig.json;bunfig.toml 仅用于 Bun 特有的设置。该文件是可选的,即使没有它,Bun 也能正常工作。
全局 vs. 本地
将bunfig.toml 放在项目根目录中,与 package.json 放在一起。
若要进行全局配置,你也可以在以下路径之一创建 .bunfig.toml 文件:
$HOME/.bunfig.toml$XDG_CONFIG_HOME/.bunfig.toml
bunfig,它会对两者进行浅合并,本地配置会覆盖全局配置。在适用的情况下,CLI 标志会覆盖 bunfig 设置。
运行时
顶层字段用于配置 Bun 的运行时行为。preload
一个脚本/插件数组,在运行文件或脚本前执行。
bunfig.toml
jsx
配置 Bun 处理 JSX 的方式。你也可以在 tsconfig.json 的 compilerOptions 中设置这些字段,但 bunfig.toml 支持在非 TypeScript 项目中使用它们。
bunfig.toml
smol
启用 smol 模式。此模式会降低内存使用,但会牺牲性能。
bunfig.toml
logLevel
设置日志级别:"debug"、"warn" 或 "error"。
bunfig.toml
define
define 字段会将全局标识符替换为常量表达式,无论它们出现在哪里。该表达式应为 JSON 字符串。
bunfig.toml
loader
配置 Bun 将文件扩展名映射到加载器的方式。使用此配置可以加载 Bun 原生不支持的文件类型。
bunfig.toml
jsxjststsxcssfilejsontomlwasmnapibase64dataurltext
telemetry
telemetry 字段用于启用或禁用分析功能。默认情况下,分析功能处于启用状态。它等同于 DO_NOT_TRACK 环境变量。
我们目前不会收集分析数据;此设置仅控制匿名崩溃报告。我们计划收集诸如哪些 Bun API 使用最频繁、或 bun build 花费多长时间等信息。
bunfig.toml
env
配置自动加载 .env 文件的行为。Bun 默认会加载 .env 文件。要禁用此行为:
bunfig.toml
file 属性:
bunfig.toml
--env-file 显式传入的文件仍会被加载。
console
配置控制台输出行为。
console.depth
设置 console.log() 对象检测的默认深度。默认值为 2。
bunfig.toml
--console-depth CLI 标志会覆盖此设置。
服务
[serve] 部分用于配置 Bun.serve 和提供 HTTP 服务时的 bun run。
serve.port
Bun.serve 监听的默认端口。默认为 3000。也可以通过 BUN_PORT 或 PORT 环境变量,或 --port 标志进行设置。
bunfig.toml
测试运行器
bunfig.toml 的 [test] 部分用于配置测试运行器。
bunfig.toml
test.root
运行测试的根目录。默认 .。
bunfig.toml
test.preload
与顶级 preload 字段相同,但仅应用于 bun test。
bunfig.toml
test.pathIgnorePatterns
使用 glob 模式从测试发现中排除文件和目录。匹配的目录会在扫描期间被裁剪,因此不会遍历其内容。当项目包含带有 *.test.ts 文件、但不希望被 bun test 发现的子模块或第三方代码时,可以使用此配置。
bunfig.toml
--path-ignore-patterns。CLI 标志完全覆盖 bunfig.toml 的值。
test.smol
与顶级 smol 字段相同,但仅应用于 bun test。
bunfig.toml
test.coverage
启用覆盖率报告。默认 false。可以使用 --coverage 来覆盖。
bunfig.toml
test.coverageThreshold
覆盖率阈值。默认不设置阈值。如果测试套件未达到该阈值,bun test 将以非零退出代码退出。
bunfig.toml
bunfig.toml
test.coverageSkipTestFiles
计算覆盖率统计时是否跳过测试文件。默认 false。
bunfig.toml
test.coverageIgnoreSourcemaps
是否报告转译后的输出覆盖率,而不是通过 sourcemaps 将行号映射回原始源码。默认 false。主要用于调试。
bunfig.toml
test.coveragePathIgnorePatterns
使用 glob 模式从覆盖率报告中排除文件。可以接受单个模式或模式数组。
bunfig.toml
test.coverageReporter
默认情况下,覆盖率报告会打印到控制台。若要生成 CI 和其他工具可以读取的持久化报告,请使用 lcov。
bunfig.toml
test.coverageDir
设置保存覆盖率报告的路径。此配置仅适用于 lcov 等持久化报告器。
bunfig.toml
test.randomize
以随机顺序运行测试。默认 false。
bunfig.toml
seed 结合使用时,随机顺序可以复现。
--randomize CLI 标志会覆盖此设置。
test.seed
设置测试随机化的随机种子。需要 randomize 为 true。
bunfig.toml
--seed CLI 标志会覆盖此设置。
test.rerunEach
每个测试文件重复运行指定次数。默认 0(运行一次)。
bunfig.toml
--rerun-each CLI 标志会覆盖此设置。
test.retry
所有测试的默认重试次数。失败的测试最多会重试指定次数。每个测试中的 { retry: N } 会覆盖此值。默认 0(不重试)。
bunfig.toml
--retry CLI 标志会覆盖此设置。
test.concurrentTestGlob
匹配此 glob 模式的测试文件将并发运行其中的所有测试,就像传入了 --concurrent 标志一样。
bunfig.toml
--concurrent CLI 标志会覆盖此设置。
test.onlyFailures
启用后,输出中只会显示失败的测试,从而减少大型测试套件中的噪音。默认 false。
bunfig.toml
--only-failures 标志。
test.reporter
配置测试报告器设置。
test.reporter.dots
启用点号报告器,每个测试打印一个点。默认 false。
bunfig.toml
test.reporter.junit
启用 JUnit XML 报告,并指定输出文件路径。
bunfig.toml
包管理器
[install] 部分配置 bun install 的行为。
bunfig.toml
install.optional
是否安装可选依赖。默认 true。
bunfig.toml
install.dev
是否安装开发依赖。默认 true。
bunfig.toml
install.peer
是否安装 peer 依赖。默认 true。
bunfig.toml
install.production
是否让 bun install 在“生产模式”下运行。默认 false。
在生产模式下,不会安装 "devDependencies"。--production CLI 标志会覆盖此设置。
bunfig.toml
install.exact
是否在 package.json 中设置精确版本号。默认 false。
默认情况下,Bun 使用插入符号范围;如果某个包的 latest 版本是 2.4.1,Bun 会将 ^2.4.1 写入你的 package.json,这表示接受从 2.4.1 到(但不包括)3.0.0 的任何版本。
bunfig.toml
install.ignoreScripts
安装期间是否跳过生命周期脚本。默认 false。等同于 --ignore-scripts 标志。
当设置为 true 时,Bun 不会运行任何 preinstall / install / postinstall / prepare 脚本,包括项目中的脚本和 trustedDependencies 中包的脚本。请参阅生命周期脚本。
bunfig.toml
install.concurrentScripts
一次可并发运行的生命周期脚本最大数量。默认为 CPU 核心数的两倍。等同于 --concurrent-scripts 标志。
bunfig.toml
install.saveTextLockfile
如果为 false,当不存在锁文件时,bun install 会生成二进制 bun.lockb,而不是基于文本的 bun.lock 文件。
默认自 Bun v1.2 起为 true。
bunfig.toml
install.auto
配置 Bun 的自动安装行为。默认值为 "auto"——找不到 node_modules 文件夹时,Bun 会在执行期间即时安装依赖。
bunfig.toml
install.prefer
配置 Bun 在运行脚本时如何针对 npm 注册表解析包版本。默认 "online"。
bunfig.toml
install.frozenLockfile
当设置为 true 时,bun install 不会更新 bun.lock。默认 false。如果 package.json 与现有的 bun.lock 不一致,安装会报错。
bunfig.toml
install.dryRun
是否实际安装依赖。默认 false。当设置为 true 时,等同于向所有 bun install 命令传入 --dry-run。
bunfig.toml
install.globalDir
Bun 存放全局安装包的目录。
环境变量:BUN_INSTALL_GLOBAL_DIR
bunfig.toml
install.globalBinDir
Bun 链接全局安装包二进制文件的目录。
环境变量:BUN_INSTALL_BIN
bunfig.toml
install.registry
默认注册表为 https://registry.npmjs.org/。如需更改:
bunfig.toml
install.linkWorkspacePackages
是否将工作区包从 monorepo 根目录链接到各自的 node_modules 目录。默认 true。
bunfig.toml
install.scopes
如需为特定作用域(例如 @myorg/<package>)配置注册表,请使用 install.scopes。你可以使用 $variable 语法引用环境变量。
bunfig.toml
install.ca 和 install.cafile
如需配置 CA 证书,请将 install.ca 设置为证书字符串,或将 install.cafile 设置为证书文件的路径。
bunfig.toml
install.cache
配置缓存行为:
bunfig.toml
install.lockfile
是否在执行 bun install 时生成锁文件。默认 true。
bunfig.toml
bun.lock 旁边生成非 Bun 锁文件。(始终会创建 bun.lock。)唯一支持的值是 "yarn"。
bunfig.toml
install.linker
配置链接器策略:即 bun install 如何在 node_modules 中组织依赖。对于新的工作区,默认为 "isolated";对于新的单包项目和现有项目(在 v1.3.2 之前创建),默认为 "hoisted"。
请参阅隔离安装。
bunfig.toml
install.globalStore
当使用 "isolated" 链接器时,会在全局虚拟存储 <cache>/links/ 中跨项目共享包安装,并将 node_modules/.bun/<pkg>@<ver> 链接到其中,而不是将每个包实际展开到项目中。这样在 rm -rf node_modules 之后的热安装会快一个数量级。默认 false。也可以通过 BUN_INSTALL_GLOBAL_STORE 环境变量设置。
请参阅全局虚拟存储。
bunfig.toml
install.publicHoistPattern
在使用 "isolated" 链接器时,匹配这些 glob 模式的包会被提升到根 node_modules 目录,以便项目中的任何包都能解析它们。默认 []。类似于 pnpm 的 public-hoist-pattern。
bunfig.toml
install.hoistPattern
在使用 "isolated" 链接器时,匹配这些 glob 模式的包会被提升到虚拟存储根目录(node_modules/.bun),以便虚拟存储中的其他包能够解析它们。默认 []。类似于 pnpm 的 hoist-pattern。
bunfig.toml
install.logLevel
设置 bun install 的日志级别。可以是 "debug"、"warn" 或 "error"。
bunfig.toml
install.security.scanner
配置安全扫描器,在安装前扫描包中的安全漏洞。
首先,从 npm 安装安全扫描器:
terminal
@oven/bun-security-scanner 是一个示例包名,不是真实存在的包。请将其替换为你要使用的扫描器,并查阅该扫描器的文档以获取准确的包名和安装说明。大多数扫描器都可通过 bun add 安装。bunfig.toml 中进行配置:
bunfig.toml
- 自动安装功能会自动禁用,以保障安全
- 安装前扫描包
- 发现严重问题时取消安装
- 安装过程中显示安全警告
install.minimumReleaseAge
配置 npm 包版本的最短存续时间(以秒为单位)。发布距今短于此阈值的包版本会在安装期间被过滤。默认 null(禁用)。
bunfig.toml
install.minimumReleaseAgeExcludes
排除在 minimumReleaseAge 检查之外的包名数组。默认 []。
bunfig.toml
bun run
[run] 部分用于配置 bun run 命令。这些设置也适用于运行文件、脚本或可执行文件时使用的 bun 命令。
对于 bun run,Bun 只会自动加载本地项目的 bunfig.toml(不会检查全局 .bunfig.toml)。
run.shell — 使用系统 shell 还是 Bun 的 shell
使用 bun run 或 bun 运行 package.json 脚本时所使用的 shell。在 Windows 上默认为 "bun",在其他平台上默认为 "system"。
如需始终使用系统 shell 而非 Bun 的 shell(除 Windows 外所有平台上的默认设置):
bunfig.toml
bunfig.toml
run.bun — 自动将 node 别名为 bun
设为 true 时,会在所有由 bun run 或 bun 调用的脚本或可执行文件的 $PATH 前添加一个指向 bun 二进制的 node 符号链接。
运行 node 的脚本会改为运行 bun,无需修改脚本。此功能支持递归生效,因此运行另一个脚本且该脚本又运行 node 时,也会运行 bun;指向 node 的 shebang 同样适用。
默认情况下,如果 $PATH 中尚无 node,此功能启用。
bunfig.toml
bun run 命令加上 --bun 参数:
false 可禁用 node 符号链接。
run.silent — 静默运行,不输出命令提示
设为 true 时,bun run 和 bun 不会打印正在运行的命令。
bunfig.toml
terminal
bun run 命令使用 --silent 参数:
run.elide-lines - 截断过滤后的输出
使用 --filter 时,每个脚本显示的脚本输出行数。默认值为 10。设为 0 可显示全部行。等同于 --elide-lines 标志。
bunfig.toml
run.noOrphans - 不留下孤儿进程
设为 true 时,Bun 会监视启动它的进程,并在该父进程消失后立即退出,即使父进程被强制终止而来不及转发信号。当 Bun 自身退出时,也会终止所有后代进程,以确保它启动的进程不会继续运行。适用于由可能被强制终止的监控程序(Electron、CI 运行器或轻量级 shim)启动 Bun 的情况。
在 Linux 上,此功能使用 prctl(PR_SET_PDEATHSIG) 和 /proc 后代进程遍历;在 macOS 上,使用事件循环的 kqueue 中的 EVFILT_PROC/NOTE_EXIT 和 libproc 后代进程遍历;在 Windows 上,使用针对父进程句柄的线程池等待以及关闭时终止进程的 Job Object。
等同于 --no-orphans CLI 标志或 BUN_FEATURE_FLAG_NO_ORPHANS=1 环境变量。
bunfig.toml