Node.js 原生运行 TypeScript：Type Stripping 深度实战指南

2024 年 Node.js 22.6 引入 --experimental-strip-types 标志，标志着 JavaScript 运行时正式迈入「原生理解 TypeScript」的时代。截至 2026 年中，Node.js 24 已将 type stripping 稳定为默认行为——无需任何标志即可直接运行 .ts 文件。这意味着开发者终于可以告别 ts-node 的配置地狱和 tsx 的额外依赖，用一行 node app.ts 启动 TypeScript 项目。

但「能跑」和「跑得好」是两回事。Type stripping 的工作原理是什么？它和 tsc 编译有什么本质区别？enum、decorators、const assertions 这些语法能正常工作吗？生产环境到底该不该用？本文将从源码层面拆解 type stripping 机制，用基准测试数据说话，并给出从 ts-node/tsx 迁移的完整方案。

🔬 一、Type Stripping 工作原理

1.1 什么是 Type Stripping

Type stripping 的核心思想极其简单：只删除类型注解，不做任何类型检查或代码转换。它利用了 TypeScript 作者 Anders Hejlsberg 早在设计语言时就预留的一个特性——TypeScript 的类型系统是「可擦除」的（erasable），所有类型注解都可以被安全移除而不影响运行时行为。

与 tsc 的完整编译流程对比：

⚠️ **关键区别：**type stripping 不是编译器，它是一个极其轻量的文本处理器。理解这一点是正确使用它的前提。

1.2 内部实现机制

Node.js 内部使用了与 SWC 团队合作开发的高速 parser（amaro 模块），处理流程如下：

// input.ts - 你的 TypeScript 源码
interface User {
  id: number
  name: string
}

const getUser = async (id: number): Promise<User> => {
  return { id, name: 'Alice' }
}

// Type stripping 处理后的结果（内存中，不写磁盘）
// 所有类型注解被精确移除，运行时代码原封不动

const getUser = async (id) => {
  return { id, name: 'Alice' }
}

整个过程遵循一个精确的规则集：只移除那些对运行时行为无影响的语法元素。具体来说：

• ✅ 会移除： 类型注解、interface、type alias、枚举值类型、泛型参数、as 类型断言
• ❌ 不会移除： enum 定义的运行时值、namespace 中的运行时代码、const enum 的内联值（会报错）
• ❌ 不支持： emitDecoratorMetadata、旧式 import = / export = 语法

1.3 实际验证：观察剥离结果

# 创建一个包含各种 TypeScript 特性的测试文件
cat > /tmp/stripping-test.ts << 'EOF'
// 测试文件：各种 TypeScript 语法
interface Config {
  port: number
  host: string
}

type Status = 'active' | 'inactive'

enum Direction {
  Up = 'UP',
  Down = 'DOWN',
}

const config: Config = { port: 3000, host: 'localhost' }

function greet(name: string): string {
  return `Hello, ${name}!`
}

const value = 'hello' as string

class UserService {
  private users: Map<string, Config> = new Map()

  getUser(id: string): Config | undefined {
    return this.users.get(id)
  }
}

export { config, greet, UserService, Direction }
EOF

# 使用 Node.js 的 type stripping 查看处理结果
node --experimental-strip-types /tmp/stripping-test.ts

💡 **提示：**你可以在 Node.js 22.6+ 中用 node --experimental-strip-types --experimental-transform-types 来启用对 enum 和 namespace 的支持（会做额外的语法转换）。

⚡ 二、四大 TypeScript 运行方案深度对比

2.1 方案全景

当前运行 TypeScript 的主流方案有四种，每种的设计哲学截然不同：

// 方案 1：tsc 编译 + node 运行（传统方案）
// package.json
{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

// 方案 2：tsx 运行（最流行的开发方案）
// 直接运行：npx tsx index.ts

// 方案 3：ts-node 运行（老牌方案，配置复杂）
// ts-node --esm index.ts

// 方案 4：Node.js 原生 type stripping（2026 新方案）
// node index.ts（Node.js 24+ 默认支持）

2.2 性能基准测试

我在同一台机器（8 核 16GB，Ubuntu 22.04）上对四种方案做了启动时间和内存占用的基准测试，测试项目是一个包含 50 个模块、约 8000 行代码的中型 Node.js 服务：

⚡ **关键结论：**Node.js 原生 type stripping 的启动速度是 tsx 的 2.2 倍、ts-node 的 4.5 倍，内存占用最低。但代价是对 enum、namespace、decorator metadata 等高级特性的支持有限。

2.3 兼容性陷阱详解

这是最容易踩坑的部分。type stripping 在以下场景会出问题：

// ❌ 会报错：enum 需要代码转换，type stripping 无法处理
enum HttpStatus {
  OK = 200,
  NotFound = 404,
  ServerError = 500,
}

// ✅ 替代方案：使用 as const 对象
const HttpStatus = {
  OK: 200,
  NotFound: 404,
  ServerError: 500,
} as const
type HttpStatus = typeof HttpStatus[keyof typeof HttpStatus]

// ❌ 会报错：namespace 中包含运行时代码
namespace Validation {
  export function isEmail(value: string): boolean {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
  }
}

// ✅ 替代方案：使用普通模块导出
export function isEmail(value: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
}

// ❌ 会报错：参数装饰器 + emitDecoratorMetadata
// 需要 reflect-metadata 和编译步骤

// ✅ 替代方案：使用 tc39 stage 3 装饰器语法（无需 metadata）
function log(target: any, context: ClassMethodDecoratorContext) {
  return function (this: any, ...args: any[]) {
    console.log(`Calling ${String(context.name)}`)
    return target.apply(this, args)
  }
}

⚠️ **避坑指南：**如果你的项目大量使用 enum（尤其是 const enum），且不想重构，那么 type stripping 不适合你。继续使用 tsx 或 tsc 编译是更稳妥的选择。

🛠️ 三、生产环境迁移实战

3.1 迁移决策树

不是所有项目都适合迁移。以下是决策流程：

# 第一步：检查你的项目是否使用了不兼容的特性
grep -rn "enum \|namespace \|@.*(" src/ --include="*.ts" | head -20

# 第二步：检查是否有 emitDecoratorMetadata
grep -rn "emitDecoratorMetadata\|reflect-metadata" tsconfig.json src/

# 第三步：尝试直接运行
node --experimental-strip-types src/index.ts

如果你的项目是以下情况，推荐迁移：

• ✅ 纯 ESM 项目
• ✅ 不使用 enum（或愿意改为 as const）
• ✅ 不使用装饰器元数据
• ✅ 使用现代 Node.js（22.6+）

如果以下情况，暂不迁移：

• ❌ 重度使用 enum 和 namespace
• ❌ 依赖 emitDecoratorMetadata（如 TypeORM、NestJS 的某些特性）
• ❌ 需要生成 .js 产物给其他系统消费

3.2 完整迁移步骤

# 1. 升级 Node.js 到 24.x（type stripping 已稳定）
nvm install 24
nvm use 24

# 2. 确保 tsconfig.json 配置正确
# tsconfig.json
cat > tsconfig.json << 'TSEOF'
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "noEmit": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src/**/*.ts"]
}
TSEOF

# 3. 添加类型检查脚本（type stripping 不做类型检查，需要单独跑 tsc）
# package.json 中添加
# "typecheck": "tsc --noEmit",
# "start": "node src/index.ts"

# 4. 运行类型检查确保无误
npx tsc --noEmit

# 5. 直接运行
node src/index.ts

📌 记住：erasableSyntaxOnly: true 是 tsconfig 中的关键配置，它会让 TypeScript 编译器在你写出 type stripping 不支持的语法时直接报错，帮你提前发现兼容性问题。

3.3 enum 替换的完整模式

这是迁移中最常见的改动。as const 对象不仅兼容 type stripping，而且在 tree-shaking 和类型推导方面表现更好：

// ❌ 旧写法：传统 enum
enum Role {
  Admin = 'admin',
  Editor = 'editor',
  Viewer = 'viewer',
}

// 使用 enum 的代码
function checkAccess(role: Role): boolean {
  return role === Role.Admin
}

// ✅ 新写法：as const 对象 + 联合类型
const Role = {
  Admin: 'admin',
  Editor: 'editor',
  Viewer: 'viewer',
} as const
type Role = typeof Role[keyof typeof Role]

// 使用方式完全一致，无需修改业务代码
function checkAccess(role: Role): boolean {
  return role === Role.Admin
}

// 额外优势：可以 Object.values(Role) 获取所有值
// 而 enum 需要 Object.values(Role).filter(v => typeof v === 'string')

3.4 CI/CD 中的类型检查策略

type stripping 不做类型检查，所以你需要在 CI 流程中单独运行 tsc --noEmit：

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: npm ci

      # 类型检查（由 tsc 负责）
      - name: Type Check
        run: npx tsc --noEmit

      # 运行测试（直接用 Node.js 原生 TS 支持）
      - name: Run Tests
        run: node --test src/**/*.test.ts

      # 启动验证
      - name: Smoke Test
        run: |
          node src/index.ts &
          sleep 2
          curl -f http://localhost:3000/health || exit 1
          kill %1

💡 **提示：**推荐使用 node --test（Node.js 内置测试运行器）配合 type stripping，可以实现零依赖的完整测试流程，无需 Jest 或 Vitest。

🎯 四、最佳实践与未来展望

4.1 项目配置推荐

// package.json - 推荐的 scripts 配置
{
  "scripts": {
    "start": "node --enable-source-maps src/index.ts",
    "dev": "node --watch --enable-source-maps src/index.ts",
    "typecheck": "tsc --noEmit",
    "test": "node --test src/**/*.test.ts",
    "lint": "tsc --noEmit && node --test src/**/*.test.ts"
  },
  "engines": {
    "node": ">=22.6.0"
  }
}

几个关键配置说明：

• --enable-source-maps：让错误堆栈指向 .ts 源码行号而非编译后的行号
• --watch：Node.js 内置的文件监听，无需 nodemon
• --test：Node.js 内置测试运行器，零依赖

4.2 与现有工具链的兼容

// 使用 path aliases 的处理方案
// tsconfig.json 中配置了 paths 后，type stripping 不会自动解析
// 解决方案：使用 --import 加载自定义 loader

// loader.ts - 路径别名解析器
import { register } from 'node:module'
import { pathToFileURL } from 'node:url'

// 使用 Node.js 的自定义 loader 机制
register(pathToFileURL('./resolve-loader.js'))

// 运行时：node --import ./loader.ts src/index.ts

⚠️ **注意：**path aliases 在 type stripping 模式下不会自动工作。如果你的项目使用了 @/ 等路径别名，需要额外配置 loader 或改用相对路径。

4.3 生产环境建议

对于 2026 年的新项目，我的建议是分场景选择：

⚡ 关键结论：Type stripping 的最大价值不是「省去 tsx 这个依赖」，而是消除开发与运行之间的编译鸿沟。你写的 .ts 文件就是被执行的文件，没有中间产物，没有 source map 断裂，没有「编译后代码和源码不一致」的困惑。这种确定性在大型项目中尤其珍贵。

📋 总结

Node.js 原生 TypeScript 支持是 2025-2026 年 JavaScript 生态最重要的基础设施变革之一。它不是要取代 tsc，而是重新定义了「运行 TypeScript」这件事的默认方式。

核心要点回顾：

• ✅ Type stripping 只移除类型注解，不做编译，速度极快
• ✅ Node.js 24+ 默认支持 .ts 文件，无需任何标志
• ✅ as const 对象是 enum 的完美替代，tree-shaking 更友好
• ✅ erasableSyntaxOnly: true 是 tsconfig 必加配置
• ⚠️ 不支持 decorator metadata、namespace 运行时代码、const enum
• ⚠️ CI 中仍需 tsc --noEmit 做类型检查
• 💡 新项目强烈推荐直接使用，老项目评估 enum 使用量后决定

相关工具推荐：

• Node.js 官方文档 — TypeScript 支持

• TypeScript 5.8+ erasableSyntaxOnly 选项

• tsx — 最流行的 TS 运行器

• Biome — 替代 ESLint + Prettier 的全功能 Linter

• 🔧 Node.js 官方文档 — Type Stripping 最权威的参考

• 🔧 tsx — 仍是最成熟的第三方方案，适合 strip-types 不支持的场景

• 🔧 TypeScript 5.8 — 最新版本，verbatimModuleSyntax 支持更完善

• 🔧 jsjson.com JSON 格式化工具 — 配置文件的格式化与校验，开发必备