Appearance
Bun API 全面指南
Bun 为开发者提供了一系列强大的原生 API，这些 API 通过全局对象 Bun 及多个内置模块来实现。本文将帮助你了解这些高度优化的 API，它们代表了 Bun 原生方式实现常见功能的最佳实践。
Bun API 设计理念
Bun 尽可能遵循 Web 标准 API，只在没有标准存在的服务器端任务（如文件 I/O 和启动 HTTP 服务器）中引入新 API。
即使在引入新 API 时，Bun 也会基于标准 API（如 Blob、URL 和 Request）进行构建，确保开发体验的一致性。
快速入门示例
以下是使用 Bun API 创建简单 HTTP 服务器的示例：
ts
// 创建一个基本的 HTTP 服务器
Bun.serve({
fetch(req: Request) {
return new Response("Hello from Bun!");
},
});这个简单的例子展示了 Bun 如何通过标准的 Web API 接口（Request 和 Response）来构建服务器功能。
Bun API 详细分类
下表提供了 Bun API 的完整概览，点击右侧链接可跳转到相应的文档。
常用 API 详解
HTTP 服务器 (Bun.serve)
INFO
什么是 Bun.serve? Bun.serve 是 Bun 提供的高性能 HTTP 服务器 API，它使用了标准的 Web 请求和响应对象，允许您快速构建 Web 应用。
基本示例
ts
// 创建一个简单的 HTTP 服务器
const server = Bun.serve({
port: 3000,
fetch(req) {
const url = new URL(req.url);
// 路由处理
if (url.pathname === "/") {
return new Response("欢迎来到首页!");
}
if (url.pathname === "/api") {
// 返回 JSON 数据
return Response.json({
success: true,
message: "这是一个 API 响应",
time: new Date().toISOString(),
});
}
// 404 页面
return new Response("页面未找到", { status: 404 });
},
});
console.log(`服务器运行在 http://localhost:${server.port}`);文件操作 (Bun.file 和 Bun.write)
TIP
高效文件操作 Bun 提供了比 Node.js fs 模块更简洁高效的文件操作 API，使得读写文件变得异常简单。
读取文件示例
ts
// 读取文件内容
const file = Bun.file("./example.txt");
// 以字符串形式读取
const text = await file.text();
console.log("文件内容:", text);
// 以 JSON 形式读取（如果文件包含有效 JSON）
const jsonFile = Bun.file("./data.json");
const data = await jsonFile.json();
console.log("JSON 数据:", data);写入文件示例
ts
// 写入字符串到文件
await Bun.write("output.txt", "这是要写入的内容");
// 写入 JSON 数据
const userData = { name: "张三", age: 30, roles: ["admin", "user"] };
await Bun.write("user.json", JSON.stringify(userData, null, 2));
// 写入 Blob 或 Buffer
const buffer = Buffer.from("二进制数据示例");
await Bun.write("binary.dat", buffer);子进程 (Bun.spawn 和 Bun.spawnSync)
使用这些 API 可以轻松执行外部命令，例如系统命令或其他程序。
异步子进程示例
ts
// 异步执行外部命令
const proc = Bun.spawn(["ls", "-la"], {
cwd: "./project", // 指定工作目录
env: { ...process.env }, // 环境变量
stdio: ["inherit", "pipe", "pipe"], // 标准输入输出配置
});
// 读取输出
const output = await new Response(proc.stdout).text();
console.log("命令输出:", output);
// 等待进程完成
const exitCode = await proc.exited;
console.log("进程退出代码:", exitCode);同步子进程示例
ts
// 同步执行命令（阻塞）
const result = Bun.spawnSync(["echo", "Hello Bun!"]);
// 检查结果
console.log("退出代码:", result.exitCode);
console.log("标准输出:", Buffer.from(result.stdout).toString());Bun API 和 Node.js API 的比较
了解 Bun API 与 Node.js 的区别有助于更好地迁移现有项目或选择合适的 API。
| 功能 | Node.js 方式 | Bun 方式 | Bun 优势 |
|---|---|---|---|
| HTTP 服务器 | http.createServer() | Bun.serve() | 更简洁的 API，原生支持 Web 标准 Request/Response |
| 文件读取 | fs.readFile() | Bun.file().text() | 链式 API，支持多种格式读取 |
| 文件写入 | fs.writeFile() | Bun.write() | 简化的单函数 API，支持多种输入类型 |
| 子进程 | child_process.spawn() | Bun.spawn() | 更好的异步支持，与 Web API 集成 |
| 打包 | 需要第三方（webpack 等） | Bun.build() | 内置打包器，无需配置 |
结语
Bun API 体系提供了一套高效、现代的工具集，同时尊重 Web 标准和 Node.js 生态。通过学习和使用这些 API，你可以充分发挥 Bun 的性能优势，构建更高效的 JavaScript 和 TypeScript 应用。
在实际开发中，可以根据项目需求灵活选择 Bun 原生 API 或兼容的 Node.js API，两者可以和谐共存，共同为你的应用提供支持。