bunfig.toml

bunfig.toml 是 Bun 的設定檔。

Bun 會盡可能使用現有的設定檔，例如 package.json 和 tsconfig.json；bunfig.toml 僅用於 Bun 特有的設定。該檔案是可選的，即使沒有它，Bun 也能正常工作。

全域性 vs. 本地

將 bunfig.toml 放在專案根目錄中，與 package.json 放在一起。

如需全域性設定 Bun 的套件管理器，也可以在以下任一路徑建立 .bunfig.toml 檔案：

• $HOME/.bunfig.toml
• $XDG_CONFIG_HOME/.bunfig.toml

只有套件管理器命令（bun install、bun add、bun remove、bun update、bun pm、bunx 等）會讀取全域性檔案。如果 Bun 同時找到全域性和本地 bunfig，則會載入二者；本地檔案中設定的鍵會覆蓋全域性檔案中的同名鍵。適用時，CLI 標誌會覆蓋 bunfig 設定。

執行環境

頂層欄位用於設定 Bun 的執行環境行為。

preload

一個指令碼/外掛陣列，在執行檔案或指令碼前執行。

# 在使用 `bun run` 執行檔案或指令碼前執行的指令碼
# 通過新增到此列表來註冊外掛
preload = ["./preload.ts"]

jsx

設定 Bun 處理 JSX 的方式。你也可以在 tsconfig.json 的 compilerOptions 中設定這些欄位，但 bunfig.toml 支援在非 TypeScript 專案中使用它們。

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

有關這些欄位的更多資訊，請參考 tsconfig 文件：

• jsx
• jsxFactory
• jsxFragment
• jsxImportSource

smol

啟用 smol 模式。此模式會降低記憶體使用，但會犧牲效能。

# 降低記憶體使用，犧牲效能
smol = true

logLevel

設定日誌級別："debug"、"warn" 或 "error"。

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

define

define 欄位會將全域性識別符號替換為常量表達式，無論它們出現在哪裡。該表示式應為 JSON 字串。

[define]
# 將所有 "process.env.bagel" 的使用替換為字串 `lox`
# 值會被解析為 JSON，但支援單引號字串，且 `'undefined'` 在 JS 中表示 undefined。
# 未來版本可能改為普通的 TOML 格式，目前保留此用法是繼承自 CLI 引數解析。
"process.env.bagel" = "'lox'"

loader

設定 Bun 將副檔名對映到載入器的方式。使用此設定可以載入 Bun 原生不支援的檔案型別。

[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 花費多長時間等資訊。

telemetry = false

env

設定自動載入 .env 檔案的行為。Bun 預設會載入 .env 檔案。要停用此行為：

# 停用自動載入 .env 檔案
env = false

也可以使用物件語法並設定 file 屬性：

[env]
file = false

在生產環境或 CI/CD 流程中，如果你希望完全相依系統環境變數，可以使用此設定。

即使停用了預設載入，Bun 仍會載入通過 --env-file 顯式傳入的檔案。

console

設定控制台輸出行為。

console.depth

設定 console.log() 物件檢測的預設深度。預設值為 2。

[console]
depth = 3

較高的值會顯示更多巢狀屬性，但對於複雜物件可能會產生冗長的輸出。--console-depth CLI 標誌會覆蓋此設定。

服務

[serve] 部分用於設定 Bun.serve 和提供 HTTP 服務時的 bun run。

serve.port

Bun.serve 監聽的預設埠。預設值為 3000。你也可以通過 BUN_PORT 或 PORT 環境變數，或 --port 標誌進行設定。

[serve]
port = 3000

測試執行器

bunfig.toml 的 [test] 部分用於設定測試執行器。

[test]
# 在這裡進行設定

test.root

執行測試的根目錄。預設 .。

[test]
root = "./__tests__"

test.preload

與頂級 preload 欄位相同，但僅應用於 bun test。

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

test.pathIgnorePatterns

使用 glob 模式從測試發現中排除檔案和目錄。測試執行器會在掃描期間剪除匹配的目錄，因此不會遍歷其中的內容。如果專案包含帶有 *.test.ts 檔案、且不希望被 bun test 發現的子模組或 vendored 程式碼，可以使用此設定。

[test]
pathIgnorePatterns = ["vendor/**", "submodules/**", "fixtures/**"]

等效 CLI 標誌：--path-ignore-patterns。CLI 標誌完全覆蓋 bunfig.toml 的值。

test.smol

與頂級 smol 欄位相同，但僅應用於 bun test。

[test]
smol = true

test.coverage

啟用覆蓋率報告。預設 false。可以使用 --coverage 來覆蓋。

[test]
coverage = false

test.coverageThreshold

覆蓋率閾值。預設不設定閾值。如果測試套件未達到該閾值，bun test 將以非零退出程式碼退出。

[test]

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

你可以為行覆蓋率和函式覆蓋率分別設定閾值。Bun 接受 statements 鍵，但目前不會強制執行該閾值。

[test]
coverageThreshold = { lines = 0.7, functions = 0.8 }

test.coverageSkipTestFiles

計算覆蓋率統計時是否跳過測試檔案。預設 false。

[test]
coverageSkipTestFiles = false

test.coverageIgnoreSourcemaps

是否報告轉譯後的輸出覆蓋率，而不是通過 sourcemaps 將行號映射回原始原始碼。預設 false。主要用於除錯。

[test]
coverageIgnoreSourcemaps = false

test.coveragePathIgnorePatterns

使用 glob 模式從覆蓋率報告中排除檔案。可以接受單個模式或模式陣列。

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

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

test.coverageReporter

預設情況下，測試執行器會將覆蓋率報告列印到控制台。如需生成 CI 和其他工具可讀取的持久化報告，請使用 lcov。

[test]
coverageReporter  = ["text", "lcov"]  # 預設 ["text"]

test.coverageDir

設定儲存覆蓋率報告的路徑。此設定僅適用於 lcov 等持久化報告器。

[test]
coverageDir = "path/to/somewhere"  # 預設 "coverage"

test.randomize

以隨機順序執行測試。預設 false。

[test]
randomize = true

每次以不同順序執行測試有助於發現與測試相互相依相關的錯誤。與 seed 結合使用時，隨機順序可以復現。

--randomize CLI 標誌會覆蓋此設定。

test.seed

設定測試隨機化的隨機種子。需要 randomize 為 true。

[test]
randomize = true
seed = 2444615283

隨機種子可以讓測試順序在多次執行之間保持可復現，從而有助於除錯不穩定的測試。

--seed CLI 標誌會覆蓋此設定。

test.rerunEach

每個測試檔案重複執行指定次數。預設 0（執行一次）。

[test]
rerunEach = 3

可以使用此設定來發現不穩定的測試或非確定性行為。

--rerun-each CLI 標誌會覆蓋此設定。

test.retry

所有測試的預設重試次數。測試執行器最多會重試失敗的測試指定次數。每個測試的 { retry: N } 設定會覆蓋此值。預設 0（不重試）。

[test]
retry = 3

--retry CLI 標誌會覆蓋此設定。

test.concurrentTestGlob

匹配此 glob 模式的測試檔案將並行執行其中的所有測試，就像傳入了 --concurrent 標誌一樣。

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

可以使用此設定逐步將測試套件遷移到並行執行，或在保持單元測試順序執行的同時並行執行整合測試。

--concurrent CLI 標誌會覆蓋此設定。

test.onlyFailures

啟用後，輸出中只顯示失敗的測試，從而減少大型測試套件中的冗餘資訊。預設 false。

[test]
onlyFailures = true

等效於 --only-failures 標誌。

test.reporter

設定測試報告器設定。

test.reporter.dots

啟用點號報告器，每個測試列印一個點。預設 false。

[test.reporter]
dots = true

test.reporter.junit

啟用 JUnit XML 報告，並指定輸出檔案路徑。

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

CI 系統和其他工具可以使用此報告。

套件管理器

[install] 部分設定 bun install 的行為。

[install]
# 這裡進行設定

install.optional

是否安裝可選相依。預設 true。

[install]
optional = true

install.dev

是否安裝開發相依。預設 true。

[install]
dev = true

install.peer

是否安裝 peer 相依。預設 true。

[install]
peer = true

install.production

是否讓 bun install 在“生產模式”下執行。預設 false。

在生產模式下，Bun 不會安裝 "devDependencies"，並會凍結鎖檔案（與 install.frozenLockfile 相同）。使用 --production CLI 標誌可為單次安裝啟用此模式。由於生產模式會凍結鎖檔案，因此啟用該模式時，bun add、bun remove 和 bun update 會失敗。

[install]
production = false

install.exact

是否在 package.json 中設定精確版本號。預設 false。

預設情況下，Bun 使用 caret 範圍。如果某個包的 latest 版本為 2.4.1，Bun 會在你的 package.json 中寫入 ^2.4.1。該範圍接受從 2.4.1 起、但不包括 3.0.0 的任何版本。

[install]
exact = false

install.ignoreScripts

安裝期間是否跳過生命週期指令碼。預設 false。等同於 --ignore-scripts 標誌。

當設定為 true 時，Bun 不會執行任何 preinstall / install / postinstall / prepare 指令碼，包括專案中的指令碼和 trustedDependencies 中包的指令碼。請參閱生命週期指令碼。

[install]
ignoreScripts = false

install.concurrentScripts

一次可並行執行的生命週期指令碼最大數量。預設為 CPU 核心數的兩倍。等同於 --concurrent-scripts 標誌。

[install]
concurrentScripts = 5

install.saveTextLockfile

如果為 false，當不存在鎖檔案時，bun install 會生成二進位制 bun.lockb，而不是基於文本的 bun.lock 檔案。

預設自 Bun v1.2 起為 true。

[install]
saveTextLockfile = false

install.auto

設定 Bun 的自動安裝行為。預設值為 "auto"——找不到 node_modules 資料夾時，Bun 會在執行期間即時安裝相依。

[install]
auto = "auto"

有效值說明：

install.prefer

設定 Bun 在執行指令碼時如何針對 npm 登錄檔解析包版本。預設 "online"。

[install]
prefer = "online"

有效值：

install.offline

當設定為 true 時，bun install 永遠不會訪問網路：包後設資料和 tarball 必須已在快取中，缺少任何內容都會報錯。預設 false。等同於 bun install --offline。如需使用更寬鬆的“儘可能使用快取”行為，請參閱 install.prefer = "offline" / --prefer-offline。

[install]
offline = true

install.frozenLockfile

當設定為 true 時，bun install 不會更新 bun.lock。預設 false。如果 package.json 與現有的 bun.lock 不一致，安裝會報錯。

[install]
frozenLockfile = false

install.dryRun

是否讓 bun install 解析相依但不安裝。預設 false。當設定為 true 時，等同於向所有 bun install 命令傳入 --dry-run。

[install]
dryRun = false

install.globalDir

Bun 存放全域性安裝包的目錄。

環境變數：BUN_INSTALL_GLOBAL_DIR

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

install.globalBinDir

Bun 連結全域性安裝包二進位制檔案的目錄。

環境變數：BUN_INSTALL_BIN

[install]
# 全域性安裝包的二進位制檔案連結存放位置
globalBinDir = "~/.bun/bin"

install.registry

預設登錄檔為 https://registry.npmjs.org/。如需更改：

[install]
# 以字串形式設定預設登錄檔
registry = "https://registry.npmjs.org"
# 設定 token
registry = { url = "https://registry.npmjs.org", token = "123456" }
# 設定使用者名稱/密碼
registry = "https://username:password@registry.npmjs.org"

install.linkWorkspacePackages

是否將工作區包從 monorepo 根目錄連結到各自的 node_modules 目錄。預設 true。

[install]
linkWorkspacePackages = true

install.scopes

如需為特定作用域（例如 @myorg/<package>）設定登錄檔，請使用 install.scopes。你可以使用 $variable 語法引用環境變數。

[install.scopes]
# 字串格式登錄檔
myorg = "https://username:password@registry.myorg.com/"

# 帶使用者名稱/密碼，支援引用環境變數
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

install.ca 和 install.cafile

如需設定 CA 證書，請將 install.ca 設定為證書字串，或將 install.cafile 設定為證書檔案的路徑。

[install]
# CA 證書內容（字串）
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# CA 證書檔案路徑，檔案可以包含多個證書
cafile = "path/to/cafile"

install.cache

設定快取行為：

[install.cache]

# 快取目錄
dir = "~/.bun/install/cache"

# 為 true 則不從全域性快取載入
# 但 Bun 仍可能寫入 node_modules/.cache
disable = false

# 為 true 始終從登錄檔解析最新版本
disableManifest = false

install.lockfile

是否在執行 bun install 時生成鎖檔案。預設 true。

[install.lockfile]
save = true

是否在 bun.lock 之外同時生成非 Bun 鎖檔案。（Bun 始終會建立 bun.lock。）"yarn" 是唯一受支援的值。

[install.lockfile]
print = "yarn"

install.linker

設定連結器策略：即 bun install 如何在 node_modules 中組織相依。對於新的工作區，預設為 "isolated"；對於新的單包專案和現有專案（在 v1.3.2 之前建立），預設為 "hoisted"。

請參閱隔離安裝。

[install]
linker = "hoisted"

有效值：

install.globalStore

使用 "isolated" 連結器時，可在 <cache>/links/ 下的全域性虛擬儲存中共享多個專案之間的包安裝。Bun 會將 node_modules/.bun/<pkg>@<ver> 連結到儲存中，而不是將每個包實際寫入專案目錄。這樣，在執行 rm -rf node_modules 後進行熱安裝，速度可提高一個數量級。預設 false。你也可以通過 BUN_INSTALL_GLOBAL_STORE 環境變數進行設定。

請參閱全域性虛擬儲存。

[install]
globalStore = true

install.publicHoistPattern

使用 "isolated" 連結器時，Bun 會將匹配這些 glob 模式的包提升到根 node_modules 目錄，使專案中的任何包都可以解析它們。預設 []。與 pnpm 的 public-hoist-pattern 類似。

[install]
publicHoistPattern = ["*eslint*", "*prettier*"]

install.hoistPattern

使用 "isolated" 連結器時，Bun 會將匹配這些 glob 模式的包提升到虛擬儲存中的回退目錄（node_modules/.bun/node_modules），使虛擬儲存中的其他包可以解析它們。預設情況下，Bun 會將所有包提升到此目錄中，等同於 ["*"]。與 pnpm 的 hoist-pattern 類似。

[install]
hoistPattern = ["*"]

install.hoist

使用 "isolated" 連結器時，Bun 會建立 node_modules/.bun/node_modules。此回退目錄包含指向每個已安裝包的符號連結；如果設定了 install.hoistPattern，則只包含指向匹配包的符號連結。該目錄位於儲存中每個包的向上解析路徑上，因此包仍可解析自己未宣告的相依（“幽靈相依”）。將 hoist = false 可完全跳過此目錄的建立。此時，除非匯入的包已連結到專案根目錄的 node_modules（即直接相依、匹配 publicHoistPattern 的包或工作區包），否則儲存中包的未宣告匯入會失敗。專案自身的 node_modules 符號連結不會改變。預設 true。等同於 pnpm 的 hoist 設定，包括此處提到的根 node_modules 注意事項；其優先順序高於 install.hoistPattern。

此設定僅適用於 "isolated" 連結器。提升式安裝不受影響：在那裡，扁平的 node_modules 樹本身就是佈局，而不是由此開關控制的內容。

[install]
hoist = false

install.logLevel

設定 bun install 的日誌級別。可以是 "debug"、"warn" 或 "error"。

[install]
logLevel = "warn"

install.security.scanner

設定安全掃描器，在安裝前掃描包中的安全漏洞。

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

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

然後在你的 bunfig.toml 中進行設定：

[install.security]
scanner = "@oven/bun-security-scanner" # 範例名稱，請替換為你的掃描器包名

設定安全掃描器後：

• 自動安裝功能會自動停用，以保障安全
• 安裝前掃描包
• 發現嚴重問題時取消安裝
• 安裝過程中顯示安全警告

詳細瞭解使用和編寫安全掃描器。

install.minimumReleaseAge

設定 npm 包版本的最短髮布時間（秒）。安裝過程中，Bun 會篩除釋出時間早於此閾值的包版本。預設 null（停用）。

[install]
# 只安裝至少 3 天前釋出的包版本
minimumReleaseAge = 259200

請參閱最短髮布時間。

install.minimumReleaseAgeExcludes

從 minimumReleaseAge 檢查中排除的包名陣列。預設 []。

[install]
minimumReleaseAge = 259200
# 這些包將繞過 3 天的最小發布時間要求
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

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 外所有平臺上的預設設定）：

[run]
# 非 Windows 的預設值
shell = "system"

如需始終使用 Bun 的 shell 而非系統 shell：

[run]
# Windows 的預設值
shell = "bun"

run.bun — 自動將 node 別名為 bun

當設定為 true 時，對於由 bun run 或 bun 呼叫的所有指令碼或執行檔，Bun 會在 $PATH 前新增一個指向 bun 二進位制檔案的 node 符號連結。

執行 node 的指令碼會改為執行 bun，無需修改指令碼。此行為會遞迴應用，因此，如果某個指令碼執行另一個會執行 node 的指令碼，該指令碼也會執行 bun。此別名也適用於指向 node 的 shebang。

預設情況下，如果 $PATH 中尚無 node，此功能啟用。

[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 可停用 node 符號連結。

run.silent — 靜默執行，不輸出命令提示

設為 true 時，bun run 和 bun 不會列印正在執行的命令。

[run]
silent = true

如果不使用此選項，Bun 會將正在執行的命令列印到控制台：

bun run dev
echo "正在執行 \"dev\"..."

正在執行 "dev"...

使用此選項後，Bun 不會列印正在執行的命令：

bun run dev

正在執行 "dev"...

這等同於對所有 bun run 命令使用 --silent 引數：

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

run.elide-lines - 截斷過濾後的輸出

在終端中使用 --filter 時，將每個指令碼的輸出截斷為最後 N 行。預設 0（顯示所有行）。等同於 --elide-lines 標誌。

[run]
elide-lines = 10

run.noOrphans - 不留下孤兒行程

設為 true 時，Bun 會監視啟動它的行程，並在該父行程消失後立即退出，即使父行程被強制終止而來不及轉發訊號。當 Bun 自身退出時，也會終止所有後代行程，以確保它啟動的行程不會繼續執行。適用於由可能被強制終止的監控程式（Electron、CI 執行器或輕量級 shim）啟動 Bun 的情況。

在 Linux 上，Bun 使用 prctl(PR_SET_PDEATHSIG) 和 /proc 後代行程遍歷。在 macOS 上，Bun 使用事件迴圈 kqueue 上的 EVFILT_PROC/NOTE_EXIT 和 libproc 後代行程遍歷。在 Windows 上，Bun 使用父行程控制代碼的執行緒池等待和關閉時終止行程的 Job Object。

等同於 --no-orphans CLI 標誌或 BUN_FEATURE_FLAG_NO_ORPHANS=1 環境變數。

[run]
noOrphans = true