TypeScript 6 与 tsgo 实战：Go 编译器带来的 10 倍速度革命

TypeScript 6.0 的发布标志着 TypeScript 历史上最大的架构变革——用 Go 语言重写的原生编译器 tsgo 正式随 TypeScript 一起发布。根据微软官方基准测试，tsgo 在 VS Code 代码库（约 300 万行代码）上的编译速度比传统 tsc 快 10.4 倍，在 Sentry 代码库上快 13.8 倍。对于任何超过 10 万行的 TypeScript 项目来说，这不再是「锦上添花」，而是直接决定了开发体验和 CI 成本的「生死线」。

📌 记住： TypeScript 6 不仅仅是「更快的编译器」。它引入的 isolatedDeclarations、改进的 satisfies 推断、以及全新的 tsc --init 配置模板，都在从不同维度重塑 TypeScript 的工程化实践。

🚀 一、tsgo 原生编译器：为什么 Go 比 JavaScript 快一个量级？

1.1 tsgo 的架构设计

tsgo 并不是简单地把 TypeScript 编译器的 JavaScript 代码翻译成 Go。它重新设计了整个编译流水线（Pipeline），核心优化点包括：

• 并行类型检查：Go 的 goroutine 天然支持并发，tsgo 将不同文件的类型检查分配到多个 CPU 核心，而 tsc 只能用单线程
• 增量编译：tsgo 维护了一棵持久化的类型依赖图（Dependency Graph），只重新检查受变更影响的文件
• 零 GC 停顿：Go 的垃圾回收器暂停时间在微秒级别，而 V8 的 GC 在大型项目中可能产生数百毫秒的停顿
• 原生 JSON 解析：不再依赖 Node.js 的 JSON.parse，直接用 Go 的 encoding/json 解析 tsconfig.json

1.2 性能基准对比

以下数据来自微软 TypeScript 团队在 2026 年 Build 大会上公布的官方基准测试：

⚡ 关键结论： 项目越大，tsgo 的加速比越高。对于超过 50 万行的大型 monorepo，tsgo 能将 CI 编译时间从「分钟级」压缩到「秒级」，直接节省大量的 CI 计算资源。

1.3 如何在项目中启用 tsgo

tsgo 随 TypeScript 6.0 一起发布，但目前以独立二进制文件的形式存在，命令行用法与 tsc 几乎一致：

# 安装 TypeScript 6
npm install -D typescript@6

# 使用传统 tsc 编译（仍然可用）
npx tsc --noEmit

# 使用 tsgo 原生编译器
npx tsgo --noEmit

# 启用增量编译（生成 .tsbuildinfo 缓存）
npx tsgo --noEmit --incremental

# 与 watch 模式配合
npx tsgo --noEmit --watch

💡 提示： tsgo 目前不支持所有 tsc 的编译选项（比如 --declaration 的某些边缘场景），但它已经覆盖了 95% 以上的日常开发用法。微软的路线图显示，tsgo 将在 TypeScript 7.0 中完全替代 tsc。

🔐 二、isolatedDeclarations：解耦类型声明与实现

2.1 问题背景：为什么 .d.ts 生成是构建瓶颈？

在大型 monorepo 中，一个常见的痛点是 .d.ts 类型声明文件的生成。传统的 TypeScript 编译器在生成 .d.ts 时需要完整的类型检查——它必须分析整个依赖链才能确定一个函数的返回类型。这意味着即使你只想生成声明文件，也需要等所有上游依赖编译完成。

isolatedDeclarations 是 TypeScript 6 引入的一个新编译选项，它要求每个文件的类型声明可以独立推导，不需要查看其他文件的实现。

// ❌ 旧模式：返回类型依赖跨文件推断
// utils.ts
import { createModel } from './models'
export function getUser() {
  // TypeScript 需要查看 createModel 的实现才知道返回类型
  return createModel({ name: 'Alice', age: 30 })
}

// ✅ isolatedDeclarations 模式：显式标注返回类型
// utils.ts
import { createModel } from './models'
import type { UserModel } from './models'
export function getUser(): UserModel {
  return createModel({ name: 'Alice', age: 30 })
}

2.2 为什么这个改变意义重大？

isolatedDeclarations 的核心价值在于解耦。当每个文件的声明独立于其他文件时：

• ✅ .d.ts 生成可以用更轻量的工具（如 tsgo --declaration --isolatedDeclarations）完成，无需完整类型检查
• ✅ 不同包可以并行生成声明文件，大幅缩短 monorepo 的构建时间
• ✅ 第三方打包工具（如 esbuild、Rollup）可以直接生成 .d.ts，不需要依赖完整的 TypeScript 编译器

在 Strapi 团队的实际测试中，启用 isolatedDeclarations 后，monorepo 的 .d.ts 生成时间从 45 秒降低到 8 秒。

// tsconfig.json
{
  "compilerOptions": {
    "isolatedDeclarations": true,
    "declaration": true,
    "declarationDir": "./dist/types"
  }
}

2.3 迁移痛点与解决方案

启用 isolatedDeclarations 后，你可能会遇到大量错误——TypeScript 会标出所有「无法独立推导类型」的位置。最常见的两种情况：

// ❌ 错误：对象字面量的类型需要上下文推断
export const config = {
  port: 3000,
  host: 'localhost',
  debug: true
}

// ✅ 正确：使用 satisfies + 显式类型
export const config: {
  port: number
  host: string
  debug: boolean
} = {
  port: 3000,
  host: 'localhost',
  debug: true
}

// ✅ 更好：使用 as const 配合 satisfies
export const config = {
  port: 3000,
  host: 'localhost',
  debug: true
} as const

⚠️ 警告： 不要在已有大型项目中贸然全局开启 isolatedDeclarations。建议先在 CI 中以 --noEmit 模式试跑，评估需要修改的文件数量，再逐步迁移。微软提供的 codemod 工具 @typescript/isolated-declarations-migrate 可以自动修复 70% 以上的常见问题。

💡 三、satisfies 操作符深度实战：类型推断的终极形态

3.1 satisfies vs 类型注解：核心区别

satisfies 操作符在 TypeScript 4.9 中引入，但直到 TypeScript 6 与 isolatedDeclarations 配合使用后，才真正成为每个 TypeScript 开发者的必备工具。它的核心能力是：在保证类型安全的同时，保留字面量类型的精确推断。

// ❌ 问题：类型注解会「吞掉」字面量类型
type Route = {
  path: string
  method: 'GET' | 'POST' | 'PUT' | 'DELETE'
  handler: () => void
}

const getUserRoute: Route = {
  path: '/api/users/:id',
  method: 'GET',        // 类型被拓宽为 string（因为 Route.path 是 string）
  handler: () => {}     // 但实际上 method 已经被约束为字面量
}
// getUserRoute.method 的类型是 'GET' | 'POST' | 'PUT' | 'DELETE'

// ✅ satisfies：保留精确类型，同时检查是否满足约束
const getUserRoute = {
  path: '/api/users/:id',
  method: 'GET',
  handler: () => {}
} satisfies Route
// getUserRoute.method 的类型是 'GET'（精确字面量！）

3.2 实战场景：类型安全的路由配置

在实际项目中，satisfies 最常见的应用场景是配置对象——你需要一个统一的类型约束，但又需要保留每个具体配置项的精确类型：

// 定义路由元数据类型
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE'
type RouteConfig = {
  path: string
  method: HttpMethod
  auth: boolean
  handler: (req: Request) => Response
}

// ✅ 使用 satisfies 定义路由表
const routes = {
  getUser: {
    path: '/api/users/:id',
    method: 'GET',
    auth: true,
    handler: (req) => new Response('user data')
  },
  createUser: {
    path: '/api/users',
    method: 'POST',
    auth: true,
    handler: (req) => new Response('created', { status: 201 })
  },
  healthCheck: {
    path: '/api/health',
    method: 'GET',
    auth: false,
    handler: () => new Response('ok')
  }
} satisfies Record<string, RouteConfig>

// 关键优势：routes.getUser.method 的类型是 'GET'，不是 HttpMethod
// 这允许精确的条件逻辑：
type ExtractMethod<T extends HttpMethod> = T extends 'GET' ? 'safe' : 'unsafe'

// 用 satisfies 保留的字面量类型，可以用在泛型中
function describeRoute<M extends HttpMethod>(method: M): ExtractMethod<M> {
  return (method === 'GET' ? 'safe' : 'unsafe') as any
}

describeRoute(routes.getUser.method)    // 返回类型是 'safe' ✅
describeRoute(routes.createUser.method) // 返回类型是 'unsafe' ✅

3.3 satisfies + const 断言：联合使用的威力

在 TypeScript 6 中，satisfies 与 as const 的组合使用变得更加流畅。as const 让所有属性变为 readonly 且值为字面量类型，satisfies 则在不改变推断结果的前提下添加类型检查：

// 定义颜色主题约束
type ColorTheme = {
  primary: string
  secondary: string
  accent: string
  background: string
}

// ❌ 单独用 as const：没有类型检查
const darkTheme = {
  primary: '#0066ff',
  secondary: '#333333',
  accent: '#ff6600',
  // background: 'typo!' // 拼写错误也不会报错
} as const

// ✅ as const + satisfies：精确类型 + 类型检查
const darkTheme = {
  primary: '#0066ff',
  secondary: '#333333',
  accent: '#ff6600',
  background: '#1a1a2e'
} satisfies ColorTheme

// darkTheme.primary 的类型是 '#0066ff'（精确字面量）
// 如果缺少 background 属性，TypeScript 会报错

// 实用示例：根据主题色生成 CSS 变量
function toCSSVars(theme: typeof darkTheme) {
  return Object.entries(theme)
    .map(([key, value]) => `--color-${key}: ${value};`)
    .join('\n')
}

console.log(toCSSVars(darkTheme))
// --color-primary: #0066ff;
// --color-secondary: #333333;
// --color-accent: #ff6600;
// --color-background: #1a1a2e;

💡 提示： TypeScript 6 改进了 satisfies 在复杂嵌套对象中的推断能力。在 TypeScript 5 中，超过 3 层嵌套的 satisfies 表达式可能会丢失字面量类型；TS 6 通过改进的类型缓存机制解决了这个问题。

🔧 四、TypeScript 6 其他值得关注的改进

4.1 全新的 tsc --init 模板

TypeScript 6 的 tsc --init 生成的 tsconfig.json 配置更加现代化和实用：

// TypeScript 6 生成的 tsconfig.json（简化版）
{
  "compilerOptions": {
    // 编译目标
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",

    // 类型检查严格性（全部默认开启）
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // 输出
    "declaration": true,
    "isolatedDeclarations": true,
    "sourceMap": true,

    // 新增选项
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true
  }
}

其中 rewriteRelativeImportExtensions 是 TypeScript 6 的新选项，它允许你写 import { foo } from './bar.ts'，编译时自动将 .ts 扩展名重写为 .js——这对使用 ESM 的 Node.js 项目来说是一个巨大的便利。

4.2 erasableSyntaxOnly：Node.js 原生 TypeScript 支持

Node.js 从 v22.6 开始支持通过 --experimental-strip-types 标志直接运行 TypeScript 文件。但这个特性有一个关键限制：它只能「剥离」（strip）类型注解，不能处理枚举（enum）、命名空间（namespace）等需要编译时转换的语法。

TypeScript 6 的 erasableSyntaxOnly 选项正是为这个场景设计的。开启后，TypeScript 会禁止使用需要「转换」的语法，确保你的代码可以被 Node.js 直接运行：

// tsconfig.json
{
  "compilerOptions": {
    "erasableSyntaxOnly": true
  }
}

// ❌ 错误：enum 需要运行时转换，Node.js 无法直接剥离
enum Status {
  Active = 'active',
  Inactive = 'inactive'
}

// ✅ 正确：使用 const 对象 + 类型推断替代 enum
const Status = {
  Active: 'active',
  Inactive: 'inactive'
} as const
type Status = typeof Status[keyof typeof Status]

// ❌ 错误：namespace 需要运行时转换
namespace Utils {
  export function format(str: string) { return str.trim() }
}

// ✅ 正确：使用模块导出
export function format(str: string) { return str.trim() }

⚡ 关键结论： 如果你的项目使用 Node.js 原生 TypeScript 运行（node --experimental-strip-types），erasableSyntaxOnly 是必开选项。它能帮你避免运行时 SyntaxError。

4.3 迁移检查清单

从 TypeScript 5.x 升级到 6.0，建议按以下顺序逐步迁移：

# 第一步：安装 TypeScript 6
npm install -D typescript@6

# 第二步：用传统 tsc 检查兼容性
npx tsc --noEmit 2>&1 | head -50

# 第三步：尝试 tsgo 编译器
npx tsgo --noEmit

# 第四步：在 CI 中对比两种编译器的耗时
time npx tsc --noEmit
time npx tsgo --noEmit

# 第五步：（可选）启用 isolatedDeclarations
# 先在 CI 中以报告模式运行
npx tsgo --noEmit --declaration --isolatedDeclarations 2>&1 | wc -l

📊 五、TypeScript 编译器生态全景对比

💡 提示： tsgo 填补了「速度快 + 完整类型检查」的空白。在此之前，你要么用 tsc（慢但完整），要么用 esbuild（快但不检查类型）。tsgo 让你两全其美。

✅ 总结与建议

TypeScript 6 的发布不仅仅是一个版本号的变化，它代表了 TypeScript 从「JavaScript 的类型超集」向「独立的工程化平台」的转型。tsgo 的 10 倍编译速度提升、isolatedDeclarations 对 monorepo 构建的解耦、以及 erasableSyntaxOnly 与 Node.js 原生 TS 的协同，都在指向同一个方向：TypeScript 正在成为比 JavaScript 更好的 JavaScript。

我的建议：

• ✅ 立即行动：在新项目中使用 TypeScript 6 + tsgo，享受编译速度提升
• ✅ 逐步迁移：已有项目先用 tsc --noEmit 确认兼容性，再切换到 tsgo
• ⚠️ 谨慎启用：isolatedDeclarations 需要大量手动标注，建议配合 codemod 工具使用
• ❌ 不要跳过：不要因为「tsc 还能用」就忽略 tsgo——在大型项目中，编译速度直接影响开发幸福感

相关工具推荐：

• 🔧 TypeScript Playground — 在线测试 TS 6 新特性
• 🔧 tsgo GitHub — tsgo 编译器源码
• 🔧 arethetypeswrong.github.io — 检查 npm 包的类型声明是否正确
• 🔧 本站 JSON 格式化工具 — 配合 TypeScript 开发时格式化 JSON 配置文件