把现有的 Ja vaScript 项目，按阶段、循序渐进地迁移到 TypeScript。

迁移策略

• 添加 tsconfig.json
• 重命名 .js 为 .ts
• 逐步添加类型注解
• 启用严格模式

配置 tsconfig.json

迁移初期，建议先使用宽松配置。

这样可以先完成接入，再逐步收紧检查规则。

tsconfig.json

{
    "compilerOptions": {
        // 初始阶段：宽松配置
        "target": "ES2020",
        "module": "commonjs",
        "strict": false,
        "noImplicitAny": false,
        "strictNullChecks": false,
        "skipLibCheck": true,
        // 允许 JS 文件
        "allowJs": true,
        "checkJs": false,
        // 输出目录
        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
}

逐步启用严格检查

严格模式不必一次性全部开启。

更稳妥的做法是分阶段启用，降低迁移风险。

分阶段启用

// 阶段 1: 基础迁移
{
    "compilerOptions": {
        "strict": false,
        "noImplicitAny": false
    }
}
// 阶段 2: 启用类型检查
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true
    }
}
// 阶段 3: 完全严格
{
    "compilerOptions": {
        "strict": true,
        "noImplicitAny": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "strictPropertyInitialization": true
    }
}

JSDoc 类型注释

在 Ja vaScript 里，也可以借助 JSDoc 来补充类型信息。

这适合还未完全改成 TypeScript 的阶段。

utils.js

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
    return a + b;
}
/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} name
 * @property {string} email
 */
/**
 * @param {number} id
 * @returns {Promise}
 */
function getUser(id) {
    return fetch(`/api/users/${id}`).then(r => r.json());
}

运行结果：

JSDoc 注释添加成功

类型声明文件

为没有类型定义的模块创建声明。

这是补齐类型信息的重要方式。

src/types/my-module.d.ts

declare module "my-module" {
    export function doSomething(param: string): void;
    export class MyClass {
        constructor(options: { name: string });
        name: string;
    }
}

declare 关键字

declare 可用于声明全局变量、全局函数和命名空间。

它能帮助项目在迁移中更顺畅地接入现有能力。

实例

// 声明全局变量
declare var GLOBAL_CONFIG: {
    apiUrl: string;
    version: string;
};
// 声明全局函数
declare function myFunction(param: string): void;
// 声明命名空间
declare namespace MyNamespace {
    function doSomething(): void;
}
// 使用
console.log(GLOBAL_CONFIG.apiUrl);
myFunction("hello");
MyNamespace.doSomething();

运行结果：

声明成功

迁移工具

• tsc --allowJs：编译 JS 文件
• checkJs：检查 JS 类型
• // @ts-check：单文件类型检查
• // @ts-ignore：忽略错误

legacy.js

// @ts-check
// @ts-ignore
var result = someLegacyFunction();

最佳实践

• 从关键模块开始迁移
• 添加单元测试
• 逐步启用严格模式
• 使用 JSDoc 注释
• 创建类型声明文件

总结

• 渐进式：逐步迁移
• JSDoc：类型注释
• 声明文件：.d.ts
• 严格模式：分阶段启用