如何通过 JSDoc 结合类型检查在不使用 TypeScript 时提升代码维护性

能，且效果实在——需配置到位、注解精准：启用 // @ts-check 或 jsconfig.json 中设 "checkJs": true 和 "strict": true；@param/@returns 必带花括号类型，对象须写全，异步函数需标 Promise；注释须紧贴声明无空行，箭头函数用 @type 断言，导出推荐先声明后 export。

能，而且效果很实在——前提是配置到位、注解写得准，不是光加个 /** */ 就完事。

VS Code 里怎么让 JSDoc 真正报错？

很多人加了 @param {string} name 却没任何提示，根本原因是没启用检查。VS Code 默认不主动校验 JS 文件的类型一致性。

• 在文件顶部加一行 // @ts-check，当前文件立即启用类型检查（包括参数类型、返回值、赋值兼容性）
• 如果想整个项目都生效，必须配 jsconfig.json，且 "checkJs": true 不可少；漏掉这句，// @ts-check 也会失效
• jsconfig.json 中的 "strict": true 不是可选——它控制是否检查隐式 any、是否允许 undefined 赋给非可选字段等细节，不开启等于关掉一半能力

@param 和 @returns 怎么写才不会被 eslint-plugin-jsdoc 报错？

eslint-plugin-jsdoc 的 require-param-type 和 require-returns-type 规则很严格：只写 @param name 不行，必须带花括号类型；只写 @returns 也不行，必须写成 @returns {number}。

• 对象类型要写全，比如 @param {{ id: number, name: string }} user，不能简写成 @param {object} user（object 被视为无效类型）
• 可选属性用方括号：@param {{ name: string, [key: string]: any }} opts，否则 check-types 会报错
• 异步函数别漏 Promise：应写 @returns {Promise<string>}</string>，写成 @returns {string} 会被 require-returns-type 拦下

为什么写了 JSDoc 还是没智能提示？

常见原因不是注解格式错，而是编辑器没“看到”它——尤其当函数定义和注解之间夹了空行、注释位置不对，或用了错误的注释块。

• JSDoc 注释必须紧贴函数/变量声明上方，中间不能有空行，也不能是 // 行注释
• 箭头函数无法直接绑定 JSDoc，得写成命名函数或用 /** @type {function(string): number} */ 这种类型断言方式
• 导出的函数如果写在 export default function foo() {} 上方，VS Code 有时识别不稳定；稳妥做法是先声明再导出：function foo() {}; export { foo };
• 确保没有全局 noImplicitAny: false 类配置覆盖了 jsconfig.json 的 strict 设置

最容易被忽略的一点：JSDoc 类型检查不是“写完就稳”，它高度依赖上下文推断。比如一个参数类型靠函数调用处传入的字面量反推，一旦传参是变量或来自其他模块，类型链就容易断。这时候必须手动补全 @type 或嵌套 @typedef，否则提示和检查都会弱化。这不是缺陷，而是轻量方案的合理边界。