> ## 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.

# TOML

> 通过运行时 API 和打包器集成，使用 Bun 对 TOML 文件的内置支持

在 Bun 中，TOML 与 JSON、JSON5 和 YAML 同为一等公民。你可以：

* 使用 `Bun.TOML.parse` 解析 TOML 字符串
* 在运行时通过 `import` 和 `require` 将 TOML 文件作为模块导入（支持热重载和监听模式）
* 通过 Bun 的打包器在前端应用中 `import` 和 `require` TOML 文件

***

## 运行时 API

### `Bun.TOML.parse()`

将 TOML 字符串解析为 JavaScript 对象。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
import { TOML } from "bun";
const text = `
name = "my-app"
version = "1.0.0"
debug = true

[database]
host = "localhost"
port = 5432

[features]
tags = ["web", "api"]
`;

const data = TOML.parse(text);
console.log(data);
// {
//   name: "my-app",
//   version: "1.0.0",
//   debug: true,
//   database: { host: "localhost", port: 5432 },
//   features: { tags: ["web", "api"] }
// }
```

#### 支持的 TOML 特性

Bun 的 TOML 解析器支持 [TOML v1.0 规范](https://toml.io/en/v1.0.0)，包括：

* **字符串**：基本字符串 (`"..."`) 和字面量字符串 (`'...'`)，包括多行字符串
* **整数**：十进制、十六进制（`0x`）、八进制（`0o`）和二进制（`0b`）
* **浮点数**：包括 `inf` 和 `nan`
* **布尔值**：`true` 和 `false`
* **数组**：支持混合类型及嵌套数组
* **表**：标准表（`[table]`）和内联表（`{ key = "value" }`）
* **表数组**：`[[array]]`
* **点记法键**：`a.b.c = "value"`
* **注释**：使用 `#`

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
const data = Bun.TOML.parse(`
# 应用配置
title = "My App"

[owner]
name = "John Doe"

[database]
enabled = true
ports = [8000, 8001, 8002]
connection_max = 5000

[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"
`);
```

#### 错误处理

如果 TOML 无效，`Bun.TOML.parse()` 会抛出异常：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
try {
  Bun.TOML.parse("invalid = = =");
} catch (error) {
  console.error("解析 TOML 失败:", error.message);
}
```

***

## 模块导入

### ES 模块

你可以直接将 TOML 文件作为 ES 模块导入。TOML 内容会被解析，并以默认导出和命名导出的形式提供：

```toml config.toml theme={"theme":{"light":"github-light","dark":"dracula"}}
[database]
host = "localhost"
port = 5432
name = "myapp"

[redis]
host = "localhost"
port = 6379

[features]
auth = true
rateLimit = true
analytics = false
```

#### 默认导入

```ts app.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import config from "./config.toml";

console.log(config.database.host); // "localhost"
console.log(config.redis.port); // 6379
```

#### 命名导入

你可以将顶层 TOML 表解构为命名导入：

```ts app.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import { database, redis, features } from "./config.toml";

console.log(database.host); // "localhost"
console.log(redis.port); // 6379
console.log(features.auth); // true
```

或者两者结合：

```ts app.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import config, { database, features } from "./config.toml";

// 使用完整配置对象
console.log(config);

// 或者使用特定部分
if (features.rateLimit) {
  setupRateLimiting(database);
}
```

#### 导入属性

你也可以使用导入属性将任意文件以 TOML 形式加载：

```ts app.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import myConfig from "./my.config" with { type: "toml" };
```

### CommonJS

TOML 文件同样可以在 CommonJS 中被 require：

```ts app.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
const config = require("./config.toml");
console.log(config.database.name); // "myapp"

// 解构同样可用
const { database, redis } = require("./config.toml");
console.log(database.port); // 5432
```

***

## TOML 热重载

当你使用 `bun --hot` 运行应用时，对 TOML 文件的修改会被自动检测并热重载，无需重启：

```toml config.toml theme={"theme":{"light":"github-light","dark":"dracula"}}
[server]
port = 3000
host = "localhost"

[features]
debug = true
verbose = false
```

```ts server.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import { server, features } from "./config.toml";

console.log(`启动服务器：${server.host}:${server.port}`);

Bun.serve({
  port: server.port,
  hostname: server.host,
  fetch(req) {
    if (features.verbose) {
      console.log(`${req.method} ${req.url}`);
    }
    return new Response("Hello World");
  },
});
```

使用热重载运行：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --hot server.ts
```

现在修改 `config.toml` 时，改动会立即反映到正在运行的应用中。

***

## 打包器集成

当你导入 TOML 文件并使用 Bun 打包时，TOML 会在构建时被解析，并作为 JavaScript 模块包含到打包产物中：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build app.ts --outdir=dist
```

这意味着：

* 生产环境零运行时 TOML 解析开销
* 更小的打包体积
* 对未使用属性（命名导入）的摇树优化支持

### 动态导入

TOML 文件支持动态导入：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
const config = await import("./config.toml");
```