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 中，JSON5 与 JSON、TOML 和 YAML 一样，是一等公民。你可以：
- 使用
Bun.JSON5.parse 和 Bun.JSON5.stringify 解析和序列化 JSON5
- 在运行时以模块形式
import 和 require JSON5 文件（支持热重载和监视模式）
- 通过 Bun 的打包工具在前端应用中
import 和 require JSON5 文件
兼容性
Bun 的 JSON5 解析器通过了官方 JSON5 测试套件 100% 的测试。解析器使用 Zig 编写以实现最佳性能。你可以查看我们的 翻译测试套件 查看每个测试用例。
运行时 API
Bun.JSON5.parse()
将 JSON5 字符串解析为 JavaScript 值。
import { JSON5 } from "bun";
const data = JSON5.parse(`{
// JSON5 支持注释
name: 'my-app',
version: '1.0.0',
debug: true,
// 允许尾随逗号
tags: ['web', 'api',],
}`);
console.log(data);
// {
// name: "my-app",
// version: "1.0.0",
// debug: true,
// tags: ["web", "api"]
// }
支持的 JSON5 特性
JSON5 是基于 ECMAScript 5.1 语法的 JSON 超集。它支持：
- 注释：单行注释 (
//) 和多行注释 (/* */)
- 尾随逗号：对象和数组中允许
- 未加引号的键：有效的 ECMAScript 5.1 标识符可以用作键
- 单引号字符串：除了双引号字符串外支持单引号
- 多行字符串：使用反斜杠换行
- 十六进制数：
0xFF
- 数字前后的小数点：
.5 和 5.
- 无限大和 NaN：正负无穷和非数字值
- 显式加号：
+42
const data = JSON5.parse(`{
// 未加引号的键
unquoted: 'keys work',
// 单引号和双引号
single: 'single-quoted',
double: "double-quoted",
// 尾随逗号
trailing: 'comma',
// 特殊数字
hex: 0xDEADbeef,
half: .5,
to: Infinity,
nan: NaN,
// 多行字符串
multiline: 'line 1 \
line 2',
}`);
错误处理
如果输入不是有效的 JSON5，Bun.JSON5.parse() 会抛出 SyntaxError：
try {
JSON5.parse("{invalid}");
} catch (error) {
console.error("解析 JSON5 失败:", error.message);
}
Bun.JSON5.stringify()
将 JavaScript 值序列化为 JSON5 字符串。
import { JSON5 } from "bun";
const str = JSON5.stringify({ name: "my-app", version: "1.0.0" });
console.log(str);
// {name:'my-app',version:'1.0.0'}
美化输出
传入 space 参数来格式化输出并缩进：
const pretty = JSON5.stringify(
{
name: "my-app",
debug: true,
tags: ["web", "api"],
},
null,
2,
);
console.log(pretty);
// {
// name: 'my-app',
// debug: true,
// tags: [
// 'web',
// 'api',
// ],
// }
space 参数可为数字（空格数）或字符串（用作缩进字符）：
// 使用制表符缩进
JSON5.stringify(data, null, "\t");
特殊值
与 JSON.stringify 不同，JSON5.stringify 会保留特殊数值：
JSON5.stringify({ inf: Infinity, ninf: -Infinity, nan: NaN });
// {inf:Infinity,ninf:-Infinity,nan:NaN}
模块导入
ES 模块
可以直接将 JSON5 文件作为 ES 模块导入：
{
// 数据库配置
database: {
host: "localhost",
port: 5432,
name: "myapp",
},
features: {
auth: true,
rateLimit: true,
analytics: false,
},
}
默认导入
app.tsimport config from "./config.json5";
console.log(config.database.host); // "localhost"
console.log(config.features.auth); // true
命名导入
可以将顶层属性作为命名导入进行解构：
app.ts import { database, features } from "./config.json5";
console.log(database.host); // "localhost"
console.log(features.rateLimit); // true
CommonJS
JSON5 文件同样可以在 CommonJS 中通过 require 引入：
app.ts const config = require("./config.json5");
console.log(config.database.name); // "myapp"
// 解构也支持
const { database, features } = require("./config.json5");
JSON5 热重载
当使用 bun --hot 运行你的应用时，JSON5 文件的变动会自动被检测并重载：
{
server: {
port: 3000,
host: "localhost",
},
features: {
debug: true,
verbose: false,
},
}
server.ts import { server, features } from "./config.json5";
Bun.serve({
port: server.port,
hostname: server.host,
fetch(req) {
if (features.verbose) {
console.log(`${req.method} ${req.url}`);
}
return new Response("Hello World");
},
});
打包工具集成
当你导入 JSON5 文件并使用 Bun 打包时，JSON5 会在构建时被解析，并作为 JavaScript 模块包含：
bun build app.ts --outdir=dist
- 生产环境零运行时 JSON5 解析开销
- 更小的包体积
- 对未使用属性支持摇树优化（命名导入）
动态导入
JSON5 文件也支持动态导入：
const { default: config } = await import("./config.json5");
