在现有的 Ja vaScript 项目里接入 TypeScript，并不意味着要把所有文件一股脑重写成 .ts。

更实际的做法，通常是走渐进式路线：先把类型检查启用起来，在尽量保留原有 JS 代码的前提下，拿到类型提示和错误预警。

这件事并不需要一上来就把所有文件统统重写一遍。更稳妥的做法，是渐进式地把类型检查启用起来：

• 先在 tsconfig.json 里配置 allowJs 和 checkJs，让现有JS先进入检查范围；
• 接着通过 JSDoc 给 JS 文件补上类型注释；
• 再配合 .d.ts 声明把缺失的类型信息补齐；
• 最后集成 type-check 脚本，把开发阶段的提示和 CI 门禁一起落到实处。

说到底，关键就两点：一是用好 TypeScript 的“Ja vaScript 模式”（checkJs），二是配合类型声明把能力补齐。

安装 TypeScript 并初始化配置

在项目根目录运行：

• npm install --sa ve-dev typescript
• npx tsc --init 生成 tsconfig.json

然后在 tsconfig.json 中启用对 JS 文件的检查：

{
"compilerOptions": {
"allowJs": true,
"checkJs": true,
"skipLibCheck": true,
"noEmit": true,
"strict": false,
"jsx": "preserve",
"moduleResolution": "node"
},
"include": ["**/*.js", "**/*.jsx"],
"exclude": ["node_modules"]
}

注意："noEmit": true 表示只检查、不编译输出，避免干扰现有构建流程。

"strict": false 降低初始门槛，后续可逐步开启（如 strictNullChecks）。

为 JS 文件添加类型注释

这一步可选，但推荐尽早做。TypeScript 能理解 JSDoc 注释，用于标注类型。

例如：

// utils.js
/**
 * @param {string} name
 * @param {number} age
 * @returns {Object}
 */
function createUser(name, age) {
return { name, age };
}
// 调用时如果传错类型，TS 会报错
createUser("Alice", "30"); //  类型错误：age 应为 number

调用时如果传错类型，TS 会报错。这样即使文件仍是 JS，也能获得类型检查能力。

常见 JSDoc 类型写法

• @type {Array} → 字符串数组
• @type {import('./types').User} → 引入外部类型定义
• @typedef {Object} Config {string} host → 自定义类型别名

添加类型声明文件（.d.ts）补全缺失类型

第三方库若无类型定义，可手动创建 src/types/global.d.ts。

同时，需在 tsconfig.json 的 include 中包含该文件。

// src/types/global.d.ts
declare module 'some-legacy-lib' {
const value: any;
export default value;
}
// 或为全局变量声明
declare const DEV: boolean;

也可安装社区维护的类型包：npm install --sa ve-dev @types/react @types/lodash（查 DefinitelyTyped）。

集成到开发与构建流程

在 package.json 中添加脚本：

"scripts": {
"type-check": "tsc --noEmit",
"type-check:watch": "tsc --noEmit --watch"
}

配合编辑器（VS Code 开箱即用）可获得实时提示。

CI 中运行 npm run type-check，可作为类型门禁。

Webpack/Vite 用户无需改动配置。TypeScript 此时仅做检查，不参与打包。