Node.js 24原生TypeScript支持：.ts文件直接运行的工程实践

背景：TypeScript在Node.js中的尴尬位置

长期以来，TypeScript和Node.js始终保持着一种"相爱相杀"的关系。TypeScript作为JavaScript的超集，在编译期提供类型检查能力，但最终需要在运行时将.ts文件转换为.js文件才能被Node.js执行。这一转换过程需要借助各种工具链——早期是tsc编译器，后来出现了ts-node、tsx、esbuild等专门的运行时工具。

这种"先编译再运行"的模式带来了显著的工程开销：

开发体验层面：每次修改TypeScript代码后，都需要等待编译完成才能看到效果。虽然ts-node --watch等工具提供了一定的热更新能力，但在大型项目中编译延迟仍然明显，尤其是全量编译场景。

构建管道层面：大多数Node.js项目的CI/CD流程中都包含显式的编译步骤，这不仅增加了流水线复杂度，也引入了额外的故障点。如果编译阶段失败，后续的所有部署流程都无法执行。

资源消耗层面：编译工具本身需要内存和CPU资源。在容器化部署场景下，这意味着需要为每个服务实例预留更多的资源用于编译过程。

Node.js 24 LTS的发布改变了这一局面。通过内置的TypeScript支持，开发者现在可以直接使用node app.ts运行TypeScript文件，无需任何额外的编译步骤或第三方工具。

核心原理：原生TypeScript支持的实现

--experimental-strip-types引擎

Node.js 24的原生TypeScript支持基于V8引擎内置的TypeScript类型剥离器（TypeScript Strip Types）。当使用--experimental-strip-types标志运行时，V8会直接读取.ts文件，剥离所有TypeScript类型注解，然后将纯JavaScript代码传递给V8引擎执行。

# 基本用法
node --experimental-strip-types app.ts

# 配合inspect调试
node --inspect --experimental-strip-types app.ts

# 在package.json中配置（推荐）
{
  "type": "module",
  "scripts": {
    "start": "node --experimental-strip-types src/index.ts"
  }
}

关键在于理解这个过程与完整编译的区别。传统的tsc编译器会将TypeScript代码完整编译为JavaScript，包括声明文件生成、JSX转换、模块系统转换等。而Node.js的原生支持只做了最核心的事情：剥离类型注解。

类型剥离的算法流程

// 输入：TypeScript源代码
const source = `
interface User {
  id: number;
  name: string;
}

function greet(user: User): string {
  return \`Hello, \${user.name}\`;
}

const user: User = { id: 1, name: 'Alice' };
console.log(greet(user));
`;

// 输出：剥离类型后的纯JavaScript
const transformed = `
function greet(user) {
  return \`Hello, \${user.name}\`;
}

const user = { id: 1, name: 'Alice' };
console.log(greet(user));
`;

类型剥离过程分为三个阶段：

1. 词法分析：将.ts文件解析为token流，识别类型注解的位置（: Type、as Type、等语法结构）

2. 语法树遍历：在AST层面标记所有类型相关的节点，包括接口声明、类型别名、泛型参数、类型断言等

3. 节点移除：精确移除类型节点而不破坏代码结构，保留所有运行时逻辑不变

性能对比

数据来自Node.js官方基准测试，在Node.js 24.6.0环境下运行。可以看到，原生TypeScript支持的启动开销仅比纯JavaScript高约16%，远低于任何第三方工具链的方案。

实战：工程实践与项目配置

项目初始化配置

创建一个使用Node.js原生TypeScript支持的项目：

# 初始化项目
mkdir my-ts-app && cd my-ts-app
npm init -y

# 创建tsconfig.json（仅需类型检查，无需编译输出）
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}
EOF

Express应用示例

// src/server.ts
import express from 'express';
import { z } from 'zod';

const UserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

const app = express();
const PORT = process.env.PORT ?? 3000;

app.get('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id, 10);
  res.json({ id: userId, name: 'Test User' });
});

app.post('/users', (req, res) => {
  const result = UserSchema.safeParse(req.body);
  if (!result.success) {
    res.status(400).json({ error: result.error.message });
    return;
  }
  res.json({ message: 'User created', data: result.data });
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

// package.json
{
  "name": "my-ts-app",
  "type": "module",
  "scripts": {
    "dev": "node --watch --experimental-strip-types src/server.ts",
    "start": "node --experimental-strip-types src/server.ts",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.7.0"
  },
  "dependencies": {
    "express": "^4.21.0",
    "zod": "^3.23.0"
  }
}

注意这里noEmit: true的配置——因为不需要tsc生成.js文件，TypeScript仅用于类型检查。开发时通过--watch标志实现热更新，TypeScript类型变化时自动重启服务。

与现有工具链的协作

虽然原生TypeScript支持可以替代ts-node和tsx，但某些场景下仍需配合其他工具：

// src/cli.ts - 命令行工具示例
#!/usr/bin/env node

import { readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

interface Config {
  sourceDir: string;
  targetDir: string;
  include: string[];
}

function loadConfig(): Config {
  const raw = readFileSync(join(process.cwd(), 'migrator.config.json'), 'utf-8');
  return JSON.parse(raw) as Config;
}

function transformFile(input: string, output: string): void {
  const content = readFileSync(input, 'utf-8');
  // 执行文件转换逻辑
  const transformed = content.replace(/async\s+(fn|function)/g, '$1 async');
  writeFileSync(output, transformed);
  console.log(`Transformed: ${input} → ${output}`);
}

export function main(): void {
  const config = loadConfig();
  // ... 执行迁移逻辑
}

if (import.meta.url === `file://${process.argv[1]}`) {
  main();
}

# 运行CLI工具
node --experimental-strip-types src/cli.ts
# 或直接作为可执行文件（需添加shebang）
chmod +x src/cli.ts
./src/cli.ts

CI/CD流水线配置

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: ['22', '24']

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - run: npm ci

      - name: Type check
        run: npx tsc --noEmit  # 仅类型检查，不生成.js

      - name: Run tests
        run: node --experimental-strip-types node_modules/.bin/jest

      - name: Build (if needed)
        run: npm run build  # 可选：生成产物

关键点：在CI中npx tsc --noEmit仅用于类型检查，测试运行直接使用node --experimental-strip-types，无需编译步骤。

最佳实践与注意事项

何时应该使用原生TypeScript支持

推荐使用场景：
- 新项目快速启动，减少构建配置复杂度
- 中小型项目，对启动速度敏感
- 脚本类和工具类应用
- 希望统一开发和生产运行方式

仍建议使用传统编译的场景：
- 需要输出声明文件（.d.ts）供其他项目引用
- 需要JSX/TSX转换（React项目建议使用构建工具）
- 需要代码分割和tree-shaking的复杂优化
- 需要兼容性处理（目标环境不支持最新ES特性）

类型检查与类型安全

原生TypeScript支持只剥离类型注解，不会进行类型检查。因此类型检查仍需通过tsc独立完成：

# 类型检查（编译时）
npx tsc --noEmit

# 运行（无需编译）
node --experimental-strip-types src/index.ts

建议在package.json中分离这两个步骤：

{
  "scripts": {
    "typecheck": "tsc --noEmit --pretty",
    "dev": "node --watch --experimental-strip-types src/index.ts",
    "start": "node --experimental-strip-types src/index.ts"
  }
}

与Monorepo的配合

在monorepo环境中，各子项目可以独立决定是否启用原生TypeScript支持：

// packages/web/package.json
{
  "scripts": {
    "dev": "node --experimental-strip-types src/index.ts"
  }
}

// packages/api/package.json
{
  "scripts": {
    "dev": "node --experimental-strip-types src/server.ts"
  }
}

共享包保持noEmit: true的tsconfig，但需要输出声明文件时使用独立的构建步骤：

# 仅生成声明文件，不生成.js
tsc --declaration --emitDeclarationOnly --outDir dist/types

总结

Node.js 24的原生TypeScript支持是JavaScript运行时发展史上的一个重要里程碑。它将TypeScript从"编译时工具"转变为"运行时特性"，大幅简化了TypeScript项目的开发体验。

对于新项目，建议直接使用原生TypeScript支持，避免引入ts-node或tsx等额外依赖。对于已有项目，可以逐步迁移，先在开发环境试用，确认无兼容问题后再扩展到生产环境。

需要注意的是，原生TypeScript支持目前仍处于实验阶段（--experimental-strip-types），在生产环境中使用建议锁定到稳定的Node.js 24 LTS版本，并关注后续版本的特性稳定情况。随着TypeScript生态的持续演进，这一功能有望在未来某个版本中成为默认行为。