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.
在 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 内容会被解析，并以默认导出和命名导出的形式提供：
[database]
host = "localhost"
port = 5432
name = "myapp"
[redis]
host = "localhost"
port = 6379
[features]
auth = true
rateLimit = true
analytics = false
默认导入
app.tsimport 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
TOML 文件同样可以在 CommonJS 中被 require：
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 运行应用时，对 TOML 文件的修改会被自动检测并热重载，无需重启：
[server]
port = 3000
host = "localhost"
[features]
debug = true
verbose = false
server.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");
},
});
config.toml 时，改动会立即反映到正在运行的应用中。
打包器集成
当你导入 TOML 文件并使用 Bun 打包时，TOML 会在构建时被解析，并作为 JavaScript 模块包含到打包产物中：
bun build app.ts --outdir=dist
- 生产环境零运行时 TOML 解析开销
- 更小的打包体积
- 对未使用属性（命名导入）的摇树优化支持
动态导入
TOML 文件支持动态导入：
const config = await import("./config.toml");
