bun-runtime

Bun 运行时

概述

Bun 是一款一体化的 JavaScript 和 TypeScript 运行时，内置高速包管理器、打包器、测试运行器以及兼容 Node.js 的 API。它可以原生执行 TypeScript 和 JSX，无需单独编译。

适用场景： 快速运行服务器端 JavaScript、以 TypeScript 为先的项目、替代 Node.js 以提升启动性能，以及无需外部工具即可使用内置 SQLite、密码哈希、文件 I/O、HTTP 服务、打包和测试。

不适用场景： 需要完整兼容 Node.js 生态系统的项目（部分原生模块不受支持）、需要 Node.js 久经考验的稳定性的生产环境，或不需要运行时的纯浏览器端代码。

快速参考

模式	API	要点
HTTP 服务	Bun.serve({ routes, fetch })	基于路由，支持静态/动态路由和按方法设置处理程序
读取文件	Bun.file(path)	延迟加载的 BunFile（Blob），支持 .text()、.json()、.stream()
写入文件	Bun.write(dest, data)	接受字符串、Blob、Response、BunFile
SQLite	来自 bun:sqlite 的 new Database(path)	同步查询、预处理语句、WAL 模式
密码哈希	Bun.password.hash(pw)	默认使用 Argon2id，也可选择 bcrypt；支持异步和同步版本
密码验证	Bun.password.verify(pw, hash)	根据哈希格式自动检测算法
打包器	Bun.build({ entrypoints, outdir })	树摇、代码拆分、插件、多个目标
测试运行器	import { test, expect } from "bun:test"	兼容 Jest，支持模拟、快照和监视模式
安装包	bun install	快速解析锁文件，兼容 npm
添加包	bun add <pkg>	使用 -d 添加开发依赖，使用 -g 全局安装
运行脚本	bun run <script>	运行 package.json 脚本或直接运行文件
执行二进制文件	bunx <pkg>	类似 npx，无需安装即可运行
S3 客户端	new S3Client(opts) / s3.file(key)	内置兼容 S3 的存储客户端
HTML 导入	import page from './index.html'	全栈：将 HTML 作为路由处理程序导入

常见错误

错误	正确做法
只使用 fetch 处理程序，不使用 routes	使用 routes 对象进行静态／动态路由（Bun v1.2.3+），并将 fetch 用作回退
忘记在 Bun.write() 上使用 await	Bun.write() 是异步的，务必使用 await
使用 Bun.file(path).text() 时未使用 await	.text()、.json()、.arrayBuffer() 都会返回 Promise
创建 SQLite 数据库时未启用 WAL 模式	启用 WAL 以支持并发读取：db.exec("PRAGMA journal_mode = WAL")
在 CI 中使用 bun install，但未加上 --frozen-lockfile	使用 bun install --frozen-lockfile，确保 CI 构建可重现
在 Bun 测试中导入 jest 全局变量	从 bun:test 导入，而不是从 @jest/globals 或 vitest 导入
直接使用 node_modules/.bin/	使用 bunx 或 bun run，而不是引用 bin 路径
认为 Bun.build() 失败时会抛出异常	检查 result.success 布尔值，错误信息位于 result.logs
部署到 Bun 时使用 --target node	使用 --target bun，以获得 Bun 专属优化和字节码
在请求处理程序中同步哈希密码	在服务端使用异步版本 await Bun.password.hash()

委派

• 项目脚手架：使用 Explore Agent
• 性能分析：使用 Task Agent
• 代码审查：委派给 code-reviewer Agent

如果可以使用 typescript-patterns 技能，请将高级 TypeScript 类型问题委派给它。

参考

• 运行时 API：Bun.serve()、Bun.file()、SQLite、密码哈希和实用工具
• 包管理：安装、添加、移除、工作区、锁文件
• 打包器：Bun.build()、入口点、插件、摇树优化
• 测试：bun:test、断言、模拟、快照、生命周期钩子