篡改猴脚本在Chrome中无法运行，如何排查和解决？

Question

篡改猴（Tampermonkey）脚本在Chrome中无法运行，常见原因包括：① 脚本未启用（右键图标→“启用此脚本”）；② 匹配域（@match/@include）配置错误，导致未触发执行（可用console.log测试是否进入脚本）；③ Chrome扩展权限受限——新版Chrome要求Manifest V3，而部分旧脚本依赖V2 API（如unsafe-eval、远程eval），会被拦截；④ 内容安全策略（CSP）阻止内联脚本或eval执行；⑤ 脚本语法错误或依赖的GM_* API未被支持（如GM_xmlhttpRequest在部分站点被禁用）。排查建议：打开开发者工具→Console查看报错；点击Tampermonkey图标确认脚本状态与运行日志；检查浏览器地址栏右侧扩展图标是否显示“已暂停”；必要时将脚本切换为“@run-at document-idle”或添加// @grant none（若无需高级API）。升级Tampermonkey至v4.15+并确保Chrome为最新稳定版，可规避多数兼容性问题。

Answer 1

```html

一、表层现象：脚本“静默失效”——启用状态与基础触发检查

• 用户点击网页无反应，Tampermonkey图标右键菜单中未勾选“启用此脚本”，脚本处于禁用态；
• 地址栏右侧扩展图标显示灰色/带斜杠（⛔），提示“已暂停”或“被阻止”；
• 在目标页面按 F12 → Console 输入 console.log('test') 可执行，但脚本内 console.log('tm-start') 完全不输出——说明未进入执行生命周期。

二、中层逻辑：匹配规则与执行时机错配

脚本元信息配置决定其是否被加载与何时注入：

元标签	典型错误示例	调试建议
// @match https://example.com/*	实际访问 https://www.example.com/（子域不匹配）	改用 // @include *://*.example.com/* 或多行 @match
// @run-at document-start	DOM 尚未构建，document.querySelector 返回 null	切换为 // @run-at document-idle 或 document-end

三、深层机制：Chrome 架构演进引发的兼容性断层

Manifest V3 引入强制性沙箱约束，直接冲击旧脚本根基：

• unsafe-eval 禁令：V2 兼容的 eval()、new Function()、setTimeout('string') 全部被 CSP 拦截；
• 远程代码加载失效：动态 import('./xxx.js') 或 fetch().then(eval) 在 MV3 下默认拒绝；
• GM_* API 降级：部分站点（如 GitHub、Cloudflare 保护站）主动屏蔽 GM_xmlhttpRequest，仅允许原生 fetch（需手动适配 CORS 与凭据策略）。

四、系统级防御：内容安全策略（CSP）的隐式拦截

CSP 头字段可全局禁止内联脚本与 eval，即使 Tampermonkey 注入成功也会被浏览器引擎丢弃。验证方式：

// 在 Console 中执行：
document.querySelector('meta[http-equiv="Content-Security-Policy"]')?.content
// 输出示例： "script-src 'self' 'unsafe-inline' https:;"
// 若缺失 'unsafe-inline' 或含 'none'，则 TM 注入的 script 标签将被拒绝执行

五、工程化诊断：结构化排查流程图

graph TD
  A[打开目标页面] --> B{Tampermonkey 图标是否高亮？}
  B -- 否 --> C[右键→启用脚本 / 检查“已暂停”状态]
  B -- 是 --> D[打开 DevTools → Console 查看报错]
  D --> E{是否有 SyntaxError / CSP / Refused to evaluate？}
  E -- SyntaxError --> F[检查 JS 语法 / ES 版本兼容性]
  E -- CSP error --> G[确认 CSP 策略 / 改用 @grant none + 原生 fetch]
  E -- GM_* undefined --> H[升级 TM 至 v4.15+ / 显式声明 @grant]
  H --> I[验证 Chrome 版本 ≥ 117（MV3 全面生效基线）]

六、生产级解决方案矩阵

• 最小权限原则：若脚本仅做 DOM 操作，添加 // @grant none 避免 API 权限协商失败；
• API 迁移路径：将 GM_xmlhttpRequest 替换为 fetch + credentials: 'include'，并捕获 TypeError: Failed to fetch；
• 运行时兜底：使用 if (typeof GM_xmlhttpRequest !== 'undefined') { ... } else { fetch(...) } 实现双模兼容；
• 版本强约束：在脚本头部声明 // @require https://cdn.jsdelivr.net/npm/tampermonkey@4.15/dist/tm-api.min.js（仅限高级场景）。

七、高阶实践：自动化健康检查脚本模板

// ==UserScript==
// @name         TM Health Checker
// @namespace    http://tampermonkey.net/
// @version      1.0
// @description  自动诊断当前页面 TM 执行环境
// @match        *://*/*
// @run-at       document-idle
// @grant        none
// ==/UserScript==

console.group('🔍 TM Runtime Diagnostics');
console.log('✅ Chrome Version:', navigator.appVersion.match(/Chrome\/(\d+)/)?.[1] || 'unknown');
console.log('✅ Script Enabled:', typeof window.GM_info !== 'undefined');
console.log('✅ CSP Allows Inline:', !!document.querySelector("meta[http-equiv='Content-Security-Policy'][content*='unsafe-inline']"));
console.log('✅ fetch Available:', typeof fetch === 'function');
console.groupEnd();

```