eslint 的 `jsdoc/valid-types` 规则会将对象字面量类型中名为 `event` 的键误识别为保留关键字或内部标识符，导致解析失败；可通过拆分 `@property` 声明、使用 `@typedef` 抽离类型，或改用 `@type` + 字面量注解等方式规避该限制。
在 JavaScript 项目中使用 JSDoc 进行类型标注时，你可能会遇到一个看似奇怪的限制：当对象类型定义中包含键名为 "event" 时（例如 {event: Object.<string, MyEnum[]>}），ESLint 的 jsdoc/valid-types 规则会抛出 Syntax error in type 错误，而将键名改为 "events" 或 "evt" 却能正常通过。这并非 JavaScript 语法问题，而是 ESLint 的 JSDoc 插件（如 eslint-plugin-jsdoc）在解析类型字符串时存在关键字冲突或解析歧义——它可能将 "event" 误判为内置事件相关标识符（如 Event 构造函数、event 参数名等），从而提前终止类型解析。
✅ 推荐解决方案（按优先级排序）
1. 拆分为独立 @property 声明（最简洁、兼容性最佳）
避免在单个内联对象类型中声明 event 键，转而为每个属性单独注解：
/**
* @property {Object} enums
* @property {Object.<string, MyEnum[]>} enums.event
* @property {Object.<string, MyEnum[]>} enums.observation
*/
const enums = {
event: { /* ... */ },
observation: { /* ... */ }
};✅ 优势：无需修改变量结构，完全绕过内联对象解析器缺陷；所有主流工具（VS Code、TypeScript、ESLint）均能正确推导类型。
2. 使用 @typedef + @type 组合（语义清晰、可复用）
将复杂类型抽离为命名类型，再通过 @type 显式标注变量：
/**
* @typedef {Object.<string, MyEnum[]>} MyEnumMap
*
* @type {{
* event: MyEnumMap,
* observation: MyEnumMap
* }}
*/
const enums = {
event: {},
observation: {}
};⚠️ 注意：确保 MyEnum 已正确定义（如通过 @enum 或外部类型声明），否则 MyEnumMap 可能被误报为未定义类型。
3. 替代语法：改用 Record（TypeScript 用户推荐）
若项目已启用 TypeScript 支持，可使用更现代的泛型语法提升可读性与健壮性：
/**
* @type {Record<'event' | 'observation', Record<string, MyEnum[]>}
*/
const enums = { /* ... */ };? 提示：Record 是 TypeScript 内置工具类型，在支持 JSDoc 的 TS 环境中解析稳定，且不会触发 event 关键字误判。
⚠️ 注意事项
- 不要依赖 @property {{event: ...}} 这类内联对象字面量写法中的敏感键名（如 event, class, function, return），它们在部分 JSDoc 解析器中属于高风险词。
- ESLint 插件版本影响显著：升级至 eslint-plugin-jsdoc@40+ 可缓解部分解析问题，但仍建议采用上述防御性写法。
- 若使用 VS Code，拆分式 @property 注解能提供更精准的悬停提示和自动补全支持。
通过结构化声明替代紧凑内联类型，不仅规避了工具链的解析陷阱，也让 JSDoc 更易维护、协作更清晰——类型即文档，清晰胜于简短。
