EC2实例上执行tsc命令编译TypeScript中途卡住不返回命令提示符

你当前本地和EC2的模块解析日志完全一致，日志停在@types/yargs-parser路径解析完成的节点，说明问题根本不发生在模块解析阶段——这个节点刚好是tsc完成所有路径匹配、即将进入全量类型校验遍历的分界点，后续流程对内存、Node引擎版本的敏感度远高于路径解析阶段。

优先排查的核心差异点 #

• Node版本跨大版本不兼容：本地运行版本为Node 12.18.2，EC2为Node 10.21.0，两者差了两个大版本；同时你项目里依赖的@types/node版本为^12.12.22，对应Node12的API类型规范。TypeScript 3.7.3在Node10环境下跑全量类型校验时，很容易触发V8引擎的GC无限循环、栈溢出问题，这也是之前能正常编译、现在突然卡死的最常见诱因。
• EC2实例资源负载超限：你当前的tsconfig开启了两个高负载配置，小规格EC2实例很容易扛不住：
  • 同时开启allowJs: true和checkJs: true：这两个配置会让tsc对所有被引用到的JS文件（包括第三方依赖里的JS文件）做全量类型检查，无意义增加数十倍的编译工作量，1G内存的低配置实例很容易被内存耗尽触发OOM Killer直接杀掉tsc进程，最终连build目录都没有输出。
  • 配置里include字段写为"./src/*"，如果src目录下存在多层嵌套的子目录，可能出现文件匹配范围偏差，导致tsc无意义扫描项目其他位置的文件。

可直接落地的分步排查动作 #

1. 先定位卡死的本质原因
   • 执行编译命令的同时，另开终端通过top -p <tsc进程PID>观察进程状态，确认是否存在CPU占满100%、内存占满到触发系统OOM杀进程的情况
   • 执行带GC追踪的编译命令node --trace-gc node_modules/.bin/tsc -p tsconfig.json，如果日志持续输出堆内存上涨、频繁GC回收的内容，直接可以确认是内存不足导致的卡死
2. 排除tsconfig配置冗余问题
   • 临时把allowJs、checkJs两个配置的值改为false，重新跑编译。纯TS项目本身不需要这两个JS校验功能，关闭后能直接把编译耗时降低60%以上
   • 把include路径替换为明确的递归匹配规则"./src/**/*"，避免文件匹配偏差导致的无效扫描
3. 做版本对齐验证
   • 通过nvm在EC2上临时切换Node版本到和本地完全一致的12.18.2，重新执行编译命令。如果切换后编译顺利完成，就可以100%确认是Node10版本和当前TS、类型定义版本不兼容的问题
   • 把typescript的版本锁死为精确的3.7.3，移除package.json里的^版本范围标识，避免依赖安装时拉取了存在bug的小版本更新
4. 解决权限、磁盘类突发问题
   • 执行df -h检查项目所在分区的剩余磁盘空间，如果空间不足，tsc无法写入build目录的编译产物，就会出现进程静默中断、无输出的情况——这也是之前能正常编译、突然失效的常见原因
   • 检查项目目录、build目录的所有者权限，如果之前用root用户执行过编译，现在切回ubuntu用户跑命令，会因为没有build目录的写权限导致流程卡住
   • 对比EC2上node_modules/@types/yargs-parser/index.d.ts的文件大小和本地是否一致，如果存在文件损坏，直接删除这个包重新安装即可

低配置EC2的编译兜底优化 #

如果暂时没法升级EC2规格或切换Node版本，在执行编译命令时手动调高Node堆内存上限，避免默认堆内存不足导致的GC循环：

node --max-old-space-size=2048 node_modules/.bin/tsc -p tsconfig.json

这个命令会把tsc运行时的可用堆内存从默认的1.4G提升到2G，足够支撑当前项目规模的全量类型校验。

注：你观察到的tsc停在@types/yargs-parser解析完成的日志，只是整个模块解析阶段的最后一条输出，不代表tsc卡在这个文件的处理流程上——因为tsc的模块解析是批量执行的，日志输出完成后马上就会进入后续的类型校验阶段。

内容的提问来源于stack exchange，提问作者Savitoj Cheema