Node.js 的 TypeScript 原生路线:type stripping、ts_node 与迁移边界
Node 24 移除了 --experimental-transform-types,同时内置的类型剥离(type stripping)能力在 26 时代持续成熟——.ts 文件可以直接被 node 加载执行,不需要先编译。这条"原生 TS 路线"对工具链的影响是实质性的:脚本与小服务的 tsc 构建步骤可以删掉了。但它有明确的能力边界,本文把"能做什么、不能做什么、怎么迁"讲清楚。
一、type stripping 的机制与限制
Node 内置的 TS 支持本质是擦除类型语法而不做类型检查:加载 .ts 时按规则删掉 type annotation、interface、泛型参数等,转成 JS 执行。因此:
// server.ts —— 直接 node server.ts 可跑(Node 24+)
type User = { id: number; name: string };
function greet(u: User): string { return `hi ${u.name}`; }
console.log(greet({ id: 1, name: "okgoes" }));
三条硬限制:
- 不做类型检查。编译期错误不会阻止运行,
tsc --noEmit仍然必须跑(放 lint/CI); - 不能转译高级语法:装饰器、enum、namespace 这类需要生成代码的 TS-only 特性不在擦除范围(Node 26 已移除 transform-types flag,走这条路就要放弃这些特性);
- CommonJS 语义下
import type与运行时导入混写容易出错,原生路线建议全 ESM。
二、ts_node:需要"真编译语义"时的官方搭档
要装饰器、要 enum、要更完整的转译,用 TypeScript 官方维护的 ts_node(Node loader hooks 形态):
node --import tsx src/server.ts # 社区方案 esbuild-register/tsx 同样可用
# 或官方 ts_node(基于 tsc 语义,慢但完整)
node --experimental-loader ./node_modules/ts-node/esm.mjs src/server.ts
注意 Node 26 把 module.register() 列入运行时弃用倒计时,loader 注册方式在向 --import + register API 收敛——写启动脚本时优先 --import 形态,关注 changelog 里 loader 生命周期的下一步变化。
选型判据很直白:
- 库/大型应用(要发布到 npm、要装饰器/enum)→ 保持 tsc 或 esbuild 预编译;
- 服务内部代码 + 脚本 → 原生 stripping,删掉构建步骤;
- 混合:生产入口用 stripping,测试与类型检查独立跑 tsc。
三、CI 里的完整闭环
jobs:
typecheck:
run: npx tsc --noEmit # 类型检查独立成 job
test:
run: node --test test/**/*.test.ts # 测试直接跑 .ts(stripping)
build: # 只有发布产物需要 bundle
run: npx esbuild src/server.ts --bundle --outfile=dist/server.mjs --platform=node
关键点:类型检查、执行、打包三件事解耦。过去 tsc 同时干三件事导致构建慢;stripping 把"执行"从编译链里拆出来后,开发循环变成"改代码 → 直接跑 → tsc 后台查错"。编辑器侧(tsserver)不受影响,体验不变。
四、迁移步骤与常见坑
按依赖风险从低到高:
- 先统一 ESM:
package.json加"type": "module",相对导入补扩展名——这是最大的一次性成本; - 重命名 .js → .ts(不改内容),跑
tsc --noEmit --allowJs观察基线错误数; - 逐模块补类型,开启
strict: true按目录灰度(tsconfig solution-style 多项目引用可行); - 删构建步骤:dev 环境
node server.ts直跑;生产保留 bundle(体积与冷启动收益独立于 TS)。
高频坑清单:
import { A } from "./a"省略扩展名在原生 ESM 下报错——配moduleResolution: "bundler"+ bundler 解析,或老实写全名;- JSON 导入需要
with { type: "json" }属性(Node 稳定语法),旧的 assert 已废; __dirname/require在 ESM 不存在:import.meta.dirname(Node 20.11+)替代;- enum 要改写为
const对象 + union type——这是唯一常见"必须重写"的场景; - 装饰器代码(老 NestJS 风格)走不了 stripping,这类项目维持编译链即可。
五、性能与启动成本实测口径
stripping 的开销在加载期(一次性擦除),对常驻服务可忽略,对短脚本略增启动时间。对比测试:
hyperfine --warmup 3 \
'node plain.js' \
'node same.ts' \
'npx tsx same.ts'
典型结果:原生 stripping 比 tsx 快一个量级(无 loader 握手),比纯 JS 慢几毫秒。别凭印象选路线,用这组数字。
小结
Node 原生 TS 路线改变了默认假设:执行不再需要编译。判据是特性面——只用"可擦除语法"的服务与脚本直接 node x.ts,把 tsc 降级为纯类型检查工具;用了 enum/装饰器或要发 npm 的库继续走预编译。迁移的关键成本在 ESM 化与 moduleResolution 配置,而不是类型本身。CI 三件事解耦(typecheck / test / bundle)后,开发反馈环更短,生产产物依旧可控。这是 Node 26 时代最值得做的工具链减法。
评论(0)
登录 后参与评论。