bunfig.toml – 執行階段 | 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 設定。

執行階段

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

`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 環境變數。

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`

啟用覆蓋率報告。預設值為 false。使用 --coverage 覆寫。

[test]
coverage = false

`test.coverageThreshold`

指定覆蓋率閾值。預設情況下，未設定閾值。如果您的測試套件未達到或超過此閾值，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

`test.coverageReporter`

預設情況下，覆蓋率報告將列印到主控台。對於 CI 環境中的持久程式碼覆蓋率報告以及其他工具，請使用 lcov。

[test]
coverageReporter  = ["text", "lcov"]  # default ["text"]

`test.coverageDir`

設定將儲存覆蓋率報告的路徑。請注意，這僅適用於持久 coverageReporter，如 lcov。

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

套件管理器

套件管理是一個複雜的問題；為了支援各種使用案例，bun install 的行為可以在 [install] 區段下設定。

[install]
# configuration here

`install.optional`

是否安裝選用相依性。預設值為 true。

[install]
optional = true

`install.dev`

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

[install]
dev = true

`install.peer`

是否安裝同級相依性。預設值為 true。

[install]
peer = true

`install.production`

bun install 是否將在「生產模式」下執行。預設值為 false。

在生產模式下，不會安裝 "devDependencies"。您可以在 CLI 中使用 --production 來覆寫此設定。

[install]
production = false

`install.exact`

是否在 package.json 中設定確切的版本。預設值為 false。

預設情況下，Bun 使用插入號範圍；如果套件的 latest 版本為 2.4.1，則您的 package.json 中的版本範圍將為 ^2.4.1。這表示從 2.4.1 到（但不包含）3.0.0 的任何版本都是可接受的。

[install]
exact = false

`install.saveTextLockfile`

如果為 false，則在執行 bun install 且沒有鎖定檔時，產生二進位 bun.lockb 而不是基於文字的 bun.lock 檔案。

預設值為 true（自 Bun v1.2 起）。

[install]
saveTextLockfile = false

`install.auto`

設定 Bun 的套件自動安裝行為。預設值為 "auto" — 當找不到 node_modules 資料夾時，Bun 將在執行期間動態自動安裝相依性。

[install]
auto = "auto"

有效值為

值	描述
`"auto"`	如果本機 `node_modules` 存在，則從中解析模組。否則，動態自動安裝相依性。
`"force"`	始終自動安裝相依性，即使 `node_modules` 存在。
`"disable"`	永不自動安裝相依性。
`"fallback"`	先檢查本機 `node_modules`，然後自動安裝任何找不到的套件。您可以使用 CLI 中的 `bun -i` 啟用此功能。

`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 放置全域安裝套件的目錄。

[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`

若要為特定範圍（例如 @myorg/<package>）設定登錄檔，請使用 install.scopes。您可以使用 $variable 標記法參考環境變數。

[install.scopes]
# registry as string
myorg = "https://username:password@registry.myorg.com/"

# registry with username/password
# you can reference environment variables
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }

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

`install.ca` 和 `install.cafile`

若要設定 CA 憑證，請使用 install.ca 或 install.cafile 指定 CA 憑證檔案的路徑。

[install]
# The CA certificate as a string
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# A path to a CA certificate file. The file can contain multiple certificates.
cafile = "path/to/cafile"

`install.cache`

設定快取行為

[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.lock。）目前，"yarn" 是唯一支援的值。

[install.lockfile]
print = "yarn"

`bun run`

bun run 命令可以在 [run] 區段下設定。這些設定適用於 bun run 命令以及執行檔案、可執行檔或腳本時的 bun 命令。

目前，bunfig.toml 並非總是針對本機專案中的 bun run 自動載入（它會檢查全域 bunfig.toml），因此您可能仍然需要傳遞 -c 或 -c=bunfig.toml 才能使用這些設定。

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

透過 bun run 或 bun 執行 package.json 腳本時要使用的 shell。在 Windows 上，預設值為 "bun"，在其他平台上，預設值為 "system"。

始終使用系統 shell 而不是 Bun 的 shell（除非 Windows，否則為預設行為）

[run]
# default outside of Windows
shell = "system"

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

[run]
# default on Windows
shell = "bun"

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

如果為 true，這會為 bun run 或 bun 呼叫的所有腳本或可執行檔，在 $PATH 前面加上一個指向 bun 二進位檔案的 node 符號連結。

這表示如果您有一個執行 node 的腳本，它實際上會執行 bun，而無需變更您的腳本。這會遞迴運作，因此如果您的腳本執行另一個執行 node 的腳本，它也會執行 bun。這也適用於 shebang，因此如果您有一個 shebang 指向 node 的腳本，它實際上會執行 bun。

預設情況下，如果 node 尚未在您的 $PATH 中，則會啟用此功能。

[run]
# equivalent to `bun --bun` for all `bun run` commands
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 輸出的正在執行的命令。

[run]
silent = true

如果沒有此選項，正在執行的命令將列印到主控台

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

使用此選項，正在執行的命令將不會列印到主控台

bun run dev
Running "dev"...

這相當於將 --silent 傳遞給所有 bun run 命令

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