Skip to main content
在 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.0 规范，包括：
  • 字符串：基本字符串 ("...") 和字面量字符串 ('...')，包括多行字符串
  • 整数：十进制、十六进制（0x）、八进制（0o）和二进制（0b）
  • 浮点数：包括 inf 和 nan
  • 布尔值：true 和 false
  • 数组：支持混合类型及嵌套数组
  • 表：标准表（[table]）和内联表（{ key = "value" }）
  • 表数组：[[array]]
  • 点记法键：a.b.c = "value"
  • 注释：使用 #
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() 会抛出异常： 
try {
  Bun.TOML.parse("invalid = = =");
} catch (error) {
  console.error("解析 TOML 失败:", error.message);
}

​
模块导入

​
ES 模块

你可以直接将 TOML 文件作为 ES 模块导入。TOML 内容会被解析，并以默认导出和命名导出的形式提供：
config.toml
[database]
host = "localhost"
port = 5432
name = "myapp"

[redis]
host = "localhost"
port = 6379

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

​
默认导入

https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217app.ts
import config from "./config.toml";

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

​
命名导入

你可以将顶层 TOML 表解构为命名导入：
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217app.ts
import { database, redis, features } from "./config.toml";

console.log(database.host); // "localhost"
console.log(redis.port); // 6379
console.log(features.auth); // true
或者两者结合：
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217app.ts
import config, { database, features } from "./config.toml";

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

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

​
导入属性

你也可以使用导入属性将任意文件以 TOML 形式加载：
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217app.ts
import myConfig from "./my.config" with { type: "toml" };

​
CommonJS

TOML 文件同样可以在 CommonJS 中被 require：
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217app.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 运行应用时，对 TOML 文件的修改会被自动检测并热重载，无需重启：
config.toml
[server]
port = 3000
host = "localhost"

[features]
debug = true
verbose = false
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217server.ts
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");
  },
});
使用热重载运行：
terminal
bun --hot server.ts
现在修改 config.toml 时，改动会立即反映到正在运行的应用中。

​
打包器集成

当你导入 TOML 文件并使用 Bun 打包时，TOML 会在构建时被解析，并作为 JavaScript 模块包含到打包产物中：
terminal
bun build app.ts --outdir=dist
这意味着：
  • 生产环境零运行时 TOML 解析开销
  • 更小的打包体积
  • 对未使用属性（命名导入）的摇树优化支持

​
动态导入

TOML 文件支持动态导入： 
const config = await import("./config.toml");