TypeScript 与 Bun 集成指南

Bun 对 TypeScript 有着出色的原生支持，让你可以无需任何编译步骤就能直接运行 TypeScript 代码。本指南将帮助你正确设置 TypeScript 环境，以便与 Bun 无缝协作。

安装 TypeScript 类型定义

要在编辑器中获得 Bun 内置 API 的类型提示和补全功能，首先需要安装 @types/bun 类型定义包：

$ bun add -d @types/bun # 作为开发依赖安装

> `-d` 参数代表将包安装为开发依赖（devDependencies），这些依赖不会包含在生产环境中。

安装完成后，你就可以在 TypeScript 文件中直接引用 Bun 全局对象，而不会看到任何类型错误：

// 现在编辑器能正确识别 Bun 全局对象
console.log(Bun.version); // 输出当前安装的 Bun 版本

TypeScript 配置推荐

Bun 支持许多现代 JavaScript 特性，如顶级 await、JSX 语法以及带扩展名的 .ts 导入，而默认情况下 TypeScript 编译器可能不允许这些特性。下面是一份针对 Bun 项目的推荐 TypeScript 配置，可以让你无缝使用这些特性而不会收到 TypeScript 编译器的警告。

tsconfig.json

{
  "compilerOptions": {
    // 环境设置与最新特性支持
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,

    // Bundler 模式设置
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,

    // 最佳实践
    "strict": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,

    // 更严格的可选标志（默认禁用）
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noPropertyAccessFromIndexSignature": false
  }
}

配置参数说明

配置项	功能描述
lib	指定 TypeScript 可以使用的库文件，"ESNext" 表示使用最新的 ECMAScript 特性
target	指定编译后的 JavaScript 代码版本
module	代码模块化系统，"Preserve" 会保留导入语句原样
jsx	指定 JSX 代码的转换方式，"react-jsx" 用于 React 17+
moduleResolution	设置为 "bundler" 可与现代打包工具更好地协作
allowImportingTsExtensions	允许导入带 .ts 扩展名的文件
noEmit	不生成输出文件（Bun 会直接执行 TypeScript）
strict	启用所有严格类型检查选项

自动生成配置

如果你不想手动配置，可以使用 bun init 命令在新目录中自动生成上述 tsconfig.json 文件（更严格的标志默认是禁用的）：

$ bun init

INFO

关于 Bun 的 TypeScript 执行 Bun 可以直接执行 TypeScript 文件，无需额外的编译步骤。Bun 内部使用 swc（Rust 编写的超快 JavaScript 编译器）来即时转译 TypeScript 代码。

示例：创建一个简单的 TypeScript 应用

以下是一个简单的 TypeScript 应用程序示例，展示了 Bun 的类型支持：

// 文件: index.ts

// 使用 TypeScript 接口定义请求处理器
interface RequestHandler {
  (req: Request): Response | Promise<Response>;
}

// 创建一个强类型的请求处理器
const handler: RequestHandler = (req) => {
  // 访问 Bun 特有的 API
  const serverURL = new URL(req.url);
  console.log(`请求路径: ${serverURL.pathname}`);

  // 返回一个响应
  return new Response("Hello from TypeScript + Bun!", {
    headers: { "Content-Type": "text/plain" },
  });
};

// 启动 Bun 服务器
Bun.serve({
  port: 3000,
  fetch: handler,
});

console.log(`服务器运行在 http://localhost:3000`);

要运行此应用程序，只需执行：

$ bun run index.ts

使用 Bun 运行 TypeScript 文件时，不需要额外的构建或转译步骤。Bun 会自动处理 TypeScript 代码的转译。

总结

通过正确配置 TypeScript 与 Bun 的集成，你可以享受到：

• 编辑器中的自动补全和类型检查
• 直接执行 TypeScript 代码的便利性
• 现代 JavaScript 特性的支持
• 无需额外构建步骤的开发体验

这种无缝集成使得在 Bun 中使用 TypeScript 变得简单高效，特别适合希望在项目中引入类型安全的开发者。