TypeScript 支持通过配置 allowJs 和 checkJs 在 JavaScript 文件中识别 JSDoc 注解并进行类型检查，可在混合项目中提升类型安全；常见用法包括 @type、@param、@returns 和 @typedef，能为变量、函数参数等提供类型信息，支持与 .ts 文件协同工作，适用于渐进式迁移；但 JSDoc 类型能力弱于原生 TypeScript，不支持泛型、接口继承等高级特性，建议新代码优先使用 .ts 文件，现有 JS 文件可适度使用 JSDoc 增强可维护性。
TypeScript 本身已经提供了完整的类型系统，但在一些特定场景下，开发者仍会在 JavaScript 文件中使用 JS 注解（JSDoc），尤其是在混合项目或渐进式迁移过程中。这些注解可以在 TypeScript 环境中被识别和利用，帮助提升类型安全性和开发体验。
启用 JSDoc 类型检查
TypeScript 可以通过配置支持在 .js 文件中读取 JSDoc 注解，并进行类型检查。要开启这项功能，需在 tsconfig.json 中设置：
- "allowJs": true —— 允许编译 JavaScript 文件
- "checkJs": true —— 对 .js 文件进行类型检查
- "noEmit": true 或配合构建工具使用
开启 checkJs 后，TypeScript 会解析 JSDoc 中的类型注释，对变量、函数参数、返回值等进行校验，即使没有显式使用 .ts 文件。
常见的 JSDoc 注解用法
在 JS 文件中，可以通过 JSDoc 为代码添加类型信息，TypeScript 能正确识别以下常用语法：
- @type {string} —— 指定变量类型
- @param {number} id - 用户 ID
- @returns {boolean} 是否有效
- @typedef 定义复杂类型结构
例如：
/** @param {string} name */
function greet(name) {
return "Hello, " + name;
}
TypeScript 会推断 name 必须是字符串，传入数字将报错。
与 TypeScript 文件协同工作
在一个同时包含 .ts 和 .js 文件的项目中，TypeScript 能自动将 JSDoc 提供的类型信息用于跨文件引用。比如从 .ts 文件调用一个带 JSDoc 注解的 .js 函数时，编辑器能正确显示参数提示和类型错误。
这种机制特别适合：
- 逐步将 JS 项目迁移到 TS
- 在不重命名文件的情况下增强类型安全性
- 为第三方库的手写定义提供补充
限制与建议
JSDoc 的类型表达能力弱于 TypeScript 原生类型系统，不支持泛型、接口继承等高级特性。建议：
- 新代码优先使用 .ts 文件和原生类型
- 在已有 JS 文件中合理使用 JSDoc 提升可维护性
- 避免在复杂逻辑中过度依赖 JSDoc 类型
基本上就这些。JSDoc 在 TypeScript 环境下是一个实用的过渡和补充工具，善用它可以平滑演进项目架构。
