bunfig.toml

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`

在運行文件或腳本之前要執行的腳本/插件數組。

toml

# 在 `bun run` 文件或腳本之前運行的腳本
# 通過將插件添加到此列表來注冊插件
preload = ["./preload.ts"]

`jsx`

配置 Bun 如何處理 JSX。也可以在 tsconfig.json 的 compilerOptions 中設置這些字段，但它們也支持用於非 TypeScript 項目。

toml

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

有關這些字段的更多信息，請參閱 tsconfig 文檔。

`smol`

啟用 smol 模式。這會以減少性能為代價來減少內存使用。

toml

# 以減少性能為代價來減少內存使用
smol = true

`logLevel`

設置日志級別。這可以是 "debug"、"warn" 或 "error" 之一。

toml

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

`define`

define 字段允許你用常量表達式替換某些全局標識符。Bun 將替換標識符的任何使用為表達式。表達式應該是 JSON 字符串。

toml

[define]
# 將 "process.env.bagel" 的任何使用替換為字符串 `lox`。
# 值被解析為 JSON，除了支持單引號字符串，並且 `'undefined'` 在 JS 中變為 `undefined`。
# 這可能會在未來的版本中改為普通的 TOML。這是 CLI 參數解析的遺留問題。
"process.env.bagel" = "'lox'"

`loader`

配置 Bun 如何將文件擴展名映射到加載器。這對於加載 Bun 不原生支持的文件很有用。

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 耗時多長等信息。

toml

telemetry = false

`console`

配置控制台輸出行為。

`console.depth`

設置 console.log() 對象檢查的默認深度。默認值為 2。

toml

[console]
depth = 3

這控制控制台輸出中顯示對象的嵌套深度。較高的值顯示更多嵌套屬性，但對於復雜對象可能會產生冗長的輸出。此設置可以通過 --console-depth CLI 標志覆蓋。

測試運行器

測試運行器在 bunfig.toml 的 [test] 部分下配置。

toml

[test]
# 配置放在這裡

`test.root`

運行測試的根目錄。默認值為 .。

toml

[test]
root = "./__tests__"

`test.preload`

與頂層 preload 字段相同，但僅適用於 bun test。

toml

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

`test.smol`

與頂層 smol 字段相同，但僅適用於 bun test。

toml

[test]
smol = true

`test.coverage`

啟用覆蓋率分析。默認值為 false。使用 --coverage 覆蓋。

toml

[test]
coverage = false

`test.coverageThreshold`

指定覆蓋率閾值。默認情況下，不設置閾值。如果你的測試套件未達到或超過此閾值，bun test 將以非零退出代碼退出以指示失敗。

toml

[test]

# 要求 90% 的行級和函數級覆蓋率
coverageThreshold = 0.9

可以為行級、函數級和語句級覆蓋率指定不同的閾值。

toml

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

`test.coverageSkipTestFiles`

計算覆蓋率統計時是否跳過測試文件。默認值為 false。

toml

[test]
coverageSkipTestFiles = false

`test.coveragePathIgnorePatterns`

使用 glob 模式從覆蓋率報告中排除特定文件或文件模式。可以是單個字符串模式或模式數組。

toml

[test]
# 單個模式
coveragePathIgnorePatterns = "**/*.spec.ts"

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

`test.coverageReporter`

默認情況下，覆蓋率報告將打印到控制台。對於 CI 環境和其他工具中的持久覆蓋率報告，使用 lcov。

toml

[test]
coverageReporter  = ["text", "lcov"]  # 默認 ["text"]

`test.coverageDir`

設置保存覆蓋率報告的路徑。請注意，它僅適用於持久 coverageReporter（如 lcov）。

toml

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

`test.randomize`

按隨機順序運行測試。默認值為 false。

toml

[test]
randomize = true

這有助於通過每次以不同順序運行測試來捕獲與測試相互依賴性相關的錯誤。與 seed 結合使用時，隨機順序變得可重現。

--randomize CLI 標志在指定時將覆蓋此設置。

`test.seed`

設置測試隨機化的隨機種子。此選項要求 randomize 為 true。

toml

[test]
randomize = true
seed = 2444615283

使用種子使隨機測試順序在多次運行中可重現，這對於調試不穩定測試很有用。當遇到啟用隨機化的測試失敗時，你可以使用相同的種子重現確切的測試順序。

--seed CLI 標志在指定時將覆蓋此設置。

`test.rerunEach`

將每個測試文件重新運行指定次數。默認值為 0（運行一次）。

toml

[test]
rerunEach = 3

這對於捕獲不穩定測試或非確定性行為很有用。每個測試文件將執行指定次數。

--rerun-each CLI 標志在指定時將覆蓋此設置。

`test.concurrentTestGlob`

指定 glob 模式以自動運行匹配的測試文件並啟用並發測試執行。匹配此模式的測試文件將表現得好像傳遞了 --concurrent 標志，並發運行這些文件中的所有測試。

toml

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

這對於以下情況很有用：

逐漸將測試套件遷移到並發執行
並發運行集成測試同時保持單元測試順序執行
將快速並發測試與需要順序執行的測試分開

--concurrent CLI 標志在指定時將覆蓋此設置。

`test.onlyFailures`

啟用時，輸出中僅顯示失敗的測試。這有助於通過隱藏通過的測試來減少大型測試套件中的噪音。默認值為 false。

toml

[test]
onlyFailures = true

這等同於運行 bun test 時使用 --only-failures 標志。

`test.reporter`

配置測試報告器設置。

`test.reporter.dots`

啟用 dots 報告器，顯示緊湊輸出，每個測試顯示一個點。默認值為 false。

toml

[test.reporter]
dots = true

`test.reporter.junit`

啟用 JUnit XML 報告並指定輸出文件路徑。

toml

[test.reporter]
junit = "test-results.xml"

這會生成可由 CI 系統和其他工具使用的 JUnit XML 報告。

包管理器

包管理是一個復雜的問題；為了支持一系列用例，bun install 的行為可以在 [install] 部分下配置。

toml

[install]
# 配置放在這裡

`install.optional`

是否安裝可選依賴。默認值為 true。

toml

[install]
optional = true

`install.dev`

是否安裝開發依賴。默認值為 true。

toml

[install]
dev = true

`install.peer`

是否安裝 peer 依賴。默認值為 true。

toml

[install]
peer = true

`install.production`

bun install 是否以"生產模式"運行。默認值為 false。

在生產模式下，不安裝 "devDependencies"。你可以在 CLI 中使用 --production 覆蓋此設置。

toml

[install]
production = false

`install.exact`

是否在 package.json 中設置精確版本。默認值為 false。

默認情況下，Bun 使用插入符號范圍；如果包的 latest 版本是 2.4.1，則 package.json 中的版本范圍將是 ^2.4.1。這表示從 2.4.1 到（但不包括）3.0.0 的任何版本都是可接受的。

toml

[install]
exact = false

`install.saveTextLockfile`

如果為 false，運行 bun install 且不存在鎖文件時，生成二進制 bun.lockb 而不是基於文本的 bun.lock 文件。

默認值為 true（自 Bun v1.2 起）。

toml

[install]
saveTextLockfile = false

`install.auto`

配置 Bun 的包自動安裝行為。默認值為 "auto" — 當找不到 node_modules 文件夾時，Bun 將在執行期間自動安裝依賴。

toml

[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 不一致，這將報錯。

toml

[install]
frozenLockfile = false

`install.dryRun`

bun install 是否實際安裝依賴。默認值為 false。當為 true 時，等同於在所有 bun install 命令上設置 --dry-run。

toml

[install]
dryRun = false

`install.globalDir`

配置 Bun 放置全局安裝包的目錄。

環境變量：BUN_INSTALL_GLOBAL_DIR

toml

[install]
# `bun install --global` 安裝包的位置
globalDir = "~/.bun/install/global"

`install.globalBinDir`

配置 Bun 安裝全局安裝的二進制文件和 CLI 的目錄。

環境變量：BUN_INSTALL_BIN

toml

[install]
# 全局安裝包 bins 鏈接的位置
globalBinDir = "~/.bun/bin"

`install.registry`

默認注冊表是 https://registry.npmjs.org/。這可以在 bunfig.toml 中全局配置：

toml

[install]
# 將默認注冊表設置為字符串
registry = "https://registry.npmjs.org"
# 設置令牌
registry = { url = "https://registry.npmjs.org", token = "123456" }
# 設置用戶名/密碼
registry = "https://username:password@registry.npmjs.org"

`install.linkWorkspacePackages`

要配置工作空間包如何鏈接，使用 install.linkWorkspacePackages 選項。

是否將工作空間包從 monorepo 根目錄鏈接到它們各自的 node_modules 目錄。默認值為 true。

toml

[install]
linkWorkspacePackages = true

`install.scopes`

要為特定作用域（例如 @myorg/<package>）配置注冊表，使用 install.scopes。你可以使用 $variable 表示法引用環境變量。

toml

[install.scopes]
# 注冊表為字符串
myorg = "https://username:password@registry.myorg.com/"

# 帶用戶名/密碼的注冊表
# 你可以引用環境變量
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

# 帶令牌的注冊表
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

`install.ca` 和 `install.cafile`

要配置 CA 證書，使用 install.ca 或 install.cafile 指定 CA 證書文件的路徑。

toml

[install]
# CA 證書為字符串
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# CA 證書文件的路徑。文件可以包含多個證書。
cafile = "path/to/cafile"

`install.cache`

配置緩存行為：

toml

[install.cache]

# 用於緩存的目錄
dir = "~/.bun/install/cache"

# 當為 true 時，不從全局緩存加載。
# Bun 可能仍然寫入 node_modules/.cache
disable = false

# 當為 true 時，始終從注冊表解析最新版本
disableManifest = false

`install.lockfile`

要配置鎖文件行為，使用 install.lockfile 部分。

bun install 時是否生成鎖文件。默認值為 true。

toml

[install.lockfile]
save = true

是否在 bun.lock 旁邊生成非 Bun 鎖文件。（始終會創建 bun.lock。）目前 "yarn" 是唯一支持的值。

toml

[install.lockfile]
print = "yarn"

`install.linker`

配置安裝依賴的鏈接器策略。對於新工作空間默認為 "isolated"，對於新單包項目和現有項目（v1.3.2 之前創建）默認為 "hoisted"。

完整文檔請參閱包管理器 > 隔離安裝。

toml

[install]
linker = "hoisted"

有效值為：

值	描述
`"hoisted"`	在共享的 `node_modules` 目錄中鏈接依賴。
`"isolated"`	在每個包安裝內部鏈接依賴。

toml

[debug]
# 當導航到 blob: 或 src: 鏈接時，在編輯器中打開文件
# 如果沒有，它嘗試 $EDITOR 或 $VISUAL
# 如果仍然失敗，它將嘗試 Visual Studio Code，然後是 Sublime Text，然後是其他一些
# 這由 Bun.openInEditor() 使用
editor = "code"

# 編輯器列表：
# - "subl", "sublime"
# - "vscode", "code"
# - "textmate", "mate"
# - "idea"
# - "webstorm"
# - "nvim", "neovim"
# - "vim","vi"
# - "emacs"

`install.security.scanner`

配置安全掃描器以在安裝前掃描包中的漏洞。

首先，從 npm 安裝安全掃描器：

bash

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

然後在 bunfig.toml 中配置它：

toml

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

當配置安全掃描器時：

自動禁用自動安裝以確保安全
包在安裝前被掃描
如果發現致命問題，安裝被取消
安裝期間顯示安全警告

了解有關使用安全掃描器的更多信息。

`install.minimumReleaseAge`

配置 npm 包版本的最小年齡（以秒為單位）。比此閾值最近發布的包版本將在安裝期間被過濾掉。默認值為 null（禁用）。

toml

[install]
# 僅安裝至少 3 天前發布的包版本
minimumReleaseAge = 259200
# 這些包將繞過 3 天最小年齡要求
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

有關詳細信息，請參閱安裝文檔中的最小發布年齡。

`bun run`

bun run 命令可以在 [run] 部分下配置。這些適用於 bun run 命令和運行可執行文件或腳本時的 bun 命令。

目前，bunfig.toml 僅在本地項目的 bun run 中自動加載（它不檢查全局 .bunfig.toml）。

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

通過 bun run 或 bun 運行 package.json 腳本時使用的 shell。在 Windows 上，默認為 "bun"，在其他平台上默認為 "system"。

要始終使用系統 shell 而不是 Bun 的 shell（除非 Windows 否則為默認行為）：

toml

[run]
# Windows 之外的默認值
shell = "system"

要始終使用 Bun 的 shell 而不是系統 shell：

toml

[run]
# Windows 上的默認值
shell = "bun"

`run.bun` - 自動將 `node` 別名為 `bun`

當為 true 時，這會在 $PATH 前添加一個指向 bun 二進制的 node 符號鏈接，用於 bun run 或 bun 調用的所有腳本或可執行文件。

這意味著如果你有一個運行 node 的腳本，它實際上將運行 bun，而無需更改腳本。這是遞歸工作的，所以如果你的腳本運行另一個運行 node 的腳本，它也將運行 bun。這也適用於 shebang，所以如果你有一個指向 node 的 shebang 腳本，它實際上將運行 bun。

默認情況下，如果你的 $PATH 中還沒有 node，則啟用此功能。

toml

[run]
# 等同於對所有 `bun run` 命令使用 `bun --bun`
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 運行的命令輸出。

toml

[run]
silent = true

沒有此選項時，運行的命令將打印到控制台：

bun run dev
echo "Running \"dev\"..."

txt

Running "dev"...

使用此選項時，運行的命令將不會打印到控制台：

bun run dev

txt

Running "dev"...

這等同於將 --silent 傳遞給所有 bun run 命令：

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

全局與本地 ​

運行時 ​

preload ​

jsx ​

smol ​

logLevel ​

define ​

loader ​

telemetry ​

console ​

console.depth ​

測試運行器 ​

test.root ​

test.preload ​

test.smol ​

test.coverage ​

test.coverageThreshold ​

test.coverageSkipTestFiles ​

test.coveragePathIgnorePatterns ​

test.coverageReporter ​

test.coverageDir ​

test.randomize ​

test.seed ​

test.rerunEach ​

test.concurrentTestGlob ​

test.onlyFailures ​

test.reporter ​

test.reporter.dots ​

test.reporter.junit ​

包管理器 ​

install.optional ​

install.dev ​

install.peer ​

install.production ​

install.exact ​

install.saveTextLockfile ​

install.auto ​

install.frozenLockfile ​

install.dryRun ​

install.globalDir ​

install.globalBinDir ​

install.registry ​

install.linkWorkspacePackages ​

install.scopes ​

install.ca 和 install.cafile ​

install.cache ​

install.lockfile ​

install.linker ​

install.security.scanner ​

install.minimumReleaseAge ​

bun run ​

run.shell - 使用系統 shell 或 Bun 的 shell ​

run.bun - 自動將 node 別名為 bun ​

run.silent - 抑制報告正在運行的命令 ​

全局與本地

運行時

`preload`

`jsx`

`smol`

`logLevel`

`define`

`loader`

`telemetry`

`console`

`console.depth`

測試運行器

`test.root`

`test.preload`

`test.smol`

`test.coverage`

`test.coverageThreshold`

`test.coverageSkipTestFiles`

`test.coveragePathIgnorePatterns`

`test.coverageReporter`

`test.coverageDir`

`test.randomize`

`test.seed`

`test.rerunEach`

`test.concurrentTestGlob`

`test.onlyFailures`

`test.reporter`

`test.reporter.dots`

`test.reporter.junit`

包管理器

`install.optional`

`install.dev`

`install.peer`

`install.production`

`install.exact`

`install.saveTextLockfile`

`install.auto`

`install.frozenLockfile`

`install.dryRun`

`install.globalDir`

`install.globalBinDir`

`install.registry`

`install.linkWorkspacePackages`

`install.scopes`

`install.ca` 和 `install.cafile`

`install.cache`

`install.lockfile`

`install.linker`

`install.security.scanner`

`install.minimumReleaseAge`

`bun run`

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

`run.bun` - 自動將 `node` 別名為 `bun`

`run.silent` - 抑制報告正在運行的命令