第一步：确认报错来源是本地脚本而非网页本身

先别急着开整脚本。点一下地址栏右边那个“刷新”按钮旁边的“开发者工具”图标（或者直接按F12），切到Console面板。

注意看红字报错的开头：

如果它包含 mixia://、file:///sdcard/ 或者路径里有 scripts/ 这些字样，那恭喜你，报错确实来自你装的本地脚本。

反过来，如果报错指向的是 https://域名 这种网页自家的JS文件，那问题出在网页身上，你改自己的脚本等于白忙活。这一步要是跳过了，后面全是无用功。

第二步：定位具体错误类型并分层排查

不同的报错信息，原因完全不同。咱们来快速判断一下：

• SyntaxError：说明脚本里藏着非法字符、括号没配对、或者用了X5内核不认的ES6+新语法。你需要拿纯文本编辑器（比如记事本）打开检查有没有BOM头或全角符号，然后用“分段注释法”一段段屏蔽代码来定位问题，实在不行就切换系统内核看看报错会不会更清楚。
• ReferenceError / TypeError：这俩最常见。变量没声明就用了、要找的DOM元素页面上没有、或者某个API（比如AbortController、ResizeObserver）在X5内核里压根不存在，返回了个undefined。这时候得重点检查你设定的@run-at时机是不是太早了、是不是忘了加载polyfill垫片、是不是误用了现代语法。
• RangeError / InternalError / Out of Memory：内存扛不住了。通常是长循环没做切分、事件监听器只绑不松、setInterval设了不清，或者DOM节点在页面上越堆越多。解决思路很简单：清理冗余资源，大任务拆小分批跑。

第三步：验证脚本文件是否符合硬性准入条件

这一步更像是个“体检”，确保文件本身没问题。

先检查文件扩展名——必须是纯小写的 .js。如果写成.JS、.Js或者带个空格（比如“my script.js”），米侠浏览器会直接将其静默忽略，连个报错都不会给你。

接着，用文件管理器长按该文件，选择“编辑”，然后全选粘贴到记事本之类的纯文本工具里看看：如果开头有乱码或隐藏的BOM头（比如有EF BB BF这些看不见的字符），就必须另存为UTF-8无BOM格式，否则解析肯定失败。

最后确认下脚本是不是被压缩包包着——米侠不支持直接读.zip或.rar里面的.js文件，必须解压出来放到目录里。如果有个manifest.json配置文件，得保证它和.js文件在同一级目录。

【务必保存为UTF-8无BOM格式】——用Notepad++的话，选“编码→转为UTF-8无BOM”。用VS Code的话，点击右下角编码类型，选“Save with Encoding→UTF-8”。不然等你重启浏览器，报错还会卷土重来。

第四步：检查脚本注入总开关与路径扫描状态

这一步可能看起来有点基础，但确实是很多人翻车的地方。

点右上角三个点，进入【设置】→【高级设置】→【脚本注入】，先把“启用脚本注入”的开关打开。然后缓一下，重启浏览器，再进去确认一下那个开关右侧显示的是“已启用”，否则后面所有操作都白搭。

另外，安卓设备上，米侠浏览器只认 /sdcard/MiXiaBrowser/scripts/ 这个路径下的.js文件。放到Download、Documents或是根目录里，浏览器根本不会去扫描。

确定路径没错，脚本还是没出现？那就重启浏览器，再进入刚才的“脚本注入”设置页，点一下右上角的「刷新脚本列表」按钮。这一步千万别省，不然浏览器不会重新去磁盘里找。

第五步：强制验证@run-at时机是否真正生效

光说不练假把式。给你两个实测的办法：

方法一：在脚本开头（比如return或主逻辑之前）加上一行 console.log('run-at:', document.readyState, 'time:', Date.now());，保存后刷新目标网页，看控制台输出。

方法二：直接用浏览器自带的开发者工具（地址栏输入 miaoxia://devtools），切到Console标签页观察。

如果看到 document-end 对应的 readyState = 'complete'，并且输出的时间戳比页面的DOMContentLoaded事件要晚，那说明时机设置对了。

反过来，如果你发现 readyState = 'loading'，或者时间戳比页面首屏渲染还要早，那脚本其实是在 document-start 阶段就执行了。这时候就需要回去检查你的@run-at参数是不是全小写、有没有多余的**空格**或换行把它搞乱了。

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

下载APP查看