JSDoc 类型定义中键名为 “event” 引发语法错误的解决方案

jsdoc 类型注释中若对象字面量的键名为 Event，eslint 的 jsdoc/valid-types 规则可能误将其识别为保留关键字或内部标识符，导致解析失败；推荐改用 @typedef + @type 组合写法或拆分为多个 @Property 声明。

在 javaScript 项目中使用 JSDoc 进行类型标注时，看似合法的类型语法有时会意外触发 ESLint 的 jsdoc/valid-types 报错。例如以下写法：

/**  * @property {{event: Object., observation: Object.}} enums  */

尽管 event 是完全合法的普通对象键名（如 enums.event = {…}），但某些 JSDoc 解析器（尤其是 ESLint 的 eslint-plugin-jsdoc）在解析内联对象类型 {event: …} 时，会将 event 误判为内置事件相关关键字（如 Event 构造函数、event 参数名等），从而中断类型解析流程，抛出 Syntax Error in type 错误。

✅ 推荐解决方案一：拆分 @property（最兼容、零风险）
避免在单个内联类型中声明含敏感键名的对象，转而为每个子属性单独标注：

/**  * @property {Object} enums  * @property {Object.} enums.event  * @property {Object.} enums.observation  */ const enums = {   event: { 'click': [MyEnum.CLICK] },   observation: { 'load': [MyEnum.LOAD] } };

✅ 推荐解决方案二：使用 @typedef + @type（语义清晰、便于复用）
通过 @typedef 提前定义可复用类型别名，再用 @type 声明完整结构，彻底绕过内联解析歧义：

/**  * @typedef {Object.} MyEnumMap  *  * @type {{  *   event: MyEnumMap,  *   observation: MyEnumMap  * }}  */ const enums = {   event: { 'submit': [MyEnum.SUBMIT] },   observation: { 'error': [MyEnum.ERROR] } };

⚠️ 注意事项：

• Object. 是 Closure Compiler 风格语法，在较新版本的 eslint-plugin-jsdoc（v40+）中已支持，但若使用旧版插件，建议改用 typescript 风格泛型写法 Record（需启用 settings.jsdoc.mode: ‘typescript‘）；
• 避免在类型字面量中使用其他潜在保留词作为键名，如 default、class、function、constructor 等，同样可能引发类似问题；
• 若项目已接入 TypeScript，建议优先使用 .d.ts 文件或 JSDoc 的 @typedef 定义类型，而非过度依赖内联复杂类型。

综上，该问题本质是 JSDoc 工具链在类型解析阶段的关键词冲突，并非 javascript 语言限制。采用结构化声明（拆分 property）或抽象化建模（typedef + type）均可高效规避，同时提升代码可维护性与工具兼容性。