如何为已有JavaScript项目添加TypeScript？

给一个现成的JavaScript项目加上TypeScript，这事儿听起来有点吓人，但其实没那么可怕。你不需要一口气把所有.js文件都改成.ts，那会要人命的。咱们得用“渐进式”的策略，像打游击战一样，一点点蚕食，最终赢得胜利。

第一步，先把TypeScript请进门。用npm或者yarn安装typescript包，然后在项目根目录创建一个最基本的tsconfig.json。这个配置文件一开始不用太复杂，关键是开几个口子：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "outDir": "./dist",
    "target": "esnext",
    "module": "esnext",
    "strict": false
  },
  "include": ["./src/**/*"]
}

注意看，allowJs: true是灵魂。它允许TypeScript和JavaScript文件在同一个项目里共处。先别急着开严格模式，那会炸出成千上万个错误。咱们先让编译能跑通，建立信心。

接下来，选一个你觉得最顺眼、或者逻辑最清晰的工具类文件，把它从.js重命名为.ts。TypeScript编译器通常会抱怨几句，最常见的错误是“找不到模块声明”。这时候别慌，对于还没类型的第三方模块，你可以先在项目里创建一个global.d.ts或者shims.d.ts文件，做个快速声明：

declare module 'that-old-module';

这一句就相当于告诉TS：“这个模块存在，你先别管它。” 虽然类型安全是零，但至少编译能过了。这是过渡期的权宜之计。

开始给你的代码加类型。从函数的参数和返回值开始，这是性价比最高的地方。比如一个工具函数：

// 原来是
function add(a, b) {
  return a + b;
}

改成：

function add(a: number, b: number): number {
  return a + b;
}

立刻，所有调用这个函数的地方，如果传了字符串，编辑器就会给你画红线。这种即时反馈特别有成就感。

处理对象结构时，用interface或者type给它定义个形状。别追求一步到位，先定义你当前用到的几个关键属性，剩下的可以暂时标为可选的，或者用any过渡一下。

渐进迁移的精髓在于“逐个击破”。改好一个模块，就把它相关的依赖和调用也逐步更新类型。你会发现自己慢慢构建起一张类型安全网。这时候，可以逐渐在tsconfig.json里把strict设为true，然后打开noImplicitAny这样的严格选项。每开一个，就修复一批错误。这个过程有点像打扫房间，一开始乱，但会越扫越干净。

对于实在复杂、暂时没精力处理的遗留文件，你可以保持它的.js后缀，然后在相邻位置创建一个同名的.d.ts声明文件，只描述它的公共接口。这样，其他TS文件在导入它时，就能获得类型安全了。

整个迁移过程，核心思路是“不破坏现有功能，逐步增强安全”。别想着一周内搞定一个大项目，把它当成一个持续数周甚至数月的“代码卫生”改善运动。每当你修改或重构某个老旧文件时，顺手就给它加上类型。时间久了，你会发现代码库的可读性和可维护性不知不觉上了一个大台阶。