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 的项目。关键在于坚持写规范注释，类型信息越完整，提示就越准确。
