JSDoc配合类型检查：无需TypeScript，提升代码维护性

先说一个很多人关心的问题：不使用 TypeScript，仅靠 JSDoc 能否实现有效的类型检查？

答案是：确实可以，而且效果相当扎实——前提是配置到位、注解写得准确，并非简单添加一个 /** */ 就能完成。

许多团队初次接触这块时，最大的困惑往往是：明明写了 @param {string} name，VS Code 里却没有任何提示。这其实是一个经典误操作——编辑器默认不会主动校验 JS 文件的类型一致性，需要明确告知它“去检查”。

VS Code 中的关键配置

要让 JSDoc 真正报错，必须完成两件事：

• 单文件层面：在文件顶部添加一行 // @ts-check，这相当于为当前文件开启类型检查（包括参数类型、返回值类型、赋值兼容性等）。
• 项目层面：需要配置 jsconfig.json，并且 "checkJs": true 这个字段必不可少。如果漏掉这一项，文件顶部的 // @ts-check 也会失效——因为整个项目层面并未开启该能力。

这里有一个关键细节：strict: true 并非可选项。它控制是否检查隐式 any、是否允许将 undefined 赋给非可选字段等边界情况。不开启，就等于关闭了类型检查一半的“威力”——日常开发中大量隐蔽的类型隐患，恰恰隐藏在这些隐式推断中。

注解写法的规范要点

如果配合 eslint-plugin-jsdoc 使用，有两个规则特别值得注意：require-param-type 和 require-returns-type。它们非常严格——仅写 @param name 不行，必须带上花括号类型；仅写 @returns 也不行，必须写成 @returns {number} 这种完整格式。

几个容易踩坑的地方：

• 对象类型要写完整。例如 @param {{ id: number, name: string }} user，不能简写成 @param {object} user——object 在 eslint-plugin-jsdoc 中被视为无效类型。
• 可选属性用方括号标记：@param {{ name: string, [key: string]: any }} opts，否则 check-types 规则会报错。
• 异步函数千万不要遗漏 Promise。正确的写法是 @returns {Promise}，如果写成 @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，否则提示和检查都会明显减弱。

这并非 JSDoc 的缺陷，而是轻量方案合理的边界——它也提醒我们：越灵活的机制，越需要使用者自己“对齐”上下文。只要把握住这些要点，在不使用 TypeScript 的情况下，JSDoc 照样能让代码维护性提升一个台阶。