上周同事的项目突然跑不起来了控制台报错刷了一屏仔细一看ts-node 10.9.1配着TypeScript 5.3.0一运行就抛TypeError。这种tsc和ts-node的兼容问题在TypeScript项目里太常见了很多人升级完TypeScript才发现ts-node罢工或者反过来ts-node一升级项目里的旧tsc又跟不上。版本兼容这事在技术圈里太普遍Python那边paddlehub和paddlepaddle版本对不上一样能把人折腾疯LabVIEW打印指令和驱动版本匹配也是老问题。今天先集中把TypeScript这边的坑填平重点讲怎么用npm命令查看两个包的兼容版本怎么快速找到能用的版本组合。适合正在被版本问题折磨的前端开发者也适合刚接触TypeScript的新手——这类坑你迟早会踩早看早避开。1. 先搞清楚tsc和ts-node的关系1.1 tsc和ts-node各司其职要理解兼容问题先得知道这两个工具各自干什么。TypeScript代码不能直接交给Node.js运行Node只认JavaScript。所以平时写TS要么用tsc把.ts文件编译成.js再用node去跑编译结果要么就用ts-node这类工具让它在运行时直接处理TS文件。tsc是TypeScript官方编译器它负责把.ts/.tsx代码转成.js同时做类型检查。它的产物是独立的JavaScript文件一般放在dist或build目录里然后由Node或浏览器加载。这个流程没问题但开发阶段很啰嗦——每改一次代码就要编译一次还得处理一堆中间文件。ts-node干的事不太一样。它不生成独立JS文件而是在Node运行时内部直接调用TypeScript的编译器API把当前要执行的TS文件转成JS后交给Node执行。这让开发体验舒服很多跑脚本、写测试、本地调试都能一步到位。类比一下tsc像一个面粉加工厂你把小麦送进去它给你产出面粉和包装袋ts-node更像一家开在农贸市场的现磨咖啡馆你点一杯咖啡它现场磨豆、现场冲泡喝完整个人都精神了。两者都能让你“喝上咖啡”但工作方式完全不同。也正因为ts-node不是调用tsc这个命令行工具而是直接调用typescript包里的编译器API所以它对TypeScript内部实现的依赖非常深。TypeScript每次升级都可能调整内部APIts-node如果没跟上就会出问题。1.2 兼容问题到底是怎么来的你可能会问TypeScript官方一直保持向后兼容为什么ts-node还会不兼容问题就出在“向后兼容”和“内部API稳定”不是一回事。TypeScript对外暴露的语言特性、命令行参数确实保持兼容但它内部给工具链使用的那套API比如createProgram、transpileModule、ScriptKind这类方法和枚举在不同版本里有过调整。ts-node为了高性能转译会用到这些内部API一旦TypeScript大版本改了内部结构ts-node如果不及时适配就会报错。另一个因素是package.json里的peerDependencies机制。ts-node在自己的package.json里声明它支持的TypeScript版本范围比如peerDependencies: { typescript: 2.7 }这行声明说的是“我这个ts-node理论上能配合2.7以上的所有TypeScript”但实际效果并不是绝对的。npm只把它当作提示安装时默认不会因为TypeScript版本过新而阻止你真正跑起来才发现问题。这就是为什么很多人升级TypeScript后ts-node毫无预警地炸了。还有一个隐蔽的坑是全局ts-node和项目ts-node不统一。你用npm install -g ts-node装了一个全局版本项目里又装了一个局部版本直接在项目目录敲ts-node时系统可能用了全局那个而它解析TypeScript的方式和项目里完全不是一套兼容状况自然也不一样。排查这类问题第一件事永远是确认你实际用的是哪个版本、解析的是哪个TypeScript而不是瞎猜配置。2. 兼容问题的典型表现与排查思路2.1 最常见的三类报错先说说我在实际项目里遇到过的几类典型报错大家对照一下自己属于哪一类。第一类是运行时抛TypeError比如TypeError: types_1.default.createProgram is not a function这种报错最直观说明ts-node调用的某个TypeScript内部API不存在了。一般是TypeScript版本太新ts-node还在用老API或者反过来ts-node版本太新、TypeScript版本太老新API在旧版里压根没有。第二类是Node加载模块层面的报错TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension .ts这种情况出现在package.json里设置了type: module的项目中。ts-node默认按CommonJS方式加载代码如果你把项目声明成ESM模块两者就打架了。很多人以为这是版本不兼容其实是ts-node没开ESM模式。第三类是tsc编译阶段报错error TS5110: Option module must be set to NodeNext when option moduleResolution is set to NodeNext这类问题通常出现在TypeScript升级后新版tsc对module和moduleResolution的组合校验更严格了。你的代码本身没变tsconfig里也没动但编译器检查变严直接判了死刑。这严格说不是ts-node的锅但因为它俩经常一起用很多人误以为是ts-node的问题。2.2 先确认你实际装了什么版本遇到兼容问题第一步不是改代码而是确认当前环境里真实存在的版本号。注意这里说的是“真实存在”不是package.json里写的。package.json里的^5.3.0只是一个范围声明实际npm install装下来的可能是5.3.x系列里最新的一个。而且由于依赖嵌套项目里可能存在多个TypeScript版本比如某个第三方包自己依赖了一份TSnpm把它放到了node_modules/xxx/node_modules/typescript下面。ts-node默认从当前目录向上寻找typescript它找到的可能根本不是你在顶层声明的那一份。所以排查时要盯住实际命令行输出# 查看项目里实际安装的TypeScript版本 ./node_modules/.bin/tsc --version # 或 node -e console.log(require(typescript/package.json).version) # 查看ts-node实际版本 ./node_modules/.bin/ts-node --version # 或 node -e console.log(require(ts-node/package.json).version)再看一眼依赖树确认TypeScript是不是只有一份npm ls typescript如果输出里出现多个版本比如一个在顶层、一个嵌套在某个依赖下面那就要考虑是不是多版本解析导致的问题了。我遇到过最典型的场景是一个老依赖内部锁死了TS版本npm把它装成了嵌套版本而ts-node解析到了这个嵌套版本和顶层tsc用的完全不是同一个编译内核行为自然不一致。3. 查看兼容版本的方法3.1 peerDependencies是最权威的起点解决兼容问题的核心就是找到ts-node官方声明支持的TypeScript版本范围。这个信息就藏在package.json的peerDependencies字段里你不需要去翻GitHub文档用npm view命令直接看就行。npm view ts-node peerDependencies在npm 7以上的版本里输出类似{ typescript: 2.7 }这说明当前最新版的ts-node声明兼容TypeScript 2.7及以上版本。注意这只是ts-node作者给出的“理论支持范围”实际操作中你会发现范围虽然很宽但具体到某些TS大版本仍然会有兼容性摩擦尤其是TS新版本刚发布的那段时间。如果项目里用的不是最新版ts-node想看特定版本的peerDependencies可以带版本号查询npm view ts-node10.9.2 peerDependencies npm view ts-node9.1.1 peerDependencies npm view ts-node8.10.2 peerDependencies不同版本的ts-node对TypeScript的支持范围不一样。老版本ts-node对新版TypeScript的支持往往滞后比如ts-node 8.x时代TS刚出4.0时就有不少报错案例。通过这个命令你能快速判断自己手上的ts-node和TS版本能不能搭。3.2 用npm view把版本历史翻出来只看最新版的peerDependencies还不够很多时候我们需要在“能用”和“最新”之间找一个平衡点。这时要把两个包的历史版本都翻出来对比。查看ts-node的所有历史版本npm view ts-node versions --json输出会是一长串版本号数组从0.x到10.x都有。但这还不够你还得知道每个版本大概是什么时候发布的因为“发布时间”能直接反映它是否适配某个TS大版本。查看各版本发布时间npm view ts-node time --json输出格式大概是{ 0.1.0: 2015-03-01T..., 10.9.1: 2022-10-26T..., 10.9.2: 2023-03-27T... }这时候再对比TypeScript大版本的发布时间比如TypeScript 5.0是2023年3月发布的那你就应该优先选择发布时间在2023年3月之后的ts-node版本。这个思路比我见过很多人“无脑升到最新”靠谱得多——你说不准刚发布的ts-node是不是适配了最新的TS但你可以确定它没有机会适配那些还没发布的TS版本。看TypeScript最新版本号同样用npm命令npm view typescript version3.3 一份可参考的版本组合表把npm view的输出和个人实测经验整理一下我平时排查版本问题时基本参考下面这张表ts-node 版本TypeScript 兼容范围Node.js 建议实际推荐度10.9.22.7实测推荐 4.2 ~ 5.x 12建议 16/18/20最推荐配 TS 5.x 最稳10.8.x2.7 12能用和 TS 5.0 早期版本有摩擦9.1.12.7 10老项目常用配 TS 4.x 没问题8.10.22.0 8适合 TS 3.x 时代Node 18 会有警告这张表不是绝对的但能省下很多试错时间。如果你项目里的组合和表里的“推荐”差距很大比如ts-node 10.9.2配TypeScript 5.5虽然理论上可行但遇到问题时要优先怀疑组合本身。提示查兼容版本时别只看npm页面上的“Dependencies”标签那只是运行时依赖真正决定兼容范围的是peerDependencies和devDependencies。npm官方页面会把这两个混在一起展示容易看走眼。4. 实操把不兼容的版本调整到能用4.1 项目出问题后的标准处理流程不管报错长什么样只要锁定是tsc和ts-node版本兼容导致的都可以按下面这个流程处理。第一步锁定基准。先看项目里有没有“不能动的”约束。比如项目同时使用了TypeORM、NestJS、Ant Design这类对TS版本有要求的框架它们会在peerDependencies里声明兼容范围。用npm view typeorm版本 peerDependencies --json这类命令查一下确定TS版本的可选区间。第二步做取舍。方向有两个升级ts-node或降级TypeScript。如果项目里没有老依赖卡着TS版本优先升级ts-node到最新稳定版因为新版本通常修复了老版本的兼容问题。如果项目里有一堆老库还在用TS 3.x的API那就要考虑保留老TS为它找配套的老ts-node。第三步修改版本号并重新安装。以TypeScript 5.3配ts-node 10.9.1报错为例处理方式是把ts-node升到10.9.2npm install -D ts-node10.9.2如果升级ts-node反而带来新问题那就降TSnpm install -D typescript4.9.5第四步重新安装依赖后做最小验证./node_modules/.bin/ts-node -e console.log(ok)能用再跑正式代码别直接去启动整个项目避免新报错和旧报错混在一起干扰判断。4.2 ESM和Node版本相关的附加坑版本兼容问题不是唯一的坑ts-node还特别容易踩ESM的雷。如果项目根目录的package.json里有下面这行type: module整个项目都会被Node当成ESM模块处理。这时候直接运行ts-node大概率会报ERR_UNKNOWN_FILE_EXTENSION。解决办法有几个按场景选如果你只是偶尔跑一下单文件用esm模式npx ts-node --esm src/index.ts如果你在调试一个ESM项目更推荐的方案是配置tsconfig.json把模块体系设置清楚{ compilerOptions: { module: NodeNext, moduleResolution: NodeNext } }但这里有个细节如果你的代码既要被tsc编译成dist又要被ts-node直接运行module: NodeNext可能会让tsc输出格式变成你不想看到的产物。我建议这种项目里给ts-node单独建一份tsconfig比如tsconfig.ts-node.json然后通过环境变量或命令行指定。Node.js版本本身也要留意。ts-node 10.x要求Node 12但在Node 18/20上跑起来最省心。老项目如果还在用Node 10那就要选ts-node 9.x甚至8.x否则可能启动就报错。4.3 团队协作里的版本锁定策略版本问题在单人项目里折腾一会儿也就好了最怕的是整个团队几个人同时升级依赖然后互相污染。我见过一个项目A同事把TS升到5.0B同事没升两人提交的代码在CI上跑出的行为完全不一样查了半天才发现是node_modules不一致。从源头上解决要做三件事。第一件package.json里用精确版本号去掉^和~devDependencies: { ts-node: 10.9.2, typescript: 5.3.3 }第二件用npm overrides或resolutions强制锁定嵌套依赖里的TypeScript版本避免出现多版本并存overrides: { typescript: 5.3.3 }第三件固定Node版本。项目根目录放个.nvmrc写入18.20.4这类版本号团队用nvm切换。虽然Node版本影响的是ts-node本身的运行但很多报错在特定Node版本下才会出现统一Node版本能减少大量不确定性。如果团队比较大还可以加一个简单的版本校验脚本在npm install之后跑一遍node -e const tsrequire(typescript/package.json); const noderequire(ts-node/package.json); console.log(TS:ts.version ts-node:node.version)把输出贴进CI日志任何人都能一眼看到实际版本组合排查效率翻倍。在版本调整的实际过程中我总结了一套简单的取舍标准如果项目没有历史包袱优先“TS 4.9.x ts-node 10.9.2”如果项目里全是新代码可以直接“TS 5.x ts-node 10.9.2”。这两个组合是我踩过最多坑之后留下的最稳搭配不敢说百分之百不出问题但至少90%的兼容性报错都能避开。4.4 多包仓库和全局工具的特殊处理前面讲的都是常规单包项目如果项目是npm workspace或者monorepo结构还要考虑另一个问题——ts-node从哪个目录解析TypeScript。npm workspace会把依赖提升到根目录的node_modules但子包内部也可能有嵌套的node_modules。如果ts-node安装在根目录你从一个子包目录里跑ts-node它向上层目录查找typescript时可能找到的是根目录那份如果你在一个子包里单独安装了不同版本的typescript情况就变得更加复杂。遇到这种场景不看代码、只管版本号往往无效。我的处理习惯是monorepo里统一只在根目录安装typescript和ts-node子包不单独安装。这样整个仓库只有一个TypeScript实例从任何子目录运行ts-node解析到的都是同一份代码行为可预测。代价是某些子包可能需要和根目录版本对齐但换来的是稳定性和排障效率。5. 常见问题与排查技巧实录5.1 常见问题速查表把实际工作里遇到的典型问题整理成一张表按图索骥就好现象可能原因解决方向createProgram is not a functionTS版本过新/过老API不匹配升级或降级ts-node对齐TS版本ERR_UNKNOWN_FILE_EXTENSIONpackage.json里设置了type: module用ts-node --esm或用.mts扩展名TS5110 Option module must be set to NodeNexttsconfig配置不合法新版TS校验变严调整module和moduleResolution组合启动时有大量ExperimentalWarningts-node版本太老Node版本太新升级ts-node或换用tsx等工具项目里有多个typescript版本某个依赖嵌套安装了TS用overrides强制顶层单版本命令行跑ts-node和npx ts-node结果不一样全局ts-node和项目ts-node版本不一致统一用项目内的./node_modules/.bin/ts-node这张表覆盖了我在实际项目里遇到的绝大多数情况也基本覆盖了网上相关讨论里出现的高频问题。如果你遇到的是表外的情况建议把完整的报错信息和npm ls typescript、npm ls ts-node的输出一起贴到issue里比单纯贴一句“运行不了”更容易获得帮助。5.2 两个很实用的排查技巧第一个技巧升级TypeScript大版本之前先看ts-node的release notes。npm只是包管理工具它不知道什么版本搭配起来好用。在GitHub的ts-node Releases页面每个版本都会列出来修复了哪些和TypeScript版本相关的问题。比如ts-node 10.9.2的release notes里写着修复了TypeScript 5.0兼容性这就是最直接的线索。第二个技巧用npm view对比发布时间判断版本是否适配。这个前面提过但实际操作中值得反复使用。举个例子你想把TS升到5.4先查一下TS 5.4的发布时间再查ts-node最新版的发布时间如果ts-node比你手上的TS新那大概率没问题如果TS 5.4是本周刚发布的ts-node还是上个月的版本那就谨慎一点等一等再升。第三个技巧到了实在没辙的时候用npx直接跑一个临时组合来验证比改package.json再反复npm install快得多。比如想验证ts-node 9.1.1配TS 4.3能不能跑通可以在一个临时目录里执行npx -p ts-node9.1.1 -p typescript4.3.5 ts-node -e console.log(hello)这条命令会临时安装这两个指定版本的包然后运行ts-node执行一段简单代码。能跑通说明组合可行跑不通立刻换下一个组合全程不污染当前项目。我个人在实际操作中的体会是版本兼容问题80%靠“先确认实际版本再查peerDependencies最后调整版本”这三步就能解决。剩下的20%可能是ESM配置、Node版本、多包仓库这些叠加因素但只要排查思路清晰一步一步排除最终都能找到原因。tsc和ts-node这对工具就像厨房里的锅和铲单个看都没问题配套不合适做菜就硌手。真正吃几次亏以后我现在拿到任何新仓库的第一件事就是先跑一遍npm ls typescript ts-node确认版本组合再动手写代码。养成这个习惯之后被版本问题卡住的频率低了很多。