使用米侠浏览器编写用户脚本时，@run-at参数失效是一个常见问题——DOM元素找不到、按钮不出现、功能静默失败。根本原因在于，脚本在目标节点还没渲染时就开始执行了。

排查方向很明确：检查元数据中是否声明了该参数，确认文件头部有没有BOM字节。同时，只使用米侠真正支持的三种时机值——document-end、document-start和context-menu，其他写法一概不认。

为什么米侠浏览器对@run-at的依赖这么脆弱？因为它的解析机制比Chrome严格得多，原生支持有限，必须手动适配。说白了，脚本在目标节点尚未渲染时就跑完了，自然找不到任何DOM元素。所以，手动调整注入时机是绕不过去的一步。

确认当前@run-at是否被识别

检查元数据块

先打开脚本编辑界面，定位到元数据块——也就是// ==UserScript==和==/UserScript==之间的注释。仔细查找是否有@run-at这一行。

如果整段注释里根本没出现这个词，说明参数压根没声明。脚本会回退到米侠的默认时机，通常是document-start，但实际行为很不稳定。这一步必须先做，否则调错方向。

检查BOM头

用记事本之类的纯文本工具打开.js文件，检查文件开头是否有不可见的BOM头——也就是EF BB BF这三个字节。一旦存在，@run-at会被解析器截断或直接跳过，参数立刻失效。

替换为米侠明确支持的时机值

方法一：@run-at document-end。这个最常用，适用于绝大多数操作DOM的脚本。它等到整个HTML解析完才执行，能确保body存在，大部分静态节点都挂载好了。但要注意：如果是Vue或React动态生成的内容，依然可能错过，需要配合MutationObserver来补充监听。

方法二：@run-at document-start。这个只在需要劫持原生API（比如重写fetch、XMLHttpRequest）或者注入全局变量时才用。别忘了，这个时机下document.documentElement刚刚创建，DOM树还是空的。误用于DOM操作将100%返回null。

方法三：@run-at context-menu。这个用在极少数场景——脚本需要响应右键菜单触发，并且不依赖页面初始结构。它在用户右键之后才执行，与页面加载无关。不过要注意，米侠对这个值的支持有版本差异，v5.5.4以上才稳定可用。

验证时机是否真正生效

第一步，在脚本开头插一句调试代码。在return或主逻辑之前，加上一行：console.log('run-at:', document.readyState, 'time:', Date.now());，保存后刷新目标网页。

第二步，打开开发者工具。直接在地址栏输入miaoxia://devtools，然后切换到Console标签页。观察输出的时间戳和readyState值：

• 如果看到document-end对应readyState = 'complete'，且时间戳晚于页面DOMContentLoaded事件，那时机就对了。
• 如果readyState是'loading'，或者时间戳早于页面首屏渲染，说明脚本还在document-start阶段跑。这时候就要检查参数拼写是不是全小写、有没有多余空格、有没有被BOM干扰。

第三步，强制等待重试。如果用document-end还是找不到目标元素，可以临时改一下：setTimeout(() => { /*你的代码*/ }, 1000);，看看是不是框架异步渲染导致的问题。如果是，那就不能只靠@run-at调整了，得改用waitForElement或者直接监听DOM变化。

《夸克》非常好用的免费AI浏览器

下载APP查看