JSDoc通过类型标注提升JavaScript代码质量，配合IDE和TypeScript检查工具可在编码阶段发现类型不匹配、null访问、回调参数错误等潜在问题，减少运行时异常。使用@param、@returns、@typedef等注解明确函数参数、返回值及复杂对象结构，启用"checkJs": true实现.js文件类型检查，结合@nullable、@private提示调用注意事项，规范异步回调签名，统一定义可复用的自定义类型，增强代码可读性与维护性，预防undefined属性访问和逻辑错误，虽非强制类型系统，但能显著降低运行时风险。
JavaScript本身不支持类似Java的“注解”（Annotation）语法，但在实际开发中，我们常通过JS Doc注解配合工具链来提升代码质量、预防潜在的运行时错误。合理使用JSDoc不仅能增强代码可读性，还能借助类型检查工具在编码阶段发现问题，从而减少运行时异常。
使用JSDoc明确变量与函数类型
很多运行时错误源于类型不匹配，比如对undefined调用方法或传入错误类型的参数。通过JSDoc标注参数、返回值和变量类型，可以提前发现这些问题。
示例：/**
* 计算两个数字的和
* @param {number} a - 第一个加数
* @param {number} b - 第二个加数
* @returns {number} 两数之和
*/
function add(a, b) {
return a + b;
}
当传入字符串或未定义值时，配合TypeScript或IDE（如VS Code）能立即提示类型不匹配，避免NaN或TypeError。
结合IDE与类型检查工具实时预警
主流编辑器（如VS Code）原生支持JSDoc类型推断。启用"checkJs": true后，TypeScript会检查.js文件中的类型问题，即使不使用.ts也能享受类型安全。
- 在
jsconfig.json中开启类型检查 - 利用
@type注解为复杂对象定义结构 - 标注
@nullable或@private提醒调用者注意事项
这样可以在函数调用前就识别出null访问或非法访问私有方法的风险。
标注回调与异步函数防止逻辑错误
异步操作中，参数误传或回调执行时机错误很常见。使用JSDoc明确回调签名有助于避免这类问题。
/**
* 发起请求并处理结果
* @param {string} url
* @param {(data: object) => void} onSuccess
* @param {(error: Error) => void} onError
*/
function fetchData(url, onSuccess, onError) {
// ...
}
开发者在调用时能清楚知道回调函数应接收什么参数，减少因结构不清导致的undefined.error等问题。
定义自定义类型提升复用与一致性
对于复杂数据结构，可用@typedef统一定义，避免散落在各处的随意对象使用。
/**
* @typedef {Object} User
* @property {string} id
* @property {string} name
* @property {number} age
*/
<p>/**</p><ul><li>@param {User} user
*/
function greet(user) {
console.log(<code>Hello, ${user.name}</code>);
}
一旦传入缺少name属性的对象，工具即可发出警告，预防运行时访问undefined.name的问题。
基本上就这些。JSDoc虽不是强制类型系统，但结合现代开发工具，能在不改变JS语法的前提下显著降低运行时错误风险。关键是坚持写、规范写，并让团队统一使用检查机制。
