TypeScript – 运行时 | Bun 文档

Bun 将 TypeScript 视为一等公民。

注意 — 要为 Bun API（如 Bun 全局对象）添加类型声明，请按照简介 > TypeScript 中的说明进行操作。此页面介绍 Bun 运行时如何运行 TypeScript 代码。

运行 `.ts` 文件

Bun 可以像普通的 JavaScript 一样直接执行 .ts 和 .tsx 文件，无需额外配置。如果您导入 .ts 或 .tsx 文件（或导出这些文件的 npm 模块），Bun 会在内部将其转译为 JavaScript，然后执行该文件。

注意 — 与其他构建工具类似，Bun 不会对文件进行类型检查。如果您希望捕获静态类型错误，请使用 tsc（官方 TypeScript CLI）。

转译仍然是必要的吗？ — 因为 Bun 可以直接执行 TypeScript，所以您可能不需要转译 TypeScript 即可在生产环境中运行。Bun 在内部转译它执行的每个文件（包括 .js 和 .ts），因此直接执行 .ts/.tsx 源文件的额外开销可以忽略不计。

也就是说，如果您将 Bun 用作开发工具，但在生产环境中仍然以 Node.js 或浏览器为目标，那么您仍然需要转译。

路径映射

在解析模块时，Bun 的运行时会遵循在您的 tsconfig.json 中的 compilerOptions.paths 中定义的路径映射。没有其他运行时会这样做。

考虑以下 tsconfig.json。

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "data": ["./data.ts"]
    }
  }
}

Bun 将使用 baseUrl 来解析模块路径。

// resolves to ./src/components/Button.tsx
import { Button } from "components/Button.tsx";

Bun 也会正确解析来自 "data" 的导入。

index.ts

data.ts

index.ts
import { foo } from "data";
console.log(foo); // => "Hello world!"

data.ts
export const foo = "Hello world!"

实验性装饰器

Bun 支持 TypeScript 5.0 之前的实验性装饰器语法。

hello.ts
// Simple logging decorator
function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function(...args: any[]) {
    console.log(`Calling ${propertyKey} with:`, args);
    return originalMethod.apply(this, args);
  };
}

class Example {
  @log
  greet(name: string) {
    return `Hello ${name}!`;
  }
}

// Usage
const example = new Example();
example.greet("world"); // Logs: "Calling greet with: ['world']"

要启用它，请将 "experimentalDecorators": true 添加到您的 tsconfig.json 中

tsconfig.json
{
  "compilerOptions": {
    // ... rest of your config
    "experimentalDecorators": true,
  },
}

我们通常不建议在新代码库中使用它，但是许多现有的代码库已经开始依赖它。

emitDecoratorMetadata

Bun 支持在您的 tsconfig.json 中使用 emitDecoratorMetadata。这允许为源文件中带装饰器的声明发出设计时类型元数据。

emit-decorator-metadata.ts
import "reflect-metadata";

class User {
  id: number;
  name: string;
}

function Injectable(target: Function) {
  // Get metadata about constructor parameters
  const params = Reflect.getMetadata("design:paramtypes", target);
  console.log("Dependencies:", params); // [User]
}

@Injectable
class UserService {
  constructor(private user: User) {}
}

// Creates new UserService instance with dependencies
const container = new UserService(new User());

要启用它，请将 "emitDecoratorMetadata": true 添加到您的 tsconfig.json 中

tsconfig.json
{
  "compilerOptions": {
    // ... rest of your config
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
  },
}

运行 .ts 文件

路径映射

实验性装饰器

emitDecoratorMetadata

运行 `.ts` 文件