> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bunfig.toml

> 使用配置文件 bunfig.toml 配置 Bun 的行为

可以通过其配置文件 `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 的运行时行为通过 `bunfig.toml` 文件中的顶级字段进行配置。

### `preload`

一个脚本/插件数组，在运行文件或脚本前执行。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 在使用 `bun run` 运行文件或脚本前执行的脚本
# 通过添加到此列表来注册插件
preload = ["./preload.ts"]
```

### `jsx`

配置 Bun 如何处理 JSX。你也可以在 `tsconfig.json` 的 `compilerOptions` 中设置这些字段，但这里为了非 TypeScript 项目同样支持这些配置。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"
```

有关这些字段的更多信息，请参考 tsconfig 文档：

* [`jsx`](https://www.typescriptlang.org/tsconfig#jsx)
* [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
* [`jsxFragment`](https://www.typescriptlang.org/tsconfig#jsxFragment)
* [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource)

### `smol`

启用 `smol` 模式。此模式会降低内存使用，但会牺牲性能。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 降低内存使用，牺牲性能
smol = true
```

### `logLevel`

设置日志级别。可以是 `"debug"`、`"warn"` 或 `"error"`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
logLevel = "debug" # "debug" | "warn" | "error"
```

### `define`

`define` 字段允许你用常量表达式替换特定的全局标识符。Bun 会将任何该标识符的使用替换为指定表达式。表达式应是 JSON 字符串。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[define]
# 将所有 "process.env.bagel" 的使用替换为字符串 `lox`
# 值会被解析为 JSON，但支持单引号字符串，且 `'undefined'` 在 JS 中表示 undefined。
# 未来版本可能改为普通的 TOML 格式，目前保留此用法是继承自 CLI 参数解析。
"process.env.bagel" = "'lox'"
```

### `loader`

配置 Bun 如何将文件扩展名映射到加载器。适用于加载 Bun 本身不原生支持的文件。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[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 title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
telemetry = false
```

### `env`

配置自动 `.env` 文件加载。默认情况下，Bun 会自动加载 `.env` 文件。如需禁用此行为：

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 禁用自动加载 .env 文件
env = false
```

也可以使用对象语法并设置 `file` 属性：

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[env]
file = false
```

这在生产环境或 CI/CD 流水线中很有用，这类场景下通常只依赖系统环境变量。

注：即使禁用默认加载，通过 `--env-file` 明确指定的环境文件仍会被加载。

### `console`

配置控制台输出行为。

#### `console.depth`

设置 `console.log()` 对象检测的默认深度。默认值为 `2`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[console]
depth = 3
```

此设置控制控制台输出中对象呈现的嵌套层数。值越高，显示的嵌套属性越多，但复杂对象时输出会更冗长。该设置可被 `--console-depth` CLI 标志覆盖。

## 服务

`Bun.serve` 和 `bun run` 在提供 HTTP 服务时的选项配置在 `[serve]` 部分下。

### `serve.port`

`Bun.serve` 监听的默认端口。默认 `3000`。也可以通过 `BUN_PORT` 或 `PORT` 环境变量，或 `--port` 标志设置。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[serve]
port = 3000
```

## 测试运行器

测试运行器配置于 `bunfig.toml` 的 `[test]` 部分。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
# 在这里进行配置
```

### `test.root`

运行测试的根目录。默认 `.`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
root = "./__tests__"
```

### `test.preload`

与顶级 `preload` 字段相同，但仅应用于 `bun test`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
preload = ["./setup.ts"]
```

### `test.pathIgnorePatterns`

使用 glob 模式从测试发现中排除文件和目录。匹配的目录在扫描过程中会被剪枝，因此其内容不会被遍历。当你的项目包含子模块或带有 `*.test.ts` 文件的 vendored 代码，而你不想让 `bun test` 检测到时，这非常有用。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
pathIgnorePatterns = ["vendor/**", "submodules/**", "fixtures/**"]
```

等效 CLI 标志：`--path-ignore-patterns`。CLI 标志完全覆盖 `bunfig.toml` 的值。

### `test.smol`

与顶级 `smol` 字段相同，但仅应用于 `bun test`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
smol = true
```

### `test.coverage`

启用覆盖率报告。默认 `false`。可以使用 `--coverage` 来覆盖。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
coverage = false
```

### `test.coverageThreshold`

指定覆盖率门槛。默认无门槛。如果测试覆盖率未达到此门槛，`bun test` 会以非零退出码表示失败。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]

# 要求达到 90% 的行级和函数级覆盖率
coverageThreshold = 0.9
```

也可分别为行覆盖、函数覆盖和语句覆盖设置不同门槛。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }
```

### `test.coverageSkipTestFiles`

计算覆盖率统计时是否跳过测试文件。默认 `false`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
coverageSkipTestFiles = false
```

### `test.coverageIgnoreSourcemaps`

是否报告转译后的输出覆盖率，而不是通过 sourcemaps 将行号映射回原始源码。默认 `false`。主要用于调试。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
coverageIgnoreSourcemaps = false
```

### `test.coveragePathIgnorePatterns`

使用 glob 模式排除特定文件或模式在覆盖率报告中的统计。可以是单个字符串，也可以是模式数组。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
# 单个模式
coveragePathIgnorePatterns = "**/*.spec.ts"

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

### `test.coverageReporter`

默认情况下，覆盖率报告会输出到控制台。为了在 CI 环境中持久保存并供其他工具使用，请使用 `lcov`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
coverageReporter  = ["text", "lcov"]  # 默认 ["text"]
```

### `test.coverageDir`

设置覆盖率报告保存路径。仅对持久化的 `coverageReporter`（如 `lcov`）有效。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
coverageDir = "path/to/somewhere"  # 默认 "coverage"
```

### `test.randomize`

以随机顺序运行测试。默认 `false`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
randomize = true
```

此功能有助于捕获测试间相互依赖导致的 Bug。配合 `seed` 使用，随机顺序可复现。

当指定 `--randomize` CLI 标志时，会覆盖此设置。

### `test.seed`

设置测试随机化的随机种子。需要 `randomize` 为 `true`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
randomize = true
seed = 2444615283
```

设置种子可使随机测试顺序在多次运行中可复现，便于调试不稳定的测试。遇到失败时可用相同种子重现当时顺序。

`--seed` CLI 标志会覆盖此设置。

### `test.rerunEach`

每个测试文件重复运行指定次数。默认 `0`（运行一次）。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
rerunEach = 3
```

此功能有助于捕获不稳定或非确定性行为的测试。每个测试文件将被执行指定次数。

`--rerun-each` CLI 标志会覆盖此设置。

### `test.retry`

所有测试的默认重试次数。失败的测试会被重试最多该次数。单个测试通过 `{ retry: N }` 覆盖此值。默认 `0`（不重试）。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
retry = 3
```

`--retry` CLI 标志会覆盖此设置。

### `test.concurrentTestGlob`

指定一个 glob 模式，使匹配的测试文件自动启用并发执行。这些测试文件行为等同于使用了 `--concurrent` 标志，文件内所有测试将并发运行。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
concurrentTestGlob = "**/concurrent-*.test.ts"
```

适用场景：

* 逐步迁移测试套件至并发执行
* 并发运行集成测试，同时单线程运行单元测试
* 将快速并发测试与需要依序运行的测试分开

当指定 `--concurrent` CLI 标志时，会覆盖此设置。

### `test.onlyFailures`

启用后，仅显示失败的测试结果，减少大型测试套件的输出噪声。默认 `false`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test]
onlyFailures = true
```

等同于运行 `bun test` 时使用 `--only-failures`。

### `test.reporter`

配置测试报告器设置。

#### `test.reporter.dots`

启用点状报告器，输出紧凑模式，每个测试用点表示。默认 `false`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test.reporter]
dots = true
```

#### `test.reporter.junit`

启用 JUnit XML 报告，并指定输出文件路径。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[test.reporter]
junit = "test-results.xml"
```

生成的 JUnit XML 可用于 CI 系统及其他工具。

## 包管理器

包管理是复杂的问题；为支持多种使用场景，`bun install` 的行为可在 `[install]` 部分配置。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
# 这里进行配置
```

### `install.optional`

是否安装可选依赖。默认 `true`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
optional = true
```

### `install.dev`

是否安装开发依赖。默认 `true`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
dev = true
```

### `install.peer`

是否安装 peer 依赖。默认 `true`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
peer = true
```

### `install.production`

`bun install` 是否以“生产模式”运行。默认 `false`。

生产模式下，不安装 `"devDependencies"`。CLI 中可使用 `--production` 覆盖此设置。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
production = false
```

### `install.exact`

是否在 `package.json` 中设置精确版本号。默认 `false`。

默认情况下，Bun 使用插入符号版本范围；例如包的最新版本为 `2.4.1`，则 `package.json` 中的版本范围是 `^2.4.1`，表示接受 `2.4.1` 到（不含）`3.0.0` 之间的任意版本。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
exact = false
```

### `install.ignoreScripts`

安装期间是否跳过生命周期脚本。默认 `false`。等同于 `--ignore-scripts` 标志。

当为 `true` 时，Bun 不会运行任何 `preinstall` / `install` / `postinstall` / `prepare` 脚本——包括你的项目以及 `trustedDependencies` 中的包。更多详情请参见[生命周期脚本](/pm/lifecycle)。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
ignoreScripts = false
```

### `install.concurrentScripts`

一次可并发运行的生命周期脚本最大数量。默认为 CPU 核心数的两倍。等同于 `--concurrent-scripts` 标志。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
concurrentScripts = 5
```

### `install.saveTextLockfile`

如果为 false，当执行 `bun install` 并且不存在锁文件时，会生成二进制格式的 `bun.lockb`，而非文本格式的 `bun.lock`。

默认自 Bun v1.2 起为 `true`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
saveTextLockfile = false
```

### `install.auto`

配置 Bun 的包自动安装行为。默认 `"auto"` —— 如果未找到 `node_modules` 文件夹，Bun 会在执行时自动安装依赖。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
auto = "auto"
```

有效值说明：

| 值            | 描述                                                  |
| ------------ | --------------------------------------------------- |
| `"auto"`     | 如果存在本地 `node_modules`，则从中解析模块。否则，在执行时自动安装依赖。        |
| `"force"`    | 即使存在 `node_modules`，也总是自动安装依赖。                      |
| `"disable"`  | 从不自动安装依赖。                                           |
| `"fallback"` | 先检查本地 `node_modules`，对未找到的包自动安装。CLI 可用 `bun -i` 启用。 |

### `install.prefer`

配置 Bun 在运行脚本时如何针对 npm 注册表解析包版本。默认 `"online"`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
prefer = "online"
```

有效值：

| 值           | 描述                                       |
| ----------- | ---------------------------------------- |
| `"online"`  | 默认。按需检查注册表中是否有过期包。                       |
| `"offline"` | 跳过过期检查，并从本地缓存解析包。等同于 `--prefer-offline`。 |
| `"latest"`  | 始终向 npm 检查最新的匹配版本。等同于 `--prefer-latest`。 |

### `install.frozenLockfile`

为 true 时，`bun install` 不会更新 `bun.lock`。默认 `false`。如果 `package.json` 与现有 `bun.lock` 不匹配，则会报错。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
frozenLockfile = false
```

### `install.dryRun`

是否真正安装依赖。默认 `false`。为 true 则等同于所有 `bun install` 命令加上 `--dry-run`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
dryRun = false
```

### `install.globalDir`

配置全局安装包的存放目录。

环境变量：`BUN_INSTALL_GLOBAL_DIR`

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
# `bun install --global` 安装包的位置
globalDir = "~/.bun/install/global"
```

### `install.globalBinDir`

配置全局安装的二进制文件和 CLI 的存放目录。

环境变量：`BUN_INSTALL_BIN`

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
# 全局安装包的二进制文件链接存放位置
globalBinDir = "~/.bun/bin"
```

### `install.registry`

默认注册表为 `https://registry.npmjs.org/`。可在全局的 `bunfig.toml` 中配置：

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[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）包的链接方式。

是否将工作区包从 monorepo 根目录链接到各自的 `node_modules` 目录。默认 `true`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
linkWorkspacePackages = true
```

### `install.scopes`

为特定作用域（如 `@myorg/<package>`）配置注册表，使用 `install.scopes`。可通过 `$variable` 引用环境变量。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[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` 指定证书文件路径。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
# CA 证书内容（字符串）
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# CA 证书文件路径，文件可以包含多个证书
cafile = "path/to/cafile"
```

### `install.cache`

配置缓存行为：

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install.cache]

# 缓存目录
dir = "~/.bun/install/cache"

# 为 true 则不从全局缓存加载
# 但 Bun 仍可能写入 node_modules/.cache
disable = false

# 为 true 始终从注册表解析最新版本
disableManifest = false
```

### `install.lockfile`

配置锁文件行为，使用 `install.lockfile` 部分。

是否在 `bun install` 时生成锁文件。默认 `true`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install.lockfile]
save = true
```

是否在生成 `bun.lock` 之外，同时生成非 Bun 格式的锁文件。默认不生成。目前支持的取值只有 `"yarn"`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install.lockfile]
print = "yarn"
```

### `install.linker`

配置安装依赖的链接策略。新工作区默认 `"isolated"`，新单包项目与现有项目（v1.3.2 以前版本）默认 `"hoisted"`。

完整文档见 [包管理 > 隔离安装](/pm/isolated-installs)。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
linker = "hoisted"
```

有效值：

| 值            | 描述                          |
| ------------ | --------------------------- |
| `"hoisted"`  | 链接依赖到共享的 `node_modules` 目录。 |
| `"isolated"` | 每个包安装内部各自链接依赖。              |

### `install.globalStore`

当使用 `"isolated"` 链接器时，会在全局虚拟存储 `<cache>/links/` 中跨项目共享包安装，并将 `node_modules/.bun/<pkg>@<ver>` 链接到其中，而不是将每个包实际展开到项目中。这样在 `rm -rf node_modules` 之后的热安装会快一个数量级。默认 `false`。也可以通过 `BUN_INSTALL_GLOBAL_STORE` 环境变量设置。

完整文档请参见[包管理器 > 全局虚拟存储](/pm/global-store)。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
globalStore = true
```

### `install.publicHoistPattern`

在使用 `"isolated"` 链接器时，匹配这些 glob 模式的包会被提升到根 `node_modules` 目录，以便项目中的任何包都能解析它们。默认 `[]`。类似于 pnpm 的 `public-hoist-pattern`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
publicHoistPattern = ["*eslint*", "*prettier*"]
```

### `install.hoistPattern`

在使用 `"isolated"` 链接器时，匹配这些 glob 模式的包会被提升到虚拟存储根目录（`node_modules/.bun`），以便虚拟存储中的其他包能够解析它们。默认 `[]`。类似于 pnpm 的 `hoist-pattern`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
hoistPattern = ["*"]
```

### `install.logLevel`

设置 `bun install` 的日志级别。可以是 `"debug"`、`"warn"` 或 `"error"`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
logLevel = "warn"
```

### `install.security.scanner`

配置安全扫描器，在安装前扫描包中的安全漏洞。

首先，从 npm 安装安全扫描器：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add -d @oven/bun-security-scanner
```

<Note>
  `@oven/bun-security-scanner` 是一个示例包名，不是真实存在的包。请将其替换为你要使用的扫描器，并查阅该扫描器的文档以获取准确的包名和安装说明。大多数扫描器都可通过 `bun add` 安装。
</Note>

然后在你的 `bunfig.toml` 中进行配置：

```toml bunfig.toml icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install.security]
scanner = "@oven/bun-security-scanner" # 示例名称，请替换为你的扫描器包名
```

配置安全扫描器后：

* 自动安装功能会自动禁用，以保障安全
* 安装前扫描包
* 发现严重问题时取消安装
* 安装过程中显示安全警告

详细了解[使用和编写安全扫描器](/pm/security-scanner-api)。

### `install.minimumReleaseAge`

配置 npm 包版本的最小发布日期（秒）。在安装时，会过滤掉比此阈值更新的版本。默认 `null`（禁用）。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
# 只安装至少 3 天前发布的包版本
minimumReleaseAge = 259200
```

更多详情见安装文档的[最小发布年龄](/pm/cli/install#minimum-release-age)。

### `install.minimumReleaseAgeExcludes`

排除在 `minimumReleaseAge` 检查之外的包名数组。默认 `[]`。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
minimumReleaseAge = 259200
# 这些包将绕过 3 天的最小发布时间要求
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]
```

## `bun run`

`bun run` 命令可在 `[run]` 部分配置。适用于 `bun run` 命令及使用 `bun` 命令运行文件、可执行程序或脚本时。

当前，`bunfig.toml` 只会自动加载本地项目中的配置（不会检查全局 `.bunfig.toml`）。

### `run.shell` — 使用系统 shell 还是 Bun 的 shell

通过 `bun run` 或 `bun` 运行 package.json 脚本时使用的 shell。Windows 默认 `"bun"`，其他平台默认 `"system"`。

如需始终使用系统 shell（非 Windows 上的默认行为）：

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[run]
# 非 Windows 的默认值
shell = "system"
```

如需始终使用 Bun 的 shell 而非系统 shell：

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[run]
# Windows 的默认值
shell = "bun"
```

### `run.bun` — 自动将 `node` 别名为 `bun`

设为 `true` 时，会在所有由 `bun run` 或 `bun` 调用的脚本或可执行文件的 `$PATH` 前添加一个指向 `bun` 二进制的 `node` 符号链接。

这意味着即使脚本内部调用 `node`，实际执行的也是 `bun`，无需修改脚本。此映射支持递归调用，对使用 `node` 的 shebang 同样生效。

默认情况下，如果 `$PATH` 中尚无 `node`，此功能启用。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[run]
# 相当于为所有 `bun run` 命令启用 `--bun`
bun = true
```

你可以通过以下命令测试：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --bun which node # bun 二进制文件的路径
bun which node      # node 二进制文件的路径
```

此选项等同于为所有 `bun run` 命令加上 `--bun` 参数：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --bun run dev
bun --bun dev
bun run --bun dev
```

设置为 `false` 时禁用该功能。

### `run.silent` — 静默运行，不输出命令提示

设为 `true` 时，`bun run` 或 `bun` 不会输出发送的命令信息。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[run]
silent = true
```

未启用该选项时，命令会打印如下内容：

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run dev
echo "正在运行 \"dev\"..."
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
正在运行 "dev"...
```

启用该选项后，命令将不再打印：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run dev
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
正在运行 "dev"...
```

这等同于对所有 `bun run` 命令使用 `--silent` 参数：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --silent run dev
bun --silent dev
bun run --silent dev
```

### `run.elide-lines` - 截断过滤后的输出

使用 `--filter` 时，每个脚本显示的脚本输出行数。默认值为 `10`。设为 `0` 可显示全部行。等同于 `--elide-lines` 标志。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[run]
elide-lines = 10
```

### `run.noOrphans` - 不留下孤儿进程

设为 `true` 时，Bun 会监视启动它的进程，并在该父进程消失后立即退出——即使父进程被 `SIGKILL`，也不会有机会转发信号。在退出时，Bun 还会递归地对其创建的所有后代进程发送 `SIGKILL`，确保它启动的进程不会比它活得更久。适用于 Bun 由某个监督程序（Electron、CI 运行器、轻量级 shim）启动，而该监督程序可能被强制终止的场景。

仅适用于 Linux 和 macOS（在 Windows 及其他平台上无效）。等同于 `--no-orphans` CLI 标志或 `BUN_FEATURE_FLAG_NO_ORPHANS=1` 环境变量。

```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[run]
noOrphans = true
```