TOML

在 Bun 中，TOML 与 JSON、JSON5 和 YAML 一样是一等公民。您可以：

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

运行时 API

`Bun.TOML.parse()`

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

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.1.0 规范，并通过了完整的官方 toml-test 一致性测试套件。

字符串：基本（"..."）和字面量（'...'），包括多行，所有转义符（\uHHHH、\UHHHHHHHH 以及 TOML 1.1 的 \xHH 和 \e）
整数：十进制、十六进制（0x）、八进制（0o）和二进制（0b）。无法无损表示为 JavaScript 数值的整数——超出 ±(2^53 - 1)——会抛出异常
浮点数：包括 inf 和 nan
布尔值：true 和 false
日期/时间：偏移日期时间、本地日期时间、本地日期和本地时间，以其源文本字符串形式返回
数组：包括混合类型和嵌套数组
表：标准（[table]）和内联（{ key = "value" }），包括 TOML 1.1 多行内联表
表数组：[[array]]
点键：a.b.c = "value"
注释：使用 #

const data = Bun.TOML.parse(`
# Application config
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"
`);

错误处理

Bun.TOML.parse() 在 TOML 无效时抛出 SyntaxError：

try {
  Bun.TOML.parse("invalid = = =");
} catch (error) {
  console.error("Failed to parse TOML:", error.message);
  // Failed to parse TOML: TOML Parse error: Expected a value but found '='
}

`Bun.TOML.stringify()`

将 JavaScript 对象序列化为 TOML 文档。标量键在前，然后是 [table] 和 [[array-of-tables]] 部分：

Bun.TOML.stringify({
  name: "app",
  server: { host: "localhost", port: 8080 },
  points: [{ x: 1 }, { x: 2 }],
});
// name = "app"
//
// [server]
// host = "localhost"
// port = 8080
//
// [[points]]
// x = 1
//
// [[points]]
// x = 2

顶层值必须是对象——TOML 文档就是一个表。Date 值变成 TOML 偏移日期时间。由于 TOML 无法表示它们，null 值、BigInt 和循环结构会抛出异常；undefined、函数和符号属性会被跳过（在数组内部会抛出异常，因为 TOML 数组不能有空位）。

模块导入

ES 模块

直接作为 ES 模块导入 TOML 文件。Bun 解析 TOML 并将其作为默认导出和命名导出暴露：

config.toml

[database]
host = "localhost"
port = 5432
name = "myapp"

[redis]
host = "localhost"
port = 6379

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

默认导入

app.ts

import config from "./config.toml";

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

命名导入

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

app.ts

import { database, redis, features } from "./config.toml";

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

或者组合两者：

app.ts

import config, { database, features } from "./config.toml";

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

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

导入属性

使用导入属性将任何文件作为 TOML 加载：

app.ts

import myConfig from "./my.config" with { type: "toml" };

CommonJS

您也可以在 CommonJS 中 require TOML 文件：

app.ts

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 运行应用程序时，Bun 会检测 TOML 文件的更改并重新加载它们，无需重启：

config.toml

[server]
port = 3000
host = "localhost"

[features]
debug = true
verbose = false

server.ts

import { server, features } from "./config.toml";

console.log(`Starting server on ${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");
  },
});

使用热重载运行：

terminal

bun --hot server.ts

打包器集成

当您使用 Bun 打包时，打包器会在构建时解析导入的 TOML 并将其作为 JavaScript 模块包含：

terminal

bun build app.ts --outdir=dist

这意味着：

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

动态导入

您也可以动态导入 TOML 文件：

const config = await import("./config.toml");

开始入门

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

互操作与工具

实用工具

标准与兼容性

贡献指南

运行时 API

`Bun.TOML.parse()`

支持的 TOML 特性

错误处理

`Bun.TOML.stringify()`

模块导入

ES 模块

默认导入

命名导入

导入属性

CommonJS

TOML 热重载

打包器集成

动态导入

​运行时 API

​Bun.TOML.parse()

​支持的 TOML 特性

​错误处理

​Bun.TOML.stringify()

​模块导入

​ES 模块

​默认导入

​命名导入

​导入属性

​CommonJS

​TOML 热重载

​打包器集成

​动态导入

运行时 API

`Bun.TOML.parse()`

支持的 TOML 特性

错误处理

`Bun.TOML.stringify()`

模块导入

ES 模块

默认导入

命名导入

导入属性

CommonJS

TOML 热重载

打包器集成

动态导入