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：指定变量或常量的类型
- @param 和 @returns：标注函数参数和返回值类型
- @typedef：定义复杂对象结构
/** @type {String} */ const name = “Alice”;
/** * 计算两个数的和 * @param {number} a – 第一个数 * @param {number} b – 第二个数 * @returns {number} 和 */ function add(a, b) { return a + b; }
/** * @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 - 开启
checkJs后，IDE会像检查TypeScript一样检查JS文件，结合JSDoc进行类型推断 - 在函数调用时，输入参数会显示预期类型；访问对象属性时，会列出可用字段
{ “compilerOptions”: { “checkJs”: true }, “include”: [“src/**/*”] }
结合第三方库的类型定义
很多npm包虽然用JS编写，但提供了.d.ts类型声明文件（或通过DefinitelyTyped维护），IDE可自动加载这些类型，配合JSDoc实现更精准提示。
例如使用Lodash：
- 安装类型定义：
npm install --save-dev @types/lodash - 在代码中使用JSDoc引用：
- 输入
_.时即可看到完整方法列表和参数提示
/** @type {import(‘lodash’)} */ const _ = require(‘lodash’);
实际应用场景示例
/** * @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的项目。关键在于坚持写规范注释，类型信息越完整，提示就越准确。