Back

使用 Bun 搭建 TypeScript 应用

OpenReplay Team OpenReplay Team

Mar 21, 2026 · 2 min read

使用 Bun 搭建 TypeScript 应用

如果你一直在用 Node.js 管理 TypeScript 项目,你一定深有体会:安装 ts-node 或 tsx,配置构建步骤,设置脚本,然后才能开始写代码。Bun 消除了大部分这些繁琐操作。它是一个现代化的 JavaScript 运行时,可以直接运行 TypeScript 文件,内置包管理器,还能充当任务运行器——所有功能集于一身。本指南将带你完整地搭建一个 Bun TypeScript 项目,让你在几分钟内从零开始运行 TypeScript。

核心要点

  • Bun 原生支持在运行时转译 TypeScript,无需 ts-node、tsx 或单独的构建步骤。
  • 单条 bun init 命令即可搭建一个开箱即用的 TypeScript 项目,包含 tsconfig.json 和 Bun 锁文件(bun.lock)。
  • Bun 的转译器会剥离类型注解以提升速度,但不执行类型检查——需要单独运行 tsc --noEmit 来捕获类型错误。
  • 在 tsconfig.json 中设置 "moduleResolution": "bundler" 可使 TypeScript 的模块解析与 Bun 的内部行为保持一致。

什么是 Bun?为什么用它开发 TypeScript?

Bun 是一个基于 JavaScriptCore 构建、使用 Zig 编写的高性能 JavaScript 运行时。它在 TypeScript 开发中的突出优势在于能够原生地在运行时转译 .ts 和 .tsx 文件——无需单独的构建步骤。与 Node.js + ts-node 的组合不同,Bun 在内部处理转译,这意味着明显更快的启动时间和更简洁的开发工作流。

除了运行时功能,Bun 还一次性替代了多个工具:

  • 运行时 – 直接执行 TypeScript 和 JavaScript
  • 包管理器 – 比 npm、yarn 或 pnpm 更快的替代方案
  • 任务运行器 – 运行 package.json 中定义的脚本

创建新的 Bun TypeScript 项目

首先安装 Bun,然后搭建一个新项目:

bun init

Bun 会提示你输入入口点。使用 src/index.ts 来保持项目结构清晰:

entry point (index.ts): src/index.ts

这将生成一个最小化的项目结构:

my-app/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── bun.lock

bun.lock 文件是 Bun 的依赖锁文件,由 Bun 的包管理器使用以确保一致的安装。

安装 Bun 类型定义

如果项目中尚未包含 @types/bun,请将其作为开发依赖安装,以获得 Bun 特定 API 的正确 IntelliSense 和类型检查:

bun add -d @types/bun

这样你就能获得 Bun 内置 API 的类型支持,如 Bun.serve()、Bun.file() 和 bun:sqlite。更多详情请参阅官方 Bun TypeScript 文档。

Bun 项目推荐的 tsconfig.json 配置

Bun 可以在没有 tsconfig.json 的情况下工作,但为了获得 IDE 支持和类型检查,你需要配置一个。Bun TypeScript 配置的关键设置是 "moduleResolution": "bundler",这与 Bun 内部解析模块的方式保持一致。

其他需要包含的重要选项:

  • "target": "ESNext" 和 "lib": ["ESNext"] — 使用现代 JavaScript 特性
  • "strict": true — 尽早捕获错误
  • "noEmit": true — Bun 处理执行,因此不需要编译输出
  • "verbatimModuleSyntax": true — 确保纯类型导入的清晰性
  • "allowImportingTsExtensions": true — 允许导入带扩展名的 .ts 文件

以下是完整示例:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ESNext"],
    "strict": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

⚠️ 重要提示: Bun 的转译器会剥离类型注解以提升速度——它不会在运行时执行完整的类型检查。在开发过程中或在 CI 中单独运行 bunx tsc --noEmit 来捕获类型错误。

运行 TypeScript 文件和管理脚本

使用 Bun 运行 TypeScript 文件非常简单:

bun run src/index.ts

在开发过程中如需文件更改时自动重启,可使用监听模式:

bun --watch src/index.ts

将常用工作流添加到 package.json 脚本中:

{
  "scripts": {
    "dev": "bun --watch src/index.ts",
    "start": "bun run src/index.ts",
    "typecheck": "bunx tsc --noEmit"
  }
}

Bun 直接运行这些脚本——无需额外的任务运行器。

Bun 的其他功能

一旦 Bun TypeScript 项目搭建完成,你就可以访问多个内置功能,无需添加额外依赖:

  • 测试运行器 — bun test 开箱即支持兼容 Jest 的 API
  • 打包工具 — bun build 处理前端资源打包
  • SQLite — bun:sqlite 提供原生的类型化数据库接口

这些功能对于基础设置不是必需的,但在你需要时随时可用。你可以在官方 Bun 文档中探索完整的功能集。

总结

使用 Bun 开发 TypeScript 的主要转变在于接受运行时处理转译而 tsc 处理类型安全——它们是两个独立的关注点。一旦理解了这一点,工作流就会变得清晰:初始化项目,根据需要安装 @types/bun,使用打包器风格的模块解析配置 tsconfig.json,然后直接运行 TypeScript 文件。无需维护构建管道,无需安装额外工具。

常见问题

不会。Bun 在转译过程中会剥离类型注解以提升速度,但不运行 TypeScript 类型检查器。你需要单独运行带 noEmit 标志的 tsc,可以在开发过程中或作为 CI 流程的一部分,以在错误进入生产环境之前捕获类型错误。

可以。Bun 的包管理器完全兼容 npm 仓库。你可以使用 bun add 安装包,就像使用 npm install 一样。大多数适用于 Node.js 的包都可以在 Bun 中使用,但依赖 Node 特定原生插件的包可能存在兼容性限制。

Bun 于 2023 年 9 月发布了 1.0 版本,此后一直保持定期稳定版本发布。许多团队在生产环境中使用它,但你应该测试特定的依赖项和工作负载。Node.js API 兼容性很广泛但尚未完全覆盖,因此请验证项目所依赖的任何 Node 特定 API。

Bun 通常比使用 ts-node 或 tsx 的 Node.js 启动更快,因为它原生转译 TypeScript,无需单独的编译步骤。由于其优化的解析器和安装系统,包安装速度也明显更快。实际运行时性能因工作负载而异,但启动时间的改进始终很明显。

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.

OpenReplay

More articles from OpenReplay Blog