用途:在 Node.js 上直接运行 TypeScript 而无需构建步骤,即通过 node file.ts(.ts/.mts/.cts)执行,使用原生类型剥离;同时判断何时原生剥离不够用,需要完整加载器 tsx。也涉及搭建 ESM-only Node 项目、--watch 模式、node:test,以及把脚本/CLI/hook 从 ts-node 迁移过来。
主要能力与规则:类型剥离只做擦除,Node 把类型替换为空白且不做任何类型检查,安全起见需单独运行 tsc --noEmit。tsconfig.json 在运行时被忽略,paths、降级和 JS 目标下调均不生效。不可擦除语法会报错:enum、含运行时代码的 namespace、参数属性、import 别名会抛出 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX。类型导入必须用 import type 或 verbatimModuleSyntax,否则值导入类型会在运行时崩溃。导入必须写文件扩展名,如 import './file.ts';原生剥离不支持 .tsx。
使用方式:项目结构包括 package.json("type": "module")、tsconfig.json(noEmit、erasableSyntaxOnly、verbatimModuleSyntax)、src/index.ts(node src/index.ts)、仅类型模块与 node --test 的测试目录。需要 paths、装饰器、enum 或 .tsx 时改用 tsx。不要在 node_modules 里发布 .ts 文件,Node 会拒绝剥离;不要依赖原生剥离处理装饰器(TC39 Stage 3,不做转换)。
流程要求:任何实现前并行调用 3 个 agent,分别探查代码库、核验最新 Node LTS 与类型剥离行为、查询 Node 模块与 CLI 标志文档;实现后用指定校验 agent 验证。
限制与范围:不适用于 Bun 运行时或 bun test(见 ts-runtime-bun)、lint/格式化(见 ts-lint-format)、自带转译管线的框架运行时(Next.js、Astro)以及浏览器/打包输出。官方文档未提供更多细节。