Bun作为一个基于JavaScriptCore的现代运行时，把文件读写、HTTP服务、子进程管理等能力直接挂载到全局的Bun对象上。用TypeScript开发时，如果编辑器提示找不到名称Bun，或者参数类型被推断为any，多半是因为缺少针对这些原生API的准确类型声明。本文会从创建.d.ts文件开始，演示通过declare global声明全局接口、为Bun.file和Bun.serve这类方法补充类型，并介绍模块增强和三斜线指令在适配过程中的作用。
理解Bun的全局类型声明机制
Bun的原生API大多通过全局命名空间暴露，例如Bun.file返回一个BunFile对象，Bun.serve用于启动HTTP服务器。TypeScript默认并不认识这些全局标识符，除非你安装了@types/bun或使用了官方模板。当项目没有引入第三方类型包，或者某些自定义插件在Bun对象上挂载了额外方法时，就需要手动编写声明文件。声明文件的核心是使用declare global，它允许你在模块内部扩展全局作用域。注意，一个包含import或export的文件会被视为模块，此时直接写interface Bun不会自动成为全局声明，必须放在declare global块中。
下面是一个最基本的声明文件框架，它扩展了全局BunFile接口，让编辑器知道该对象拥有name、size等属性以及text()、json()方法。
// types/bun-global.d.ts
export {};
declare global {
interface BunFile {
readonly name: string;
readonly size: number;
readonly type: string;
text(): Promise<string>;
json(): Promise<unknown>;
}
}
为什么需要export {}？因为一旦文件中出现export，TypeScript就会把该文件当作模块处理，而declare global在模块内部才能正确地向全局作用域合并声明。如果把同样的代码放到一个没有import或export的脚本文件中，declare global虽然也能工作，但所有顶层interface也会被视为全局，容易造成命名冲突。因此推荐始终把全局类型增强放在模块文件中，并用export {}显式标记模块边界。
此外，如果全局已经存在BunFile接口，上面的代码不会覆盖原有定义，而是进行接口合并。这意味着你可以只补充缺失的属性，而保留官方类型中已有的部分。这种合并特性在适配Bun这种快速迭代的运行时API时非常有用，因为官方类型可能滞后，你可以先自行补齐新方法，等官方更新后再移除自己的补充。
为Bun.file和Bun.write编写具体类型
Bun.file(path)接收一个字符串路径，返回BunFile对象；Bun.write(path, data)则把数据写入文件并返回一个Promise<number>，表示写入的字节数。如果只声明了BunFile而全局Bun对象本身还没有类型，就需要同时声明Bun接口，并把file和write方法挂上去。下面这段代码给出了一个精简但可用的声明示例。
declare global {
interface Bun {
file(path: string): BunFile;
write(path: string, data: string | Uint8Array): Promise<number>;
}
}
这里使用了interface Bun来声明方法，但实际场景中Bun可能已经被定义成了一个命名空间或变量。为了避免重复声明，通常还会加上declare var Bun: Bun来显式声明全局变量。不过要注意，如果项目中已经存在var Bun的声明，TypeScript会报重复标识符错误。此时应该检查是否安装了@types/bun，如果安装了，就不需要再写var Bun，只需用接口合并的方式补方法即可。
Bun.write的第二个参数实际上支持多种类型，包括字符串、Uint8Array、ArrayBuffer、Blob、Response以及ReadableStream。为了获得更精确的推断，可以把data参数定义成联合类型，并在返回值上保留Promise<number>。同时，Bun.write还有第三个可选参数options，它包含createPath属性，表示是否自动创建不存在的目录。一个完整的签名可以是write(path: string, data: BunWriteData, options?: BunWriteOptions): Promise<number>。按需定义这些类型可以让调用方在传错参数时立即获得编译错误提示。
另一个常用API是Bun.spawn，它用于启动子进程。下面是与之相关的类型声明示例，其中stdout和stderr使用联合字面量类型限制可选值，exitCode则声明为Promise<number>以反映异步退出状态。
interface BunSpawnOptions {
cmd: string[];
cwd?: string;
env?: Record<string, string>;
stdout?: 'pipe' | 'inherit' | 'null';
stderr?: 'pipe' | 'inherit' | 'null';
}
interface BunSubprocess {
stdout: ReadableStream<Uint8Array> | null;
stderr: ReadableStream<Uint8Array> | null;
stdin: WritableStream<Uint8Array> | null;
exitCode: Promise<number>;
kill(): void;
}
interface Bun {
spawn(options: BunSpawnOptions): BunSubprocess;
}
模块增强与三斜线指令的适配技巧
全局声明解决的是Bun对象上的方法类型问题，但Bun也支持通过模块导入的方式使用某些API，例如import { serve } from 'bun'。这种情况下，全局declare global不会自动增强模块导出，需要用到模块增强语法declare module 'bun'。模块增强允许你给指定模块补充导出类型，而不是替换原有模块声明。
下面是对bun模块进行增强的示例，为serve函数补充了ServeOptions和Server两个接口。
declare module 'bun' {
export function serve(options: ServeOptions): Server;
export interface ServeOptions {
port?: number;
hostname?: string;
fetch(request: Request): Response | Promise<Response>;
}
export interface Server {
port: number;
hostname: string;
stop(): void;
}
}
模块增强要求目标模块必须真实存在，否则TypeScript会忽略该声明。如果你在项目里并未安装对应的运行时模块，只是纯类型补充，那么建议改用全局声明或者三斜线指令引入独立的.d.ts文件。三斜线指令是一种较老的加载方式，例如/// <reference path="./bun-global.d.ts" />，它可以放在文件顶部，强制TypeScript加载指定路径的声明文件。不过在现代TypeScript工程中，更推荐使用tsconfig.json中的include和typeRoots来管理声明文件，避免手动维护三斜线指令的路径。
下面是一个典型的tsconfig.json配置，它把自定义类型目录types加入typeRoots，并通过include确保所有.ts和.d.ts文件都被编译器加载。
{
"compilerOptions": {
"strict": true,
"types": [],
"typeRoots": ["./types"]
},
"include": ["src", "types"]
}
这里"types": []的作用是禁止TypeScript自动加载node_modules/@types下的所有类型包，如果你还需要@types/node，就需要把它显式添加到types数组中。这种配置方式可以精确控制哪些全局类型生效，避免不同声明文件之间的冲突，也为Bun原生API的适配提供了干净的隔离环境。
实现完整的自定义声明文件并验证
综合前面的内容，可以创建一个完整的声明文件types/bun-native.d.ts，把文件、HTTP服务、子进程等常用API都纳入类型管理。下面的代码展示了较为完整的类型定义，包含BunFile、BunServeOptions、BunServer、BunSpawnOptions、BunSubprocess以及全局Bun接口和变量声明。
// types/bun-native.d.ts
export {};
declare global {
interface BunFile {
readonly name: string;
readonly size: number;
readonly type: string;
text(): Promise<string>;
json(): Promise<unknown>;
arrayBuffer(): Promise<ArrayBuffer>;
}
interface BunWriteOptions {
createPath?: boolean;
}
interface BunServeOptions {
port?: number;
hostname?: string;
fetch(request: Request): Response | Promise<Response>;
}
interface BunServer {
port: number;
hostname: string;
stop(): void;
}
interface BunSpawnOptions {
cmd: string[];
cwd?: string;
env?: Record<string, string>;
stdout?: 'pipe' | 'inherit' | 'null';
stderr?: 'pipe' | 'inherit' | 'null';
}
interface BunSubprocess {
stdout: ReadableStream<Uint8Array> | null;
stderr: ReadableStream<Uint8Array> | null;
stdin: WritableStream<Uint8Array> | null;
exitCode: Promise<number>;
kill(): void;
}
interface Bun {
file(path: string): BunFile;
write(path: string, data: string | Uint8Array, options?: BunWriteOptions): Promise<number>;
serve(options: BunServeOptions): BunServer;
spawn(options: BunSpawnOptions): BunSubprocess;
}
var Bun: Bun;
}
完成声明文件后，需要在项目根目录创建或修改tsconfig.json，确保include包含types目录，然后重启TypeScript语言服务器。之后可以新建一个测试文件，例如src/test.ts，写入Bun.file('data.json').json().then(data => console.log(data))，把鼠标悬停在json()上就能看到返回类型为Promise<unknown>，说明声明已经生效。
如果发现类型提示仍然缺失，首先检查声明文件路径是否被include覆盖；其次确认声明文件是否包含export {}，因为缺少模块标记时declare global可能不会按预期合并；最后检查是否存在两个同名的BunFile或Bun接口导致冲突。大多数情况下，重启编辑器或运行tsc --noEmit可以快速定位问题所在。
常见问题与注意事项
在适配Bun原生API类型时，最容易遇到的问题是与官方类型包@types/bun冲突。如果项目中已经安装了该包，就不需要再声明全局var Bun，否则会出现重复声明错误。此时正确做法是保留官方类型，只用interface Bun进行接口合并，或者通过模块增强补充官方尚未覆盖的方法。另一个常见问题是自定义声明文件未被加载，这通常和tsconfig.json的typeRoots、types以及include配置有关。建议在include中明确列出声明文件目录，并尽量避免使用exclude把该目录排除掉。
对于Bun提供的其他全局能力，比如Bun.env、Bun.randomUUID()、Bun.gc()等，也可以用相同的方式补充类型声明。你只需要在declare global中继续扩展Bun接口，添加对应的方法或属性即可。对于只在特定模式下可用的API，例如bun test提供的expect和describe，可以通过单独的声明文件并按需引入，避免污染主应用的全局类型空间。
最后要强调的是，手动维护类型声明虽然灵活，但也需要跟随Bun版本更新及时调整。建议定期对比官方类型定义，移除已经失效的接口，补充新增的API。随着项目规模扩大，你可以把这些声明整理成独立的@types包供多个项目复用，或者直接为社区贡献类型补丁。通过系统性地编写和管理类型声明，TypeScript能够在Bun这个快速演进的运行时中继续保持良好的开发体验。
TypeScriptBun类型声明修改时间：2026-10-07 00:54:09