TypeScript 迁移实战

7 minIntermediate2026/5/3

渐进式迁移策略、类型覆盖提升与常见迁移陷阱。

1. 迁移前准备

1.1 环境配置

 # 安装 TypeScript
 npm install typescript --save-dev
 # 初始化 tsconfig.json
 npx tsc --init

1.2 项目分析

代码规模: 评估项目大小和复杂度
依赖分析: 检查第三方库的类型支持情况
代码质量: 评估现有 JavaScript 代码的质量
团队技能: 评估团队成员对 TypeScript 的熟悉程度

2. 迁移策略

2.1 渐进式迁移

阶段一: 配置 allowJs 和 checkJs，不强制类型检查
阶段二: 为关键文件添加类型注解
阶段三: 逐步将 .js 文件转换为 .ts 文件
阶段四: 启用严格模式，完善类型定义

2.2 迁移方法

2.2.1 直接重命名法

 # 重命名文件
 mv src/index.js src/index.ts
 # 修复类型错误
 npx tsc --noEmit

2.2.2 JSDoc 注解法

// @ts-check
/**
 * 计算两个数的和
 * @param {number} a 第一个数
 * @param {number} b 第二个数
 * @returns {number} 两数之和
 */
function add(a, b) {
  return a + b;
}

2.2.3 类型声明法

// types/index.d.ts
declare module 'my-module' {
  export function someFunction(): void;
}

3. 配置优化

3.1 基础配置

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowJs": true,
    "checkJs": false,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noImplicitAny": false,
    "strict": false
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

3.2 渐进式严格模式

阶段	配置	说明
1	`strict: false, noImplicitAny: false`	初始阶段，减少类型错误
2	`strict: false, noImplicitAny:`	开始添加类型注解
3	`strict:`	完全启用严格模式

4. 实战案例

4.1 React 项目迁移

4.1.1 组件迁移

// 从 JavaScript
function Button({ onClick, children }) {
  return <button onClick={onClick}>{children}</button>;
  ;
}
// 到 TypeScript
import React from 'react';
interface ButtonProps {
  onClick: () => void;
  children: React.ReactNode;
  ;
}
const Button: React.FC<ButtonProps> = ({ onClick, children }) => {
  return <button onClick={onClick}>{children}</button>;
  ;
};

4.1.2 状态管理

// 从 JavaScript
import { useState } from 'react';
function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}
// 到 TypeScript
import { useState } from 'react';
function Counter() {
  const [count, setCount] = useState<number>(0);
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

4.2 Node.js 项目迁移

4.2.1 模块导入

// 从 JavaScript
const fs = require('fs');
const path = require('path');
// 到 TypeScript
import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

4.2.2 Express 应用

// 从 JavaScript
const express = require('express');
const app = express();
app.get('/', (req, res) => {
  res.send('Hello World!');
});
app.listen(3000, () => {
  console.log('Server started on port 3000');
});
// 到 TypeScript
import express from 'express';
const app = express();
app.get('/', (req: express.Request, res: express.Response) => {
  res.send('Hello World!');
});
app.listen(3000, () => {
  console.log('Server started on port 3000');
});

4.3 通用项目迁移

4.3.1 工具函数

 // 从 JavaScript
 function debounce(func, wait) {
  let timeout;
  return function() {
  const context = this;
  const args = arguments;
  clearTimeout(timeout);
  timeout = setTimeout(() => func.apply(context, args), wait);
  };
 }
 // 到 TypeScript
 function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait: number
 )
  let timeout: NodeJS.Timeout;
  return function(...args: Parameters<T>) {
  const context = this;
  clearTimeout(timeout);
  timeout = setTimeout(() => func.apply(context, args), wait);
  };
 }

4.3.2 类和对象

// 从 JavaScript
class Person {
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }
  greet() {
    return `Hello, my name is ${this.name}`;
  }
}
// 到 TypeScript
class Person {
  constructor(
    private name: string,
    private age: number
  ) {}
  greet(): string {
    return `Hello, my name is ${this.name}`;
  }
  getAge(): number {
    return this.age;
  }
}

5. 类型定义管理

5.1 第三方库类型

 # 安装类型定义
 npm install @types/node @types/express @types/react --save-dev

5.2 自定义类型声明

// types/index.d.ts
declare global {
  interface Window {
    myApp: {
      version: string;
      config: Record<string, any>;
    };
  }
}
export {};

5.3 类型导入导出

// types/user.ts
export interface User {
  id: number;
  name: string;
  email: string;
  ;
}
// src/components/UserProfile.tsx
import { User } from '../types/user';
interface UserProfileProps {
  user: User;
  ;
}

6. 常见问题与解决方案

6.1 类型错误

错误	原因	解决方案
`Type 'undefined' is not assignable to type 'string'`	未处理空值	使用可选链或空值合并操作符
`Object is possibly 'null'`	未处理 null 值	使用类型守卫或非空断言
`Property 'x' does not exist on type 'Y'`	属性不存在	添加类型定义或使用索引签名
`Argument of type 'X' is not assignable to parameter of type 'Y'`	类型不匹配	修正类型注解或使用类型断言

6.2 模块问题

问题	原因	解决方案
`Cannot find module 'x'`	模块路径错误	检查导入路径或添加类型声明
`Module 'x' has no exported member 'y'`	导出成员不存在	检查模块导出或添加类型声明
`CommonJS module require()`	模块系统不兼容	使用 ES 模块语法或配置 `esModuleInterop`