可渐进式引入typescript类型安全：一、启用宽松模式（allowjs:true、checkjs:false等）；二、用@ts-check和jsdoc为单文件加类型；三、用.d.ts为第三方库补类型；四、用类型断言和record替代any；五、配eslint强化类型检查。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在维护一个大型 JavaScript 项目，并希望在不重写整个代码库的前提下引入 TypeScript 类型安全，则可以对遗留代码逐步添加类型注解。以下是实现渐进式迁移的具体操作路径：
一、启用 TypeScript 的宽松模式
在不修改任何现有代码的前提下，让 TypeScript 编译器接受 JavaScript 文件并允许逐步添加类型。此步骤为后续增量标注提供基础环境支持。
1、在项目根目录创建或修改 tsconfig.json 文件。
2、设置 "allowJs": true 和 "checkJs": false，使 TypeScript 能读取 JS 文件但暂不校验其类型。
3、添加 "noEmit": true 避免生成编译产物，仅用于类型检查。
4、将 "strict": false 并启用 "skipLibCheck": true 以降低初始报错压力。
二、为单个文件启用类型检查
通过在 JavaScript 文件顶部添加 JSDoc 注释，显式开启该文件的类型校验，从而实现按需激活类型系统，避免全局干扰。
1、在目标 JS 文件第一行插入 // @ts-check。
2、使用 JSDoc 语法为变量、函数参数和返回值添加类型提示，例如 /** @type {string} */ 或 /** @param {number} id */。
3、保存后，TypeScript 会立即报告该文件中与注解冲突的类型错误，可逐个修复。
4、修复完成后，可将该文件重命名为 .ts 或 .tsx 后缀以脱离 JSDoc 依赖。
三、使用类型声明文件（.d.ts）为第三方模块标注
当项目依赖未提供类型定义的 npm 包时，可通过外部声明文件为其补充类型信息，确保调用处获得类型提示而不改动原始模块代码。
1、在项目中新建 src/@types/ 目录，并在 tsconfig.json 的 "typeRoots" 中包含该路径。
2、为特定包创建 package-name/index.d.ts，使用 declare module 'package-name' 声明其导出结构。
3、在声明中使用 export const、export function 等语法标注已知 API 的类型。
4、在 JS 文件中导入该模块时，TypeScript 即可识别其类型，无需修改原模块源码。
四、利用类型断言与 any 过渡处理不确定结构
面对动态属性访问、JSON 解析结果或 DOM 操作等难以静态推断的场景，可采用受控的类型断言策略，在保留运行时行为的同时明确类型意图。
1、对已知结构的 JSON 数据，使用 /** @type {MyInterface} */ 进行 JSDoc 断言，替代 /** @type {*} */。
2、对无法立即建模的对象，先定义为 Record
3、在函数返回值处使用 /** @returns {Promise
4、避免在参数位置使用 any，改用 unknown 并在函数体内做类型守卫校验。
五、配置 ESLint 与 TypeScript 插件协同检测
借助静态分析工具在编辑阶段暴露类型不一致问题，形成开发闭环，减少手动排查成本。
1、安装 @typescript-eslint/eslint-plugin 和 @typescript-eslint/parser。
2、在 .eslintrc.js 中启用 plugin:@typescript-eslint/recommended 规则集。
3、启用 @typescript-eslint/no-explicit-any 和 @typescript-eslint/explicit-function-return-type 等规则强制类型显式化。
4、将 ESLint 集成至编辑器和 CI 流程，在保存或提交时实时提示缺失类型的位置。
