Bun 命名空间 API

相关源文件

• packages/bun-types/bun.d.ts
• packages/bun-types/globals.d.ts
• src/bun.js/api/BunObject.zig
• src/bun.js/bindings/BunObject+exports.h
• src/bun.js/bindings/BunObject.cpp
• src/bun.js/bindings/BunProcess.cpp
• src/bun.js/bindings/BunProcess.h
• src/bun.js/bindings/helpers.cpp
• src/bun.js/bindings/helpers.h
• test/js/node/process/process.test.js
• test/js/node/test/parallel/test-process-setsourcemapsenabled.js
• test/js/node/test/parallel/test-resource-usage.js

The Bun 命名空间 API 通过全局 Bun 对象和 "bun" 模块公开 Bun 特定的功能。此命名空间提供了 Bun 运行时功能的主要 JavaScript 接口，包括文件 I/O、HTTP 服务、打包、进程管理以及标准 JavaScript 或 Node.js 中不可用的各种实用程序。

The Bun 对象实现为一个在 BunObject 结构中定义的函数和 getter 属性的集合，并为开发工具提供了 TypeScript 定义。

有关 Bun 中实现的 Web API 的信息，请参阅 Web APIs and Standards Compliance。

API 表面概述

核心 Bun 命名空间结构

The Bun 命名空间通过系统化的实现模式公开了大约 40 多个函数和 30 多个 getter 属性。

来源：packages/bun-types/bun.d.ts16-657 src/bun.js/api/BunObject.zig9-81

实现架构

代码实体映射

The Bun 命名空间实现遵循三层架构，将 JavaScript 连接到原生代码。

来源：src/bun.js/api/BunObject.zig9-45 src/bun.js/bindings/BunObject.cpp39-95 src/bun.js/bindings/BunObject+exports.h4-83

实现模式

命名空间遵循系统模式，其中每个 API 都通过以下两种机制之一实现：

模式	用途	实现函数	导出宏
回调函数	函数调用，如 Bun.file()	toJSCallback()	FOR_EACH_CALLBACK
Getters	属性访问，如 Bun.env	toJSGetter()	FOR_EACH_GETTER

来源：src/bun.js/api/BunObject.zig91-101 src/bun.js/bindings/BunObject+exports.h40-83

核心组件

核心 API 类别

文件系统操作

The file system APIs in the Bun 命名空间通过 WebCore.Blob.constructBunFile 和 JSC.WebCore.Blob.writeFile 实现。

核心文件 API 函数

功能	实现	目的
Bun.file()	WebCore.Blob.constructBunFile	创建 BunFile 实例
Bun.write()	JSC.WebCore.Blob.writeFile	高效写入数据到文件
Bun.mmap()	Bun.mmapFile	内存映射文件以实现高效读取

来源：packages/bun-types/bun.d.ts642-778 src/bun.js/api/BunObject.zig18-40

HTTP 服务器和网络

The HTTP server APIs are implemented through Bun.serve and networking functions through the api.Listener class.

核心网络函数

功能	实现	目的
Bun.serve()	Bun.serve	创建 HTTP/WebSocket 服务器
Bun.connect()	api.Listener.connect	创建 TCP 客户端连接
Bun.listen()	api.Listener.listen	创建 TCP 服务器
Bun.udpSocket()	api.UDPSocket.udpSocket	创建 UDP 套接字

来源：packages/bun-types/bun.d.ts2481-2732 src/bun.js/api/BunObject.zig14-38

Bundler 和 Build API

The bundler API is implemented through Bun.JSBundler.buildFn and provides access to Bun's JavaScript/TypeScript bundling capabilities.

核心构建函数

功能	实现	目的
Bun.build()	Bun.JSBundler.buildFn	打包 JavaScript/TypeScript 文件
Bun.Transpiler	Bun.getTranspilerConstructor	转译单个文件

来源：packages/bun-types/bun.d.ts1733-2109 src/bun.js/api/BunObject.zig12-63

进程管理

Process-related APIs provide subprocess spawning and system utilities through various implementations.

实用函数

Utility APIs provide various helper functions for common operations.

类别	功能	实现	目的
系统	Bun.which()	Bun.which	查找可执行文件路径
时间点	Bun.sleepSync()	Bun.sleepSync	同步睡眠
时间点	Bun.nanoseconds()	Bun.nanoseconds	高精度计时
文本	Bun.stringWidth()	Bun.stringWidth	终端字符串宽度
内存	Bun.allocUnsafe()	Bun.allocUnsafe	不安全内存分配
内存	Bun.shrink()	Bun.shrink	内存优化
异步	Bun.peek()	Bun.peek	Promise 值提取
转义	Bun.shellEscape()	Bun.shellEscape	Shell 字符串转义

来源：packages/bun-types/bun.d.ts520-597 src/bun.js/api/BunObject.zig26-39

密码学函数

Cryptographic APIs provide hashing and security functions through the Crypto module implementations.

核心加密函数

功能	实现	目的
Bun.CryptoHasher	Crypto.CryptoHasher.getter	通用哈希构造函数
Bun.SHA256	Crypto.SHA256.getter	SHA-256 哈希构造函数
Bun.hash	Bun.getHashObject	非加密哈希函数
Bun.sha()	Crypto.SHA512_256.hash_	直接哈希计算

来源：packages/bun-types/bun.d.ts3260-3400 src/bun.js/api/BunObject.zig32-68

专用 API

Additional APIs provide access to various Bun-specific features and integrations.

专用 API 函数

类别	功能	实现	目的
配置	Bun.TOML	Bun.getTOMLObject	TOML 文件解析
FFI	Bun.FFI	Bun.FFIObject.getter	外部函数接口
安全	Bun.CSRF	Bun.getCSRFObject	CSRF 令牌生成
存储	Bun.S3Client	Bun.getS3ClientConstructor	AWS S3 客户端
存储	Bun.s3	Bun.getS3DefaultClient	默认 S3 实例
数据库	Bun.ValkeyClient	Bun.getValkeyClientConstructor	Valkey Redis 客户端
数据库	Bun.valkey	Bun.getValkeyDefaultClient	默认 Valkey 实例
路由	Bun.FileSystemRouter	Bun.getFileSystemRouter	基于文件的路由
文件	Bun.Glob	Bun.getGlobConstructor	文件模式匹配
调试	Bun.inspect	Bun.getInspect	值检查

来源：packages/bun-types/bun.d.ts601-612 src/bun.js/api/BunObject.zig50-80

实现细节

代码生成模式

The BunObject implementation uses a systematic code generation pattern connecting TypeScript definitions to native implementations.

实现层

层	文件	目的	关键函数
TypeScript	bun.d.ts	API 定义	类型信息
Zig	BunObject.zig	核心实现	toJSCallback(), toJSGetter()
C++ Headers	BunObject+exports.h	导出宏	FOR_EACH_CALLBACK, FOR_EACH_GETTER
C++ Bindings	BunObject.cpp	JSC 集成	@begin bunObjectTable

来源： src/bun.js/api/BunObject.zig103-180 src/bun.js/bindings/BunObject+exports.h4-98 src/bun.js/bindings/BunObject.cpp39-900

压缩和流

压缩 API

Bun 通过各种算法提供同步和异步的压缩函数。

流实用工具

用于处理 ReadableStreams 和数据转换的流处理实用工具。

功能	实现	目的
Bun.readableStreamToArrayBuffer()	内置	将流转换为 ArrayBuffer
Bun.readableStreamToText()	内置	将流转换为字符串
Bun.readableStreamToJSON()	内置	将流转换为 JSON
Bun.readableStreamToBlob()	内置	将流转换为 Blob
Bun.readableStreamToArray()	内置	将流转换为数组
Bun.concatArrayBuffers()	内置	连接多个缓冲区

来源： packages/bun-types/bun.d.ts817-928 src/bun.js/api/BunObject.zig17-44

API 参考摘要

完整函数索引

API	类型	实现	类别
allocUnsafe	回调	Bun.allocUnsafe	内存
build	回调	Bun.JSBundler.buildFn	打包
color	回调	bun.css.CssColor.jsFunctionColor	实用工具
connect	回调	api.Listener.connect	网络
file	回调	WebCore.Blob.constructBunFile	文件系统
serve	回调	Bun.serve	网络
spawn	回调	api.Subprocess.spawn	进程
which	回调	Bun.which	实用工具
write	回调	JSC.WebCore.Blob.writeFile	文件系统
argv	Getter	Bun.getArgv	进程
env	Getter	进程环境变量	进程
main	Getter	Bun.getMain	进程
CryptoHasher	Getter	Crypto.CryptoHasher.getter	加密
FFI	Getter	Bun.FFIObject.getter	FFI
TOML	Getter	Bun.getTOMLObject	实用工具

来源： src/bun.js/api/BunObject.zig10-80 src/bun.js/bindings/BunObject+exports.h40-83

Shell API

Bun 命名空间通过 Bun.$ 包含了一个强大的 shell 脚本 API。

来源： packages/bun-types/shell.d.ts1-200

流和缓冲区实用工具

Bun 提供用于处理流和缓冲区的实用工具

来源： packages/bun-types/bun.d.ts793-1004

实现细节

Bun 命名空间的实现是通过 Zig 和 C++ 代码结合实现的。Zig 中的 BunObject 结构定义了暴露给 JavaScript 的回调和 getter。

• 回调是直接函数调用（例如 Bun.file()）。
• Getter 提供属性访问（例如 Bun.env）。

这些通过 BunObject+exports.h 中定义的宏导出，然后用 C++ 包装以提供 JavaScript 接口。

该系统使用 JavaScriptCore 引擎将这些原生函数绑定到 JavaScript 环境，使其可以通过全局 Bun 对象进行访问。

来源： src/bun.js/api/BunObject.zig9-98 src/bun.js/bindings/BunObject+exports.h4-77

使用示例

文件操作

HTTP 服务器

构建代码

Shell 命令

来源： packages/bun-types/bun.d.ts1-15 test/integration/bun-types/fixture/index.ts100-110

总结

Bun 命名空间 API 提供了一套全面的实用工具和函数，通过 Bun 特有的功能扩展了标准的 JavaScript 环境。从文件操作到 HTTP 服务器，从加密到 shell 命令，全局 Bun 对象是访问 Bun 独特功能和优化的入口。

该实现混合了 Zig 和 C++ 代码，通过 JavaScriptCore 绑定桥接到 JavaScript，并提供 TypeScript 定义为开发人员提供强类型安全。