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

套件管理員

套件管理是一個複雜的問題；為了支援各種使用案例，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.auto`

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

[install]
auto = "auto"

有效值為

值	說明
`"auto"`	如果存在，則從本機 `node_modules` 解析模組。否則，自動安裝依賴項。
`"force"`	即使存在 `node_modules`，也總是自動安裝依賴項。
`"disable"`	永不自動安裝依賴項。
`"fallback"`	先檢查本機 `node_modules`，然後自動安裝找不到的任何套件。您可以使用 `bun -i` 從 CLI 啟用此功能。

`install.frozenLockfile`

如果為 true，則 bun install 不會更新 bun.lockb。預設為 false。如果 package.json 和現有的 bun.lockb 不一致，則會發生錯誤。

[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.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.lockb 旁邊產生非 Bun 鎖定檔。（將始終建立 bun.lockb。）目前 "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` - 使用系統殼層或 Bun 的殼層

在透過 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 時，這會在 $PATH 前面加上一個指向 bun 二進檔的 node 符號連結，以供 bun run 或 bun 呼叫的所有腳本或可執行檔使用。

這表示如果你有一個執行 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