大型ES5项目渐进式迁移至TypeScript的最优方案咨询

迁移路径选择 #

直接选第一类路径，第二类先转UMD的方案完全不推荐，原因很简单：

• 第二类路径要求你在启动TS迁移前，先给数千个全局脚本做一轮UMD格式包装，属于额外的全量代码改动，工作量大、回归风险高，完全违背渐进式迁移“小步走、可暂停、低风险”的核心原则。UMD多模块格式兼容的优势在你这个阶段完全用不上——现有项目本来就是全局脚本运行模式，不需要额外兼容AMD/CommonJS/SystemJS等格式，做这步属于纯无效投入。

你梳理的第一类路径方向正确，但有几个实操细节需要调整，避免踩坑：

• 初始tsconfig.json不要只开allowJs，同步配置strict: false、noEmitOnError: false，初期不要开启任何严格类型检查规则，保证TS遇到类型报错时不会阻塞正常构建，先把编译链路跑通，后续再逐步收紧校验规则，避免刚启动就被满屏报错卡进度。
• 全局脚本阶段不要手动维护/// <reference path="">依赖指令，文件多了很容易出现漏写、依赖顺序错误的问题，维护成本极高。正确做法是在tsconfig的include字段里配置所有源码路径，TS会自动识别全局作用域下的函数、变量声明，不需要手动写引用指令。
• 文件后缀从.js改.ts的工作不要无差别批量做，按依赖优先级推进：先改通用工具函数、基础公共组件这类底层依赖文件，再改上层业务逻辑文件，每改完一个模块就跑一遍回归测试。改后缀初期不需要强行补全所有类型，先修好语法层面的报错（比如隐式全局变量、重名声明这类ES5遗留问题）就行，类型标注可以后续迭代慢慢补。
• 等全量文件都改成.ts、TS编译链路稳定运行1-2个迭代没有构建问题后，再启动ESM改造：从最底层的无依赖模块开始加export，上层调用方逐步替换为import，不要一次性全量切换，避免打乱原有全局脚本的加载顺序引发线上问题。

类型声明处理 #

不要依赖ts-loader自动生成声明文件做日常开发的类型提示，正确的处理方式是：

• 第三方依赖优先找社区维护的@types/*类型包，没有对应包的先写declare module '依赖包名'做宽松兜底，后续再补详细类型定义。
• 项目内的全局变量、公共方法，统一放到根目录typings文件夹下维护.d.ts全局声明，不要散落在各个业务文件里。
• ts-loader/tsc自动生成.d.ts的功能，等你后续全量切完ESM、需要抽离公共代码为独立NPM包的时候再开启就行，迁移阶段开了只会拖慢编译速度，生成的临时声明文件还会干扰开发。

编译工具选型：ts-loader vs Babel #

迁移初期优先选ts-loader，等全量迁移完成、编译速度成为瓶颈后再考虑换Babel，二者的适用限制很明确：

• ts-loader直接调用官方TypeScript编译器做转译，100%支持所有TS语法，类型检查和转译一步完成，配置简单，遇到问题直接查TS官方文档就能解决，非常适合迁移初期团队对TS编译链路不熟悉的阶段，唯一缺点是大项目下编译速度比Babel慢。
• Babel是通过@babel/preset-typescript做TS语法转译，本身不具备类型检查能力，需要额外单独执行tsc --noEmit做类型校验，而且不支持const enum、namespace等部分TS特有语法，配置相对复杂；优势是编译速度快，能无缝对接现有Babel生态的各类插件、polyfill方案，适合全量迁移完成、团队对TS配置足够熟悉之后，为了提效再切换。

迁移启动最小落地步骤（一周内可跑通） #

• 先安装typescript依赖，创建基础tsconfig配置，把TS类型检查集成到本地开发和构建流程，初期不阻断构建，先让开发能拿到基础的类型提示。
• 选一个依赖少、迭代改动频率低的小模块做试点，把模块内的JS文件改成TS，修完编译问题正常上线，跑通单模块迁移的完整流程，踩完小坑再往全量推。
• 后续每个迭代安排10%-20%的开发资源做模块迁移和类型补全，不搞突击式全量改造，保证每个版本的改动都可控可回滚。

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