Chrome扩展可在普通页面运行但在Gmail页面不触发如何解决？

问题根因 #

• 错误在content script中调用仅后台脚本可用的chrome.tabs.onUpdatedAPI，代码执行到此处直接抛出异常，中断后续所有逻辑执行
• Gmail是典型的单页应用（SPA），页面初始加载完成后切换邮件仅通过JS修改DOM、调用History API变更路由，不会重新触发window.load事件
• MutationObserver未做防抖处理，Gmail DOM变更频率极高，容易被浏览器限制执行甚至静默禁用
• 代码中直接对getElementsByTagName返回的DOM集合调用replace方法，属于语法错误，执行到此处会直接抛出异常

修正方案 #

第一步：修改manifest.json配置 #

新增后台脚本声明，同时缩小注入范围、增加注入时机配置：

{
    "name": "***",
    "version": "0.99",
    "manifest_version": 2,
    "background": {
        "scripts": ["background.js"],
        "persistent": false
    },
    "content_scripts" : [
        {
            "matches": ["*://mail.google.com/*"],
            "js": ["agent.js"],
            "css": ["style.css"],
            "all_frames": true,
            "run_at": "document_end"
        }   
    ],
    "icons": {
        "16": "icon16.png",
        "48": "icon16.png",
        "128": "icon16.png"
    },
    "browser_action": {
        "default_popup": "popup.html"
    }
}

第二步：修正agent.js逻辑 #

删除无效API调用，增加防抖处理、修正DOM操作逻辑：

// 防抖函数，避免Gmail频繁DOM变更触发过多执行
function debounce(func, wait = 300) {
    let timeout;
    return function(...args) {
        clearTimeout(timeout);
        timeout = setTimeout(() => func.apply(this, args), wait);
    }
}

function replaceText() {
    // 先判断Gmail邮件内容容器是否加载完成，避免操作空DOM
    const mailContainer = document.querySelector('div[role="main"] table');
    if (!mailContainer) return;
    if (mailContainer.innerText.includes("****")) {
        alert("Found");
        // 不建议直接操作innerHTML，会破坏Gmail原有事件绑定，仅做示例参考
        let content = mailContainer.innerHTML;
        content = content.replace("替换前内容1", "替换后内容1");
        content = content.replace("替换前内容2", "替换后内容2");
        mailContainer.innerHTML = content;
    }
}

// 页面初始加载完成后执行一次
window.addEventListener('load', function () {
    alert("Started");
    replaceText();
})

// 防抖处理后的监听回调
const debouncedReplace = debounce(replaceText);
new MutationObserver(debouncedReplace).observe(document.body, {
    subtree: true,
    childList: true,
    attributes: true,
    attributeFilter: ['role', 'class']
});

// 监听后台脚本的触发通知
chrome.runtime.onMessage.addListener((request) => {
    if (request.action === 'runReplace') {
        replaceText();
    }
});

第三步：新增background.js监听页面更新 #

chrome.tabs.onUpdated.addListener( function (tabId, changeInfo, tab) {
    if (changeInfo.status == 'complete' && tab.url.includes('mail.google.com')) {
        chrome.tabs.sendMessage(tabId, {action: 'runReplace'});
    }
})

内容的提问来源于stack exchange，提问作者Yoav