Chrome扩展Manifest V3中onDOMContentLoaded无法触发问题排查

核心原因拆解 #

• 监听注册时机完全错误：你把页面导航监听塞进了chrome.runtime.onInstalled回调里，这个回调只在扩展首次安装、更新，或者Chrome版本更新时触发一次。也就是说，只有第一次装扩展的时候会注册这个监听，之后浏览器重启、扩展重载都不会再重新注册，自然不会响应后续的页面加载事件。
• Manifest V3 Service Worker特性限制：Manifest V3的后台用的是Service Worker，它是事件驱动的，闲置时会被浏览器销毁。把监听注册放在onInstalled里，一旦Service Worker被销毁，监听就直接失效了，不会再触发。
• 冗余的脚本注入设计：你已经在content_scripts里配置了自动把hide.js注入YouTube视频页面，同时又在后台尝试用executeScript重复注入，不仅多余，还可能引发冲突。

额外的hide.js潜在问题 #

• 直接通过getElementsByClassName取第一个元素就修改样式，没做存在性判断。如果页面加载时这些元素还没生成，或者YouTube改了类名，会直接抛错误导致脚本挂掉。
• YouTube播放器是动态加载的，DOMContentLoaded触发时播放器可能还没渲染完，此时根本找不到目标元素。

修复方案 #

方案1：只用内容脚本（推荐，最简单可靠） #

直接调整manifest.json的内容脚本配置，同时优化hide.js的逻辑：

1. 更新manifest.json：

{
  "background": {
    "service_worker": "src/background.js"
  },
  "content_scripts": [
    {
      "js": ["src/hide.js"],
      "matches": ["*://*.youtube.com/watch*"],
      "run_at": "document_idle"
    }
  ],
  "description": "Hide YouTube video player overlay",
  "icons": {
    "128": "img/icon128.png",
    "16": "img/icon16.png",
    "32": "img/icon32.png",
    "48": "img/icon48.png"
  },
  "manifest_version": 3,
  "name": "hideYTOverlay",
  "permissions": [], // 不需要activeTab、scripting、webNavigation这些权限了
  "version": "1.0"
}

2. 优化hide.js，适配动态加载的播放器：

// 封装隐藏逻辑，加存在性判断
function hideOverlays() {
  const targetClasses = ['ytp-chrome-top', 'ytp-chrome-bottom', 'ytp-gradient-top'];
  targetClasses.forEach(cls => {
    const el = document.querySelector(`.${cls}`);
    if (el) el.style.visibility = 'hidden';
  });
}

// 先尝试执行一次
hideOverlays();

// 监听页面DOM变化，确保动态加载的播放器出现后也能生效
const observer = new MutationObserver(() => hideOverlays());
observer.observe(document.body, { childList: true, subtree: true });

3. 可以直接删除background.js（如果没其他后台功能需求的话）。

方案2：修复后台监听逻辑（仅当有其他后台需求时用） #

如果必须用后台脚本注入，要把监听注册放在Service Worker的顶层，不能藏在onInstalled里：

1. 修改background.js：

// 直接在顶层注册监听，不要嵌套在onInstalled里
chrome.webNavigation.onDOMContentLoaded.addListener(async ({ tabId, url }) => {
  console.log("hello hello!");
  if (url.includes("youtube.com/watch")) { 
    await chrome.scripting.executeScript({
      target: { tabId },
      files: ['src/hide.js']
    });
  }
});

2. 删除manifest.json里的content_scripts配置，避免重复注入。

调试小技巧 #

• 看后台脚本日志：在Chrome扩展管理页，点你扩展的「Service Worker」链接，打开后台控制台看输出。
• 看内容脚本日志：打开YouTube视频页的控制台，切换到「内容脚本」标签，查看hide.js的执行情况和错误。

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