JavaScript API 表面

API 表面概述

Bun 的 JavaScript API 表面由多个层组成，为 JavaScript 应用程序提供全面的功能。

完整的 API 表面结构

来源

Bun 命名空间 API

全局对象Bun提供了 Bun 特有的功能，这些功能被组织成回调（函数）和 getter（属性/构造函数）。

Bun 对象结构

来源

Bun API 类别

Bun 命名空间 API 被组织成功能类别。

类别	函数	Getter
文件 I/O	`file()`、`write()`、`mmap()`	`FileSystemRouter`
HTTP/网络	`serve()`、`connect()`、`listen()`、`udpSocket()`	-
进程管理	`spawn()`、`spawnSync()`、`which()`	-
加密	`sha()`	`CryptoHasher`、`MD4`、`MD5`、`SHA1`、`SHA224`、`SHA256`、`SHA384`、`SHA512`、`SHA512_256`
压缩	`deflateSync()`、`gunzipSync()`、`gzipSync()`、`inflateSync()`、`zstdCompressSync()`、`zstdDecompressSync()`	-
实用工具	`color()`、`nanoseconds()`、`openInEditor()`、`shellEscape()`、`sleepSync()`、`stringWidth()`	`TOML`、`Glob`、`semver`、`inspect`
开发	`build()`、`jest()`、`registerMacro()`	`Transpiler`、`enableANSIColors`
内存	`allocUnsafe()`、`shrink()`	`unsafe`
运行时信息	`resolve()`、`resolveSync()`	`argv`、`cwd`、`env`、`main`、`origin`、`embeddedFiles`
I/O 流	-	`stderr`、`stdin`、`stdout`
存储/DB	-	`S3Client`、`s3`、`ValkeyClient`、`valkey`
安全	-	`CSRF`
FFI	-	`FFI`
哈希	-	`hash`

来源

Web API 和标准符合性

Bun 实现标准 Web API，以提供与浏览器环境的兼容性。

Web API 实现架构

核心 Web API

API 类别	全局对象	关键方法
流	`ReadableStream`、`WritableStream`、`TransformStream`	`pipe()`、`pipeTo()`、`tee()`
工作进程	`Worker`、`MessagePort`	`postMessage()`、`terminate()`
WebSocket	`WebSocket`	`send()`、`close()`、事件处理程序
Crypto	`crypto`、`SubtleCrypto`	`getRandomValues()`、`randomUUID()`、`subtle.*`
编码	`TextEncoder`、`TextDecoder`	`encode()`、`decode()`、`encodeInto()`
事件	`Event`、`EventTarget`、`CustomEvent`	`addEventListener()`、`dispatchEvent()`
文件	`File`、`Blob`	`arrayBuffer()`、`text()`、`stream()`
URL	`URL`、`URLSearchParams`	`parse()`，操作方法

来源

WebSocket 实现

Bun 提供客户端和服务器 WebSocket 支持。

来源

全局 API

Bun 提供无需导入即可使用的标准全局 API。

全局 API 类别

定时器和调度 API

功能	描述	返回类型
`setTimeout(handler, delay, ...args)`	延迟执行函数	`Timer`
`setInterval(handler, delay, ...args)`	重复调度函数执行	`Timer`
`setImmediate(handler, ...args)`	在当前事件循环之后调度立即执行	`Timer`
`clearTimeout(id)`	取消定时器	`void`
`clearInterval(id)`	取消间隔执行	`void`
`clearImmediate(id)`	取消立即执行	`void`
`queueMicrotask(callback)`	调度微任务在下一个 tick 执行	`void`

来源

事件系统 API

运行时环境的全局事件处理 API

来源

Process 对象 API

The process 对象提供 Node.js 兼容的进程信息和控制

进程对象结构

进程属性和方法

类别	成员	描述
命令行	`argv`, `argv0`, `execPath`, `execArgv`	命令行参数和可执行路径
环境	`env`, `cwd()`, `chdir()`, `platform`, `arch`	环境变量和系统信息
进程控制	`exit()`, `exitCode`, `pid`, `ppid`, `kill()`	进程生命周期和控制
版本	`version`, `versions`	运行时和依赖项版本信息
性能	`uptime()`, `hrtime()`, `memoryUsage()`, `cpuUsage()`, `resourceUsage()`	性能和资源监控
事件	`nextTick()`, `on()`, `emit()`, `emitWarning()`	事件系统和调度
系统	`umask()`, `title`, `binding()`, `dlopen()`	系统级操作

来源

进程环境变量

The process.env 对象提供对具有特殊行为的环境变量的访问

来源

生成的类绑定

Bun 使用自动生成的类绑定系统将 Zig 实现公开给 JavaScript

绑定生成架构

回调和 Getter 系统

绑定系统将 API 分为两类

回调（函数）

直接函数调用，例如 Bun.file(), Bun.spawn(), Bun.serve()
从 Zig 导出，命名模式为：BunObject_callback_<name>
示例：BunObject_callback_file, BunObject_callback_spawn

Getter（属性/构造函数）

惰性加载的属性，例如 Bun.TOML, Bun.CryptoHasher
从 Zig 导出，命名模式为：BunObject_getter_<name>
示例：BunObject_getter_TOML, BunObject_getter_CryptoHasher

导出注册

导出系统使用宏来注册所有 API

来源

API 集成和模块访问

API 可以通过多种模式访问

访问模式

模块导入示例

来源

模块支持

Bun 的 API 可通过全局 Bun 对象访问，或从 "bun" 模块导入

来源

Web API 兼容性

Bun 实现标准 Web API

Fetch API: fetch, Request, Response
Web Streams: ReadableStream, WritableStream, TransformStream
WebSockets: WebSocket （客户端和服务器）
Web Crypto: crypto.subtle
URL 解析: URL, URLSearchParams
编码/解码: TextEncoder, TextDecoder
定时器: setTimeout, setInterval, clearTimeout, clearInterval

来源

Node.js 兼容性

Bun 致力于与 Node.js API 兼容，以简化应用程序的移植。它实现了许多常见的 Node.js API，包括

用于文件系统操作的 fs 模块
用于路径处理的 path 模块
http 和 https 模块
crypto 模块
process 对象
用于二进制数据的 Buffer

有关 Node.js 兼容性的更多详细信息，请参阅 Node.js 兼容性。

来源

TypeScript 支持

Bun 提供 TypeScript 类型定义来描述其 API

bun-types 包提供类型定义
在 VS Code 等编辑器中自动完成
所有 Bun 特有 API 的类型

来源

可扩展性

Bun 的 API 表面可以通过多种方式扩展

插件：通过 Bun.plugin() 或 preload 配置加载
FFI：通过 Bun.FFI 调用原生代码
原生插件：Node-API 兼容的原生模块

这种可扩展性允许与系统库集成，并扩展 Bun 的内置功能。

来源