向现有Node.js项目引入TypeScript的最优生产级工作流咨询

一、迁移策略：优先选择渐进式迁移 #

• 90%以上的生产项目都会采用渐进式迁移，一次性迁移仅适合文件数少于50的小型项目。
• 核心思路：先搭建TS编译环境，确保JS与TS能共存运行，再逐步将核心业务模块、新增代码改为TS，最后逐步淘汰JS文件。

二、过渡期间JS与TS共存的实操方案 #

1. 核心配置适配 #

修改tsconfig.json，让TS编译器兼容现有JS文件：

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false, // 初期关闭JS类型检查，避免大量报错阻塞进度
    "outDir": "./dist", // 编译产物单独存放
    "rootDir": "./src", // 源码根目录
    "module": "NodeNext", // 自动适配CJS/ESM混合场景
    "moduleResolution": "NodeNext",
    "target": "ES2020", // 匹配Node.js支持的ES版本
    "esModuleInterop": true, // 消除CJS与ESM导入语法差异
    "skipLibCheck": true, // 跳过第三方库类型检查
    "strict": false // 初期关闭严格模式，后续逐步开启子规则
  },
  "include": ["src/**/*"], // 包含所有JS/TS文件
  "exclude": ["node_modules", "dist"]
}

2. 构建工具选型 #

用tsup替代原生tsc或ts-node，它更快且自动处理模块兼容：

• 安装依赖：npm install tsup --save-dev
• 在package.json中添加脚本：

{
  "scripts": {
    "dev": "tsup src --watch", // 开发模式热更新
    "build": "tsup src", // 生产构建
    "start": "node dist/index.js" // 运行编译后的产物
  }
}

3. 类型补充方案 #

• 对现有JS文件，可通过JSDoc标注类型（比如/** @type {string} */），避免TS调用时出现类型缺失。
• 复杂JS模块可手动添加.d.ts声明文件，放在项目根目录的types文件夹中。

三、CommonJS与ESM冲突的解决方法 #

场景1：原有项目是CJS，新增TS用ESM #

• 在package.json中添加"type": "module"，将原有CJS文件重命名为.cjs，TS文件保持.ts（编译后默认输出ESM格式的.js）。
• tsconfig.json中module和moduleResolution设为NodeNext，编译器会自动识别文件后缀与package.json的type配置。

场景2：混合导入导出问题 #

• 导入CJS模块时，通过esModuleInterop: true支持import xxx from 'xxx'语法，无需手动写import * as xxx from 'xxx'。
• 禁止在同一文件中混用require和import，强制用TS的import语法，编译时自动适配目标模块系统。

场景3：第三方依赖模块冲突 #

• 安装@types/node确保Node.js内置模块的类型支持：npm install @types/node --save-dev
• 若第三方依赖只有CJS类型，在tsconfig.json中添加"allowSyntheticDefaultImports": true解决导入报错。

四、生产级工具链与避坑指南 #

必备工具 #

• typescript-eslint：统一JS/TS代码规范，避免风格不一致：
  • 安装：npm install @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint --save-dev
  • 配置.eslintrc.json：

    {
      "parser": "@typescript-eslint/parser",
      "plugins": ["@typescript-eslint"],
      "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
      "env": { "node": true }
    }
    

• prettier：配合ESLint做代码格式化，消除JS/TS格式差异：npm install prettier eslint-config-prettier eslint-plugin-prettier --save-dev

避坑指南 #

1. 不要一开始就开启strict: true，先让项目正常运行，再逐步开启strictNullChecks、noImplicitAny等子规则，每次只调整一个规则，降低适配成本。
2. 禁止修改node_modules中的类型声明，若第三方依赖类型缺失，在项目types文件夹中用declare module 'xxx'补充声明。
3. 构建时必须指定outDir和rootDir，避免编译产物与源码混放导致模块解析混乱。
4. 生产环境禁止直接用ts-node运行代码，必须编译为JS后再执行，ts-node仅用于开发调试。
5. 过渡期间，新增代码必须用TS编写，避免产生新的JS文件，保证迁移节奏。

内容的提问来源于stack exchange，提问作者Youssef Selk