JS 转 TS 手动迁移最佳实践：从配置 tsconfig 到消除 any 类型

将庞大或活跃迭代的现有 JavaScript 代码库迁移至 TypeScript，最稳妥的策略不是一揽子全量重写，而是采用“双轨共存、自底向上、阶梯加固”的手动渐进式迁移方案。本文通过梳理真实的工程演进链路，从搭建兼顾 JS/TS 的编译管道开始，详解核心 tsconfig.json 选项的阶段性取舍，再依照模块拓扑依赖逐步替换文件，最终运用 unknown、类型守卫与判别式联合等技术消除代码中的隐式与显式 any，帮助项目在不中断业务迭代的前提下平稳建立静态类型防护网。

一、迁移核心原则与执行流水线

很多工程团队在启动 TypeScript 迁移时，往往试图通过全局脚手架直接重命名所有 .js 文件，结果产生数千条编译器报错；或者为了让构建快速通过，在各类变量和参数上肆意添加 any。这两种极端做法要么导致正常业务交付停摆，要么仅仅得到了一个“披着 TS 外皮的纯 JS”，丢失了静态类型的所有工程收益。

手动迁移的成功关键在于建立一条具备防御性的五步流水线：基建双轨先行、依赖拓扑逐层推进、边界声明补齐、核心逻辑消除 any、最终开启全严格模式与 CI 防线。在这个过程中，未迁移的 JavaScript 模块与已迁移的 TypeScript 模块可以在同一套构建管道中协同运行。

在迁移全生命周期中，应严格遵守三条底线原则：

• 双轨共存原则：构建管道必须同时接纳 .js 与 .ts 源码，每一次 Git 提交都必须保证本地与生产环境可正常构建并部署。
• 自底向上原则：坚决杜绝从页面层或控制器层向下重构，必须从叶子节点（如无依赖的常量、纯工具函数、模型接口）开始重命名与收窄类型。
• 类型防腐原则：迁移一个模块，就彻底闭环一个模块的类型契约，绝不将临时 any 泄露扩散至上游依赖。

二、第一步：搭建双轨编译环境与 tsconfig 渐进配置

在现有项目中引入 TypeScript，首先需要在根目录安装核心依赖，并确保 TypeScript 编译器仅充当“类型检查员”，而不侵入既有的打包逻辑（例如原有的 Webpack、Vite 或 Babel 流水线）。

执行以下命令安装核心依赖：

# 根目录下安装 typescript 及基础 node 类型定义
npm install -D typescript @types/node

# 初始化默认配置文件
npx tsc --init

生产级迁移不能直接套用默认生成的 tsconfig.json。根据迁移推进的节奏，配置项需要划分为“初期双轨基线”、“中期拓扑拆迁”与“终态严格守卫”三个矩阵阶段。

1. 阶段一配置：允许双轨构建与无害接入

在迁移第一阶段，重点是让 tsc 命令能够在不打断旧 JS 运行的前提下跑通。此时必须显式启用 allowJs 并关闭 checkJs，避免数百个旧 JS 文件瞬间爆出类型报错。

// tsconfig.json - 阶段一基准配置
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    
    // 双轨共存核心开关
    "allowJs": true,           // 允许工程中同时存在 .js / .jsx 源码
    "checkJs": false,          // 暂不强制对遗留 .js 文件进行类型校验
    "noEmit": true,            // tsc 仅执行类型静态检查，打包输出继续由 Webpack/Vite 负责
    
    // 兼容性与性能保障
    "esModuleInterop": true,   // 解决 CommonJS 与 ES Module 混合引入时的 default 识别问题
    "allowSyntheticDefaultImports": true,
    "skipLibCheck": true,      // 跳过 node_modules 内部 .d.ts 声明文件的比对，显著提升编译性能
    "forceConsistentCasingInFileNames": true,

    // 路径映射（需与打包工具 alias 保持完全一致）
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },

    // 阶段一暂不开启全部严格规则
    "strict": false
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "build"]
}

三、第二步：分层重命名与边界类型隔离

配置就绪后，不要盲目挑选业务复杂的页面进行迁移。如果优先迁移上层组件，上层组件调用的底层工具函数仍然是无类型的旧 JavaScript，会导致上层组件不得不为返回值编写宽泛的 any 占位，形成类型污染。

1. 自底向上的模块迁移拓扑

合理的重命名实施序列应该严格遵循依赖倒置拓扑：

1. 常量与配置字典（Constants & Configs）：完全无外部导入，重命名为 .ts，补充 as const 锁定字面量类型。
2. 通用纯工具函数（Utils & Helpers）：通常只有输入输出计算，极易推导明确的形参与返回值类型。
3. 数据传输对象与实体接口（Models & Entities）：梳理 API 响应与业务状态字段，声明统一的 interface 或 type。
4. 网络请求与数据访问层（Services & APIs）：将请求参数和返回 Promise 绑定至刚才定义的数据模型。
5. 业务组件与控制器（Components & Controllers）：最后改造上层业务模块，消费底层强类型。

2. 用声明文件（.d.ts）隔离未迁移的旧 JS 模块

在自底向上重构期间，已经转为 .ts 的文件若不可避免需要调用某些遗留的 .js 复杂模块，直接 import 会提示缺少类型。此时应当在项目内建立垫片声明目录 src/types/shims/，为旧模块撰写局部签名：

// src/types/shims/legacy-logger.d.ts
// 为尚未迁移的 src/utils/legacyLogger.js 提供类型隔离，避免在调用方写 any
declare module "@/utils/legacyLogger" {
  export interface LogMeta {
    timestamp: number;
    level: "info" | "warn" | "error";
  }
  export function recordLog(message: string, meta?: LogMeta): void;
}

通过提供精确的局部 declare module，可以在不改变旧 JS 文件内容的前提下，将类型污染阻断在边界之外。

四、第三步：消除 any 的四大系统性策略

迁移过程中最隐蔽的陷阱是“any 病毒”。在 TypeScript 中，any 是双向自由的逃生门：它可以赋值给任何类型，也可以接受任何类型的赋值。一旦一个模块的返回值被声明为 any，下游所有引用该值的逻辑都会无感丢失类型检查。

策略一：用 unknown 替代 any 建立第一道防线

当处理外部未知数据源（例如 JSON.parse、第三方 SDK 返回值或 window.fetch 响应体）时，不要写 any，一律声明为 unknown。unknown 是类型安全的顶级类型：任何值都可以赋给 unknown，但在未经检查收窄之前，禁止在其上执行任何方法或属性访问。

// ❌ 错误做法：使用 any 导致运行时潜伏崩溃
function parseUserBad(rawJson: string): any {
  return JSON.parse(rawJson);
}
const userBad = parseUserBad('{"name":"Alice"}');
userBad.account.balance.toFixed(2); // 编译通过，运行时报 TypeError: Cannot read properties of undefined

// ✅ 正确做法：使用 unknown 迫使调用者建立类型保护
interface UserAccount {
  name: string;
  account?: {
    balance: number;
  };
}

function parseUserSafe(rawJson: string): unknown {
  return JSON.parse(rawJson);
}

const rawData = parseUserSafe('{"name":"Alice"}');
// rawData.account; // ❌ 编译报错：TS2571: Object is of type 'unknown'.

// 配合类型收窄或验证库解析后方可使用
function isValidUser(val: unknown): val is UserAccount {
  return (
    typeof val === "object" &&
    val !== null &&
    "name" in val &&
    typeof (val as Record<string, unknown>).name === "string"
  );
}

if (isValidUser(rawData)) {
  console.log(rawData.name); // ✅ 安全访问
}

策略二：编写类型谓词（is）自定义类型守卫

在复杂的 JavaScript 业务逻辑中，经常需要依据某个属性是否存在或判断某个字段值来分发逻辑。使用 TypeScript 的自定义类型守卫（User-Defined Type Guard），通过 parameterName is Type 签名，能够让条件判断语句直接成为编译器的类型收窄工具。

interface SuccessResponse<T> {
  status: "success";
  payload: T;
}

interface FailureResponse {
  status: "error";
  code: number;
  errorMessage: string;
}

type ApiResponse<T> = SuccessResponse<T> | FailureResponse;

// 类型守卫函数
function isSuccessResponse<T>(res: ApiResponse<T>): res is SuccessResponse<T> {
  return res.status === "success";
}

// 业务消费场景
function handleResult(res: ApiResponse<{ id: string; email: string }>) {
  if (isSuccessResponse(res)) {
    // 自动收窄为 SuccessResponse，IDE 支持 payload 提示
    console.log("用户邮箱：", res.payload.email);
  } else {
    // 自动收窄为 FailureResponse
    console.error(`错误 [${res.code}]: ${res.errorMessage}`);
  }
}

策略三：运用判别式联合（Discriminated Union）替代扁平 any 对象

在旧 JS 中，开发者常使用一个包罗万象的“万能对象”来传递不同状态的数据，例如同时包含支付状态、取消原因、发货单号等。在 TS 迁移中，应当将其拆解为判别式联合，利用公共单例属性（如 kind、type 或 status）消除空值断言与 any 强转。

// ❌ 传统 JS 的扁平弱类型设计
// function processOrder(order: any) { ... }

// ✅ 重构为清晰的判别式联合
interface PendingOrder {
  state: "PENDING";
  orderId: string;
  createTime: number;
}

interface PaidOrder {
  state: "PAID";
  orderId: string;
  paidAmount: number;
  transactionId: string;
}

interface CancelledOrder {
  state: "CANCELLED";
  orderId: string;
  cancelReason: string;
}

type Order = PendingOrder | PaidOrder | CancelledOrder;

function renderOrderSummary(order: Order): string {
  switch (order.state) {
    case "PENDING":
      return `待支付订单：${order.orderId}`;
    case "PAID":
      return `已支付 ${order.paidAmount} 元，交易流水号：${order.transactionId}`;
    case "CANCELLED":
      return `订单已取消，原因：${order.cancelReason}`;
    default: {
      // 利用 never 实现穷尽性检查（Exhaustiveness Checking）
      const _exhaustiveCheck: never = order;
      return _exhaustiveCheck;
    }
  }
}

策略四：泛型约束与 Record 字典精确化

在需要处理通用字典缓存或高阶包装函数时，许多人习惯声明 obj: any 或 params: any[]。正确的做法是使用泛型约束结合 Record<string, unknown>：

// 字典场景：明确 key 类型，值如果未知使用 unknown，避免使用 any
type SafeDict = Record<string, unknown>;

// 函数包装场景：精确推导参数与返回值
function withLogging<TArgs extends unknown[], TReturn>(
  fn: (...args: TArgs) => TReturn
): (...args: TArgs) => TReturn {
  return (...args: TArgs): TReturn => {
    console.log("[EXEC] 开始调用，参数清单:", args);
    const result = fn(...args);
    console.log("[EXEC] 调用结束，返回值:", result);
    return result;
  };
}

五、第四步：开启严格模式与自动化拦截防线

当代码库中绝大部分核心模块已转换为 .ts 且业务逻辑完成了类型收窄后，便进入最终的固化收尾阶段。此时需要逐步收紧 tsconfig.json，并接入自动化卡点工具，防止后续迭代中产生新的类型倒退。

1. 逐步激活 strict 家族子项

如果直接开启 "strict": true 导致报错过多，可以先在 compilerOptions 中按顺序激活以下关键规则：

2. ESLint 规则与 CI 门禁闭环

仅仅依靠开发者的自律是无法彻底杜绝 any 的。必须在工程中配置 @typescript-eslint 规则集，并在持续集成（CI）流水线中配置阻塞型检查脚本：

// .eslintrc.cjs 关键规则配置
module.exports = {
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  rules: {
    // 严禁显式 any，确有必要时须通过行级注释特异性放行并说明原因
    "@typescript-eslint/no-explicit-any": ["error", { "fixToUnknown": true }],
    // 强制声明推导不出的函数返回值
    "@typescript-eslint/explicit-function-return-type": "off",
    // 严禁存在无法推导的 @ts-ignore，要求统一使用带有解释的 @ts-expect-error
    "@typescript-eslint/prefer-ts-expect-error": "error"
  }
};

在 package.json 中配置脚本：

{
  "scripts": {
    "type-check": "tsc --noEmit",
    "lint:types": "eslint src --ext .ts,.tsx --max-warnings 0"
  }
}

六、迁移成熟度检验清单与常见问题解答

在宣布一个模块或整个项目的迁移工作正式收尾前，应当使用以下清单逐一核对当前状态：

• 零编译报错：运行 npm run type-check（即 tsc --noEmit）输出退出码为 0，且无任何 warning。
• 全量业务文件转换：除必要打包脚本外，src/ 下不再存在任何 .js 或 .jsx 文件，tsconfig.json 中可将 allowJs 安全置为 false。
• 严格模式全局常驻："strict": true 正式成为全局配置，无全局性的忽略参数。
• any 归零治理：全项目 grep 检索 : any 与 as any，除特定底层跨平台驱动或老旧第三方库胶水层外，业务逻辑层实现零显式 any。
• 测试用例与生产构建校验：原有单元测试、集成测试全部通过，打包构建后生成的 bundle 体积与功能表现与迁移前完全一致。

常见迁移疑难排查

问：第三方老旧库没有提供 @types，且社区也没有维护，怎么处理？

答：切忌在每个引用处加 // @ts-ignore。应当在 src/types/declarations.d.ts 中统一补充模块垫片：

// 快速兜底垫片：如果库非常大，可先声明泛模块，后续逐步补充函数签名
declare module "legacy-chart-plugin" {
  const plugin: {
    init: (container: HTMLElement, options?: Record<string, unknown>) => void;
    destroy: () => void;
  };
  export default plugin;
}

问：全局挂载的 Window 扩展属性（如 window.__INITIAL_DATA__）引发 TS 报错，如何优雅解决？

答：不要使用 (window as any).__INITIAL_DATA__。利用 TypeScript 的声明合并（Declaration Merging）特性，对全局 Window 接口进行类型扩充：

// src/types/global.d.ts
export {};

declare global {
  interface Window {
    __INITIAL_DATA__?: {
      userId: string;
      role: "admin" | "user";
      config: Record<string, unknown>;
    };
  }
}

通过这套自底向上、阶梯加固的手动迁移路径，团队可以在维持常规产品交付节奏的同时，有条不紊地完成大型 JavaScript 项目的代码结构升级。随着 tsconfig 编译矩阵的逐级收紧与 any 类型的系统性清除，代码库将真正获得精准的代码导航、快速重构提示与高可靠的编译时安全屏障。