frontend

JavaScript 项目迁移到 TypeScript 实战：渐进式策略与自动化工具

详解 JS 项目迁移到 TS 的渐进式策略：允许 JS 和 TS 共存、.d.ts 声明文件、ts-migrate 自动转换、any 逐步消除路径、第三方库类型声明处理。附完整的迁移检查清单。

Leeting Yan 2025-11-22 2 分钟阅读 610 字

把一个现有的 JavaScript 项目迁移到 TypeScript 不需要一次全部重写。TypeScript 支持"渐进式迁移"——允许 .js 和 .ts 文件在同一项目中并存，逐个模块迁移。本文提供经过验证的迁移路径和工具链。

一、迁移策略

策略一：松耦合 → 严约束（推荐）

1. 安装 TypeScript，配置 allowJs（允许 JS 文件编译）
2. 把所有 .js 改为 .ts（不使用类型，先跑通编译）
3. 逐步添加类型注解（从 API 层/工具函数开始）
4. 开启 strict 模式，消除 any

策略二：边界优先

1. 先给公共 API 和接口加上 .d.ts 声明文件
2. 新模块一律用 .ts 编写
3. 旧模块遇到 Bug 重构时顺便迁移
4. 核心业务逻辑最后迁移（因为最复杂）

二、第一步：安装与配置

npm install -D typescript @types/node
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowJs": true,            // ✅ 允许编译 JS 文件
    "checkJs": false,           // 先不检查 JS 的类型
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": false,            // 先关闭严格模式
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

三、自动转换工具

ts-migrate（Airbnb 出品）

npx ts-migrate-full folder-name

功能：

批量重命名 .js → .ts
自动添加 @ts-expect-error 注释到类型错误处
自动添加 any 类型占位

TypeStat

npx typestat --config typestat.json

功能更智能的自动类型推断工具。

四、渐进启用严格模式

{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": true,      // 第一步：禁用隐式 any
    "strictNullChecks": true,   // 第二步：null 检查
    "strictFunctionTypes": true, // 第三步：函数类型严格
    "strict": true              // 最终：全部严格
  }
}

五、第三方库类型处理

# 安装 DefinitelyTyped 类型声明
npm install -D @types/lodash @types/express

# 如果没有官方类型，创建 .d.ts 文件
echo "declare module 'legacy-lib';" > src/types/legacy-lib.d.ts

迁移检查清单

安装 TypeScript 和配置 tsconfig.json
配置 allowJs + rootDir
重命名核心模块为 .ts
处理第三方库类型声明
开启 noImplicitAny
启用 strictNullChecks
最终开启 strict: true
CI 中添加 tsc 编译检查

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页