null表示有意为空，undefined表示未定义；JSDoc中应根据语义用{Type|null}、{Type|undefined}或联合标注，可选参数默认含undefined，建议显式声明以提升类型安全与可读性。
在JavaScript中，null 和 undefined 虽然都表示“无值”，但语义和使用场景不同。在编写类型注解（如JSDoc）时，明确区分二者有助于提升代码可读性和类型安全。
理解 null 与 undefined 的区别
null 是一个表示“有意为空”的值，通常用于主动赋值来清空引用；而 undefined 表示“未定义”，通常是变量声明了但未初始化、对象属性不存在或函数无返回值时的默认值。
在注解中应根据实际意图选择标注：
- 如果参数允许传入“空对象”或“清空当前值”，应包含 null
- 如果参数可能未传值或省略，应包含 undefined
JSDoc 中如何标注 null 和 undefined
JSDoc 支持通过联合类型明确声明可能的取值。使用 | 符号连接不同类型。
/** * @param {string|null} value - 可以是字符串或 null */ function handleNullable(value) { }/**
- @param {string|undefined} value - 可以是字符串或未传值
*/
function handleUndefined(value) { }
/**
- @param {string|null|undefined} value - 三种情况都允许
*/
function handleAnyEmpty(value) { }
注意：若使用 TypeScript 风格的 JSDoc，还可以启用 strictNullChecks 来增强类型检查精度。
可选参数与默认值的处理建议
对于函数参数，是否标注 undefined 取决于是否为可选参数。
- 可选参数自动可能是 undefined，无需额外说明，但显式写出更清晰
- 若参数不允许为 null，应在注解中排除，并在逻辑中做校验
- 使用默认值时，通常意味着接受 undefined，例如：
function log(msg = 'default')应标注 msg 可能为 undefined
最佳实践总结
准确标注 null 和 undefined 能帮助其他开发者理解 API 设计意图。
- 只允许 null 时写 {Type|null}
- 可省略参数时写 {Type|undefined} 或使用 ?Type（如 {?string}）
- 两者都允许时写 {Type|null|undefined}
- 避免滥用 any 类型代替具体联合类型
基本上就这些。清楚区分 null 和 undefined 的语义，在注解中如实反映，能让代码更健壮、易维护。
