米侠浏览器异步脚本失效主因是执行时机与X5内核限制不匹配，需确认脚本注入开启、@run-at元数据正确（仅支持document-end/start/context-menu）、禁用?./??语法、适配内核差异、添加超时控制及限定MutationObserver范围。
米侠浏览器无法正常执行异步注入脚本，表现为页面加载后脚本无反应、控制台无日志、目标元素始终获取不到，根本原因是异步逻辑未适配米侠严格的执行时机与内核限制，而非代码本身语法错误。
确认脚本是否真正被注入
点击右上角三个点 → 【设置】→【高级设置】→【脚本注入】→ 确认“启用脚本注入”已开启且右侧显示“已启用”。【若此处为灰色或未显示已启用，所有后续调试全部无效】。
重启浏览器后，打开目标网页，点击地址栏左侧「脚本状态图标」→ 查看是否有该脚本名称及匹配状态。若图标灰显或点击后无任何条目，说明脚本根本未被识别，立即停止调试异步逻辑，转去检查文件路径和编码。
验证@run-at时机是否生效
在脚本最开头插入一行：console.log('✅ run-at test:', document.readyState, 'time:', Date.now());，保存后刷新目标页。
地址栏输入 miaoxia://devtools 打开开发者工具 → 切换到 Console 标签页，观察输出：
若输出中 document.readyState 为 loading 或时间戳早于页面首屏渲染（如小于 100ms），说明实际执行时机仍是 document-start，@run-at 未被识别；此时必须检查元数据块中是否拼写为全小写 @run-at、有无多余空格、文件开头是否含 BOM 头（EF BB BF）。
米侠仅稳定支持 document-end、document-start、context-menu 三种值，document-idle 或 document-ready 一律无效。
排查异步逻辑在X5内核下的兼容性断点
方法一：禁用现代语法特性
将脚本中所有可选链 ?. 和空值合并 ?? 全部替换为传统写法，例如 a?.b?.c 改为 a && a.b && a.b.c，x ?? y 改为 x !== undefined && x !== null ? x : y。【X5内核默认不支持?.和??，报错时不会提示语法错误，而是静默跳过整段逻辑】。
方法二：强制切换内核组合验证
进入【设置】→【高级设置】→【内核与UA设置】→ 先切为【X5内核 + 桌面版UA】→ 重启 → 刷新测试；若失败，再切为【系统内核 + iPhone UA】→ 重启 → 再测。两种组合必须都试，因为X5内核会屏蔽 MutationObserver 和 AbortController，而系统内核下某些网站又会因UA被识别为低端设备返回阉割DOM。
修复异步等待导致的超时中断
第一步：检查脚本中是否存在未加超时控制的 await fetch() 或 await new Promise(...)。
第二步：对所有外部请求添加 AbortSignal.timeout(8000)（需先确认当前内核支持）；若不支持，则改用 Promise.race([fetch(...), new Promise((_, r) => setTimeout(r, 8000))]) 包裹。
第三步：若使用 MutationObserver 等待动态节点，必须限定监听范围——只观察 document.body 或具体父容器，禁止监听 document 全局；否则在长页面中极易触发主线程阻塞超时。
第四步：在地址栏输入 mx://flags → 搜索 script-timeout → 将值从默认 10000 改为 30000 → 点击“重启生效”。这一步不能替代逻辑优化，仅用于临时绕过超时中断以定位真实卡点。
验证异步回调是否落入正确执行上下文
在每个 then()、catch()、async function 开头插入 console.log('? in then:', document.currentScript?.src || 'inline');。
刷新页面后查看 Console 输出顺序：若出现 in then 日志但后续 DOM 操作仍失败，说明回调执行时 document.body 已存在，问题出在选择器或节点挂载时机；若连 in then 都没输出，说明 Promise 被拒绝但未被捕获，或 await 表达式左侧值为 undefined 导致运行时静默终止。
特别注意：米侠中 document.currentScript 在模块化脚本或内联执行时可能为 null，此时应改用 performance.now() 打时间戳辅助判断执行流。
