传入非法 options 会触发 TypeError，需用 safeAddEventListener 封装：先转布尔值为对象，再校验类型并白名单过滤 capture/once/passive/signal，最后兜底捕获异常。
当 addEventListener 的第三个参数传入不合法的 options（比如 null、undefined、非对象类型，或对象中含非法属性如 capture: "yes"），部分浏览器（尤其是较新版本的 Chrome、Firefox）会直接抛出 TypeError，导致 JS 执行中断。这不是“静默失败”，必须主动防御。
确保 options 是有效对象
最常见错误是把布尔值（如 true）误当 options 传入，或变量未定义就直接使用。应显式判断并兜底：
- 用
typeof options === 'object' && options !== null判断是否为合法对象 - 若不满足，可降级为布尔值（兼容老写法），或直接用默认空对象
{} - 避免直接传
someVar，改用someVar ?? {}或Object.assign({}, defaultOpts, someVar)
过滤非法 options 属性
标准允许的 options 属性只有：capture、once、passive、signal。若传入了 { priority: 'high' } 或 { useCapture: true } 等非标字段，某些浏览器（如 Safari 16.4+）会报错。
- 手动白名单过滤：
const safeOpts = Object.fromEntries(Object.entries(opts).filter(([k]) => ['capture','once','passive','signal'].includes(k))) - 对
capture、once、passive做类型校验（只接受布尔值） -
signal必须是AbortSignal实例，否则也应忽略或报 warn 而非 crash
封装安全的 addEventListener 辅助函数
在项目中统一用一层包装，避免每个地方重复判断：
function safeAddEventListener(target, type, listener, options) {
// 处理布尔值旧写法
if (typeof options === 'boolean') {
options = { capture: options };
}
// 确保是对象
if (typeof options !== 'object' || options === null) {
options = {};
}
// 白名单 + 类型校验
const validOpts = {};
for (const [key, val] of Object.entries(options)) {
if (['capture', 'once', 'passive'].includes(key) && typeof val === 'boolean') {
validOpts[key] = val;
} else if (key === 'signal' && val instanceof AbortSignal) {
validOpts[key] = val;
}
}
try {
target.addEventListener(type, listener, validOpts);
} catch (e) {
console.warn('Failed to add event listener with options:', options, e);
}
}
注意框架/库的自动透传行为
像 Vue 的 v-on、React 的合成事件、或某些 UI 组件库（如 Element Plus）可能把用户传的 onXXX 配置原样透传给 addEventListener。若你在模板里写了 @click="{ passive: true }" 这种错误写法，也会触发报错。
- 检查文档确认框架对事件选项的支持方式（Vue 3 中需用
v-on:click.passive修饰符） - 避免在模板中直接传对象字面量作为事件选项
- 在封装自定义 hook 或指令时，务必对传入的 options 做上述校验
