JSDoc通过在JavaScript中添加类型注释，使IDE能提供智能提示与错误检查。使用@type、@param、@returns等标注变量和函数类型，配合jsconfig.json启用checkJs，可实现接近TypeScript的开发体验，尤其适用于未迁移至TS的项目，提升代码可维护性与开发效率。
JavaScript本身是动态类型语言，不支持传统意义上的“注解”（如Java中的Annotation），但通过JSDoc这类文档注解语法，可以为代码提供类型信息，从而让IDE实现智能提示、自动补全和错误检查。合理使用JSDoc配合现代IDE（如VS Code、WebStorm），能大幅提升开发效率。
使用JSDoc添加类型注解
JSDoc是一种广泛支持的JavaScript文档标准，通过在代码上方添加特定格式的注释，为变量、函数、类等提供类型描述。
常见用法包括：
- @type：指定变量或常量的类型 /** @type {string} */ const name = "Alice";
- @param 和 @returns：标注函数参数和返回值类型 /** * 计算两个数的和 * @param {number} a - 第一个数 * @param {number} b - 第二个数 * @returns {number} 和 */ function add(a, b) { return a + b; }
- @typedef：定义复杂对象结构 /** * @typedef {Object} User * @property {string} id - 用户ID * @property {string} name - 用户名 * @property {number} age - 年龄 */
IDE如何识别JSDoc实现提示
主流IDE（尤其是VS Code）内置TypeScript语言服务，即使你写的是纯JS，也能解析JSDoc中的类型信息并提供智能提示。
启用方式：
- 确保项目根目录有
jsconfig.json或tsconfig.json
{
"compilerOptions": {
"checkJs": true
},
"include": ["src/**/*"]
}
- 开启
checkJs后，IDE会像检查TypeScript一样检查JS文件，结合JSDoc进行类型推断 - 在函数调用时，输入参数会显示预期类型；访问对象属性时，会列出可用字段
结合第三方库的类型定义
很多NPM包虽然用JS编写，但提供了.d.ts类型声明文件（或通过DefinitelyTyped维护），IDE可自动加载这些类型，配合JSDoc实现更精准提示。
例如使用Lodash：
- 安装类型定义：
npm install --save-dev @types/lodash - 在代码中使用JSDoc引用： /** @type {import('lodash')} */ const _ = require('lodash');
- 输入
_.时即可看到完整方法列表和参数提示
实际应用场景示例
假设封装一个API请求模块：
/** * @typedef {Object} ApiResponse * @property {boolean} success * @property {any} data * @property {string} message *//**
- 发起GET请求
- @param {string} url
- @param {Object} [params]
- @returns {Promise<ApiResponse>} */ async function get(url, params) { // 实现逻辑 }
// 调用时，IDE会提示url、params，并知道返回值是Promise<ApiResponse> const res = await get('/api/user', { id: 1 }); // 输入res. 时会提示 success/data/message
基本上就这些。JSDoc不是装饰，而是提升JavaScript可维护性和开发体验的重要工具。配合IDE，能让JS拥有接近TS的开发体验，尤其适合尚未迁移到TypeScript的项目。关键在于坚持写规范注释，类型信息越完整，提示就越准确。
