YAML

在 Bun 中，YAML 与 JSON 和 TOML 同等重要。你可以：

使用 Bun.YAML.parse 解析 YAML 字符串
在运行时以模块形式 import 和 require YAML 文件（包括热重载和监听模式支持）
通过 Bun 的打包器在前端应用中 import 和 require YAML 文件

兼容性

Bun 的 YAML 解析器目前通过了官方 YAML 测试套件超过 90% 的测试。我们正积极努力达到 100% 兼容，但现有实现已覆盖绝大多数实际使用场景。解析器使用 Zig 编写以获得最佳性能，并持续改进中。

运行时 API

`Bun.YAML.parse()`

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

import { YAML } from "bun";
const text = `
name: John Doe
age: 30
email: [email protected]
hobbies:
  - reading
  - coding
  - hiking
`;

const data = YAML.parse(text);
console.log(data);
// {
//   name: "John Doe",
//   age: 30,
//   email: "[email protected]",
//   hobbies: ["reading", "coding", "hiking"]
// }

多文档 YAML

解析由多个文档（用 --- 分隔）构成的 YAML 时，Bun.YAML.parse() 返回一个数组：

const multiDoc = `
---
name: Document 1
---
name: Document 2
---
name: Document 3
`;

const docs = Bun.YAML.parse(multiDoc);
console.log(docs);
// [
//   { name: "Document 1" },
//   { name: "Document 2" },
//   { name: "Document 3" }
// ]

支持的 YAML 特性

Bun 的 YAML 解析器支持完整的 YAML 1.2 规范，包括：

标量：字符串、数字、布尔值、null 值
集合：序列（数组）和映射（对象）
锚点与别名：使用 & 和 * 的可复用节点
标签：类型提示，如 !!str、!!int、!!float、!!bool、!!null
多行字符串：文字块 (|) 和折叠块 (>) 标量
注释：使用 #
指令：%YAML 和 %TAG

const yaml = `
# 员工记录
employee: &emp
  name: Jane Smith
  department: Engineering
  skills:
    - JavaScript
    - TypeScript
    - React

manager: *emp  # 引用员工

config: !!str 123  # 显式字符串类型

description: |
  这是一个多行
  文字字符串，保留
  换行和空格。

summary: >
  这是一个折叠字符串，
  用空格连接行，
  除非有空白行。
`;

const data = Bun.YAML.parse(yaml);

错误处理

如果 YAML 无效，Bun.YAML.parse() 会抛出 SyntaxError：

try {
  Bun.YAML.parse("invalid: yaml: content:");
} catch (error) {
  console.error("解析 YAML 失败:", error.message);
}

模块导入

ES 模块

你可以直接将 YAML 文件导入为 ES 模块。YAML 内容会被解析，既作为默认导出，也提供命名导出：

config.yaml

database:
  host: localhost
  port: 5432
  name: myapp

redis:
  host: localhost
  port: 6379

features:
  auth: true
  rateLimit: true
  analytics: false

默认导入

https://mintcdn.com/ikxin/RzFFGbzo0-4huILA/icons/typescript.svg?fit=max&auto=format&n=RzFFGbzo0-4huILA&q=85&s=a3dffd2241f05776d3bd25171d0c5a79

app.ts

import config from "./config.yaml";

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

命名导入

你可以将顶层 YAML 属性解构为命名导入：

app.ts

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

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

或者两者结合：

app.ts

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

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

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

CommonJS

YAML 文件也可以在 CommonJS 环境中通过 require 加载：

app.ts

const config = require("./config.yaml");
console.log(config.database.name); // "myapp"

// 解构同样有效
const { database, redis } = require("./config.yaml");
console.log(database.port); // 5432

YAML 热重载

Bun 支持的 YAML 最强大特性之一是热重载。当你使用 bun --hot 运行应用时，对 YAML 文件的修改会被自动检测并进行热刷新，无需关闭连接。

配置热重载示例

config.yaml

server:
  port: 3000
  host: localhost

features:
  debug: true
  verbose: false

server.ts

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

console.log(`启动服务器，地址为 ${server.host}:${server.port}`);

if (features.debug) {
  console.log("调试模式已启用");
}

// 服务器代码
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.yaml 会立即在运行的应用中生效。非常适合：

开发过程中的配置调整
不重启测试不同设置
配置变更时实时调试
启用或关闭功能开关

配置管理

基于环境的配置

YAML 非常适合管理多环境配置：

config.yaml

defaults: &defaults
  timeout: 5000
  retries: 3
  cache:
    enabled: true
    ttl: 3600

development:
  <<: *defaults
  api:
    url: http://localhost:4000
    key: dev_key_12345
  logging:
    level: debug
    pretty: true

staging:
  <<: *defaults
  api:
    url: https://staging-api.example.com
    key: ${STAGING_API_KEY}
  logging:
    level: info
    pretty: false

production:
  <<: *defaults
  api:
    url: https://api.example.com
    key: ${PROD_API_KEY}
  cache:
    enabled: true
    ttl: 86400
  logging:
    level: error
    pretty: false

app.ts

import configs from "./config.yaml";

const env = process.env.NODE_ENV || "development";
const config = configs[env];

// YAML 值中的环境变量插值函数
function interpolateEnvVars(obj: any): any {
  if (typeof obj === "string") {
    return obj.replace(/\${(\w+)}/g, (_, key) => process.env[key] || "");
  }
  if (typeof obj === "object") {
    for (const key in obj) {
      obj[key] = interpolateEnvVars(obj[key]);
    }
  }
  return obj;
}

export default interpolateEnvVars(config);

功能标志配置

features.yaml

features:
  newDashboard:
    enabled: true
    rolloutPercentage: 50
    allowedUsers:
      - [email protected]
      - [email protected]

  experimentalAPI:
    enabled: false
    endpoints:
      - /api/v2/experimental
      - /api/v2/beta

  darkMode:
    enabled: true
    default: auto # auto, light, dark

feature-flags.ts

import { features } from "./features.yaml";

export function isFeatureEnabled(featureName: string, userEmail?: string): boolean {
  const feature = features[featureName];

  if (!feature?.enabled) {
    return false;
  }

  // 检查发布比例
  if (feature.rolloutPercentage < 100) {
    const hash = hashCode(userEmail || "anonymous");
    if (hash % 100 >= feature.rolloutPercentage) {
      return false;
    }
  }

  // 检查允许用户列表
  if (feature.allowedUsers && userEmail) {
    return feature.allowedUsers.includes(userEmail);
  }

  return true;
}

// 与热重载配合，实现实时切换功能
if (isFeatureEnabled("newDashboard", user.email)) {
  renderNewDashboard();
} else {
  renderLegacyDashboard();
}

数据库配置

database.yaml

connections:
  primary:
    type: postgres
    host: ${DB_HOST:-localhost}
    port: ${DB_PORT:-5432}
    database: ${DB_NAME:-myapp}
    username: ${DB_USER:-postgres}
    password: ${DB_PASS}
    pool:
      min: 2
      max: 10
      idleTimeout: 30000

  cache:
    type: redis
    host: ${REDIS_HOST:-localhost}
    port: ${REDIS_PORT:-6379}
    password: ${REDIS_PASS}
    db: 0

  analytics:
    type: clickhouse
    host: ${ANALYTICS_HOST:-localhost}
    port: 8123
    database: analytics

migrations:
  autoRun: ${AUTO_MIGRATE:-false}
  directory: ./migrations

seeds:
  enabled: ${SEED_DB:-false}
  directory: ./seeds

db.ts

import { connections, migrations } from "./database.yaml";
import { createConnection } from "./database-driver";

// 解析带默认值的环境变量
function parseConfig(config: any) {
  return JSON.parse(
    JSON.stringify(config).replace(
      /\${([^:-]+)(?::([^}]+))?}/g,
      (_, key, defaultValue) => process.env[key] || defaultValue || "",
    ),
  );
}

const dbConfig = parseConfig(connections);

export const db = await createConnection(dbConfig.primary);
export const cache = await createConnection(dbConfig.cache);
export const analytics = await createConnection(dbConfig.analytics);

// 如果配置自动执行迁移
if (parseConfig(migrations).autoRun === "true") {
  await runMigrations(db, migrations.directory);
}

打包器集成

当你导入 YAML 文件并用 Bun 打包时，YAML 会在构建时被解析并作为 JavaScript 模块包含：

terminal

bun build app.ts --outdir=dist

这意味着：

生产环境零运行时 YAML 解析开销
更小的包体积
支持未用配置的摇树优化（命名导入）

动态导入

YAML 文件可以动态导入，适合按需加载配置：

// 根据环境加载配置
const env = process.env.NODE_ENV || "development";
const config = await import(`./configs/${env}.yaml`);

// 加载用户特定设置
async function loadUserSettings(userId: string) {
  try {
    const settings = await import(`./users/${userId}/settings.yaml`);
    return settings.default;
  } catch {
    return await import("./users/default-settings.yaml");
  }
}

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

兼容性

运行时 API

`Bun.YAML.parse()`

多文档 YAML

支持的 YAML 特性

错误处理

模块导入

ES 模块

默认导入

命名导入

CommonJS

YAML 热重载

配置热重载示例

配置管理

基于环境的配置

功能标志配置

数据库配置

打包器集成

动态导入

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

​兼容性

​运行时 API

​Bun.YAML.parse()

​多文档 YAML

​支持的 YAML 特性

​错误处理

​模块导入

​ES 模块

​默认导入

​命名导入

​CommonJS

​YAML 热重载

​配置热重载示例

​配置管理

​基于环境的配置

​功能标志配置

​数据库配置

​打包器集成

​动态导入

兼容性

运行时 API

`Bun.YAML.parse()`

多文档 YAML

支持的 YAML 特性

错误处理

模块导入

ES 模块

默认导入

命名导入

CommonJS

YAML 热重载

配置热重载示例

配置管理

基于环境的配置

功能标志配置

数据库配置

打包器集成

动态导入