bun

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bun

Specification

规范

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

<prerequisite> You MUST load `javascript` first for language, module, async, and code-navigation conventions. You MUST load `typescript` too when editing TypeScript, type definitions, or tsconfig. </prerequisite>

Use Bun deliberately. Prefer Bun-native APIs in Bun-first projects, but do not break portability by accident.

Bun is an all-in-one JavaScript and TypeScript toolkit: runtime, package manager, test runner, bundler, and script runner. In projects that intentionally target Bun, you SHOULD prefer Bun-native APIs such as

Bun.serve

Bun.file

Bun.write

Bun.$

Bun.spawn

bun:sqlite

, and

bun:test

. In existing Node-compatible projects, you MUST respect the established portability contract and only introduce Bun-specific APIs when the project is already Bun-targeted or the user asks for Bun-specific implementation.

MUST

、

MUST NOT

、

REQUIRED

、

SHALL

、

SHALL NOT

、

SHOULD

、

SHOULD NOT

、

RECOMMENDED

、

MAY

和

OPTIONAL

这些词汇的解释遵循RFC 2119中的规定。

<prerequisite> 在使用语言、模块、异步及代码导航约定前，你必须先加载`javascript`。当编辑TypeScript、类型定义或tsconfig时，你还必须加载`typescript`。 </prerequisite>

谨慎使用Bun。在优先采用Bun的项目中，建议使用Bun原生API，但切勿意外破坏可移植性。

Bun是一款一体化的JavaScript和TypeScript工具包：包含运行时、包管理器、测试运行器、打包工具及脚本运行器。在明确以Bun为目标环境的项目中，你应当优先使用Bun原生API，例如

Bun.serve

、

Bun.file

、

Bun.write

、

Bun.$

、

Bun.spawn

、

bun:sqlite

和

bun:test

。在现有兼容Node的项目中，你必须遵守已有的可移植性约定，仅当项目已明确以Bun为目标环境或用户要求实现Bun特定功能时，才可引入Bun专属API。

References

参考文档

Topic	Reference	Load when
HTTP server and routing	`references/server.md`	Building `Bun.serve` apps, routes, cookies, WebSockets, static/file responses
File I/O, shell, and processes	`references/io-and-processes.md`	Using `Bun.file` , `Bun.write` , `Bun.$` , `Bun.spawn` , workers
Testing	`references/testing.md`	Writing `bun:test` tests, mocks, snapshots, coverage, type checks
SQLite, bundler, macros, utilities	`references/ecosystem.md`	Using `bun:sqlite` , `Bun.build` , plugins, macros, passwords, hashing
Configuration and compatibility	`references/config-and-compat.md`	`bunfig.toml` , package manager behavior, Node compatibility, install strategy

主题	参考文档	加载时机
HTTP服务器与路由	`references/server.md`	构建 `Bun.serve` 应用、路由、Cookie、WebSocket、静态/文件响应时
文件I/O、Shell与进程	`references/io-and-processes.md`	使用 `Bun.file` 、 `Bun.write` 、 `Bun.$` 、 `Bun.spawn` 、工作进程时
测试	`references/testing.md`	编写 `bun:test` 测试、模拟、快照、覆盖率、类型检查时
SQLite、打包工具、宏、实用工具	`references/ecosystem.md`	使用 `bun:sqlite` 、 `Bun.build` 、插件、宏、密码、哈希时
配置与兼容性	`references/config-and-compat.md`	处理 `bunfig.toml` 、包管理器行为、Node兼容性、安装策略时

Runtime Preferences

运行时偏好

Bun-first projects SHOULD use
```
Bun.serve()
```
for HTTP servers,
```
Bun.file()
```
/
```
Bun.write()
```
for file reads and writes,
```
Bun.$
```
for shell commands,
```
Bun.spawn()
```
for child processes,
```
bun:test
```
for tests, and
```
bun:sqlite
```
for SQLite.
Node-compatible projects MAY keep
```
node:*
```
APIs when portability matters, the local codebase already standardizes on them, or Bun has no native equivalent.
Directory traversal and directory creation SHOULD use
```
node:fs/promises
```
unless a Bun-native API has been adopted in the project.
Web-standard APIs such as
```
fetch
```
,
```
Request
```
,
```
Response
```
,
```
ReadableStream
```
,
```
Blob
```
, and
```
AbortController
```
SHOULD be preferred over Node-only abstractions when they fit.
Existing codebase conventions MUST win over this skill. If a convention conflicts, follow the project locally and flag the divergence once.

优先采用Bun的项目应当使用
```
Bun.serve()
```
搭建HTTP服务器，使用
```
Bun.file()
```
/
```
Bun.write()
```
进行文件读写，使用
```
Bun.$
```
执行Shell命令，使用
```
Bun.spawn()
```
创建子进程，使用
```
bun:test
```
进行测试，使用
```
bun:sqlite
```
操作SQLite。
兼容Node的项目在需要保证可移植性、本地代码库已标准化使用
```
node:*
```
API，或Bun无对应原生API时，可保留
```
node:*
```
API。
目录遍历和目录创建应当使用
```
node:fs/promises
```
，除非项目已采用Bun原生API。
当适用时，应当优先使用Web标准API（如
```
fetch
```
、
```
Request
```
、
```
Response
```
、
```
ReadableStream
```
、
```
Blob
```
和
```
AbortController
```
），而非仅Node支持的抽象。
现有代码库的约定优先级高于本规范。若存在冲突，应遵循项目本地约定，并仅标记一次差异。

Server

服务器

New Bun HTTP servers SHOULD use
```
Bun.serve({ routes })
```
for declarative routing.
```
fetch
```
SHOULD be used as fallback handling for unmatched routes or for lower-level control such as WebSocket upgrades.
Route handlers SHOULD return
```
Response
```
or
```
Promise<Response>
```
.
```
Bun.serve()
```
SHOULD include an
```
error
```
handler for production-facing servers.
Static
```
Response
```
routes SHOULD be used for health checks, redirects, and fixed JSON responses.
File responses SHOULD choose deliberately between buffering into a static response and returning
```
new Response(Bun.file(path))
```
.

新的Bun HTTP服务器应当使用
```
Bun.serve({ routes })
```
实现声明式路由。
对于未匹配的路由或需要更底层控制（如WebSocket升级）的场景，应当使用
```
fetch
```
作为回退处理方式。
路由处理器应当返回
```
Response
```
或
```
Promise<Response>
```
。
面向生产环境的服务器，其
```
Bun.serve()
```
应当包含
```
error
```
处理函数。
健康检查、重定向和固定JSON响应应当使用静态
```
Response
```
路由。
文件响应应当谨慎选择：是缓冲为静态响应，还是返回
```
new Response(Bun.file(path))
```
。

Package Manager

包管理器

You MUST use the package manager configured by the project. If the project uses Bun or has no established package manager, you SHOULD use Bun commands.
New installs SHOULD use the text
```
bun.lock
```
lockfile. Old
```
bun.lockb
```
projects SHOULD be migrated only when the user asks or the task already requires lockfile work.
CI and reproducible installs SHOULD use
```
bun install --frozen-lockfile
```
.
Dependency lifecycle scripts MUST NOT be trusted casually. Use
```
trustedDependencies
```
or
```
bun pm trust <pkg>
```
only after confirming the package actually requires its install script.
New monorepos SHOULD use isolated installs unless the project requires hoisting. New single-package projects SHOULD use hoisted installs. Existing projects SHOULD preserve their current linker strategy.
Security-sensitive dependency updates SHOULD consider
```
--minimum-release-age
```
to avoid newly published malicious package versions.

你必须使用项目配置的包管理器。若项目使用Bun或未指定包管理器，你应当使用Bun命令。
新安装项目应当使用
```
bun.lock
```
锁文件。仅当用户要求或任务本身需要处理锁文件时，才需迁移旧的
```
bun.lockb
```
项目。
CI环境和可复现安装应当使用
```
bun install --frozen-lockfile
```
。
切勿随意信任依赖的生命周期脚本。仅在确认包确实需要其安装脚本时，才可使用
```
trustedDependencies
```
或
```
bun pm trust <pkg>
```
。
新的单体仓库应当使用隔离安装，除非项目需要提升依赖。新的单包项目应当使用提升安装。现有项目应当保留其当前的链接策略。
对安全性敏感的依赖更新应当考虑使用
```
--minimum-release-age
```
，以避免引入刚发布的恶意包版本。

Testing And Tooling

测试与工具

Bun-targeted tests SHOULD use
```
bun:test
```
, not Jest or Vitest, unless the project already standardizes elsewhere.
Test files SHOULD import test APIs from
```
bun:test
```
.
Mocks SHOULD be restored or cleared in
```
afterEach
```
when state can leak across tests.
Type assertions from
```
expectTypeOf
```
MUST be paired with a real type-check command such as
```
bunx tsc --noEmit
```
when type correctness is the thing being verified.
Do not run long-lived dev servers or build commands unless the user explicitly asks or approves.

以Bun为目标环境的测试应当使用
```
bun:test
```
，而非Jest或Vitest，除非项目已标准化使用其他测试框架。
测试文件应当从
```
bun:test
```
导入测试API。
当状态可能在测试间泄漏时，应当在
```
afterEach
```
中恢复或清除模拟。
当验证类型正确性时，
```
expectTypeOf
```
的类型断言必须与真实的类型检查命令（如
```
bunx tsc --noEmit
```
）配合使用。
除非用户明确要求或批准，否则不要运行长期运行的开发服务器或构建命令。

Bundler And Macros

打包工具与宏

```
Bun.build()
```
SHOULD check
```
result.success
```
and inspect
```
result.logs
```
on failure.
Build targets MUST match the runtime:
```
"bun"
```
for Bun apps,
```
"browser"
```
for browser bundles,
```
"node"
```
for Node output.
Macros are advanced bundler behavior. They SHOULD be used sparingly for small bundle-time computations that replace otherwise separate build scripts.
Macro imports MUST use import attributes such as
```
with { type: "macro" }
```
; do not introduce the older assertion syntax in new code.
Macro return values MUST be serializable by Bun's transpiler, and macro inputs MUST be statically knowable at bundle time.
Macros MUST NOT be treated as runtime imports; they execute at bundle time and carry supply-chain/security risk.

```
Bun.build()
```
应当检查
```
result.success
```
，并在失败时查看
```
result.logs
```
。
构建目标必须与运行时匹配：Bun应用使用
```
"bun"
```
，浏览器包使用
```
"browser"
```
，Node输出使用
```
"node"
```
。
宏是高级打包工具特性。应当仅将其用于小型打包时计算，以替代原本独立的构建脚本。
宏导入必须使用导入属性（如
```
with { type: "macro" }
```
）；请勿在新代码中引入旧的断言语法。
宏的返回值必须可被Bun的转译器序列化，且宏的输入必须在打包时即可静态确定。
宏不得被视为运行时导入；它们在打包时执行，存在供应链/安全风险。

Application

实践应用

When writing Bun code:

You MUST apply these conventions without narrating each one.
You MUST preserve project portability unless the project is intentionally Bun-targeted.
You SHOULD use Bun-native APIs for new Bun-targeted code.
You MUST keep behavior equivalent when migrating from Node-compatible APIs to Bun-native APIs.

When reviewing Bun code:

You MUST lead with concrete portability, runtime, install, security, or testing risks.
You SHOULD show the smallest Bun-native correction inline.
You MUST distinguish Bun-specific preferences from issues that would affect any JavaScript runtime.

编写Bun代码时：

你必须遵循这些约定，无需逐一说明。
除非项目明确以Bun为目标环境，否则必须保持项目的可移植性。
对于新的Bun目标代码，应当使用Bun原生API。
从兼容Node的API迁移到Bun原生API时，必须保持行为一致。

审查Bun代码时：

你必须首先指出具体的可移植性、运行时、安装、安全或测试风险。
你应当在代码中展示最小化的Bun原生修正方案。
你必须区分Bun特定偏好与会影响所有JavaScript运行时的问题。