Chrome扩展无法加载offscreen.html问题求助

我开发Chrome扩展时遇到了如下问题：点击扩展按钮后，offscreen.html并未加载，也无法看到offscreen.js的任何日志输出。目前能正常调试background.js和sidepanel.js，但在Chrome扩展详情页面里看不到offscreen.html的踪迹。

现有代码片段 #

manifest.json #

"side_panel": {
    "default_path": "sidepanel.html"
  },
  "action": {},
  "permissions": ["sidePanel", "storage", "scripting", "tabCapture", "offscreen"]

background.js #

chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

chrome.action.onClicked.addListener(async (tab) => {
    // 若将以下代码放入onMessage.addListener会报错："Unchecked runtime.lastError: The message port closed before a response was received"
    // 应将offscreen相关代码放在onClicked事件内
    const existingContexts = await chrome.runtime.getContexts({});
    let recording = false;
    
    console.log("[==] Context");
    console.log(existingContexts);
    console.log("[==] Context");
    
    const offscreenDocument = existingContexts.find(
        (c) => c.contextType === 'OFFSCREEN_DOCUMENT'
    );
    
    console.log("[==] Context offscreenDocument");
    console.log(offscreenDocument);
    console.log("[==] Context offscreenDocument");

    // 若offscreen文档未打开则创建
    if (!offscreenDocument) {
        console.log("[!!] Create offscreen document");
        // 创建offscreen文档
        await chrome.offscreen.createDocument({
          url: 'offscreen.html',
          reasons: ['USER_MEDIA'],
          justification: 'Recording from chrome.tabCapture API'
        });
    }
});

offscreen.js #

chrome.runtime.onMessage.addListener(async (message) => {
    console.log("OFFSCREEN");
    console.log(message);
    console.log("OFFSCREEN");
});

sidepanel.js #

document.getElementById('delete-button').addEventListener('click', function() {
    console.log("Send Event Button Remove..");
    chrome.runtime.sendMessage({action: 'RemoveTestButton'}, function(response) {
      console.log(`message from background: ${JSON.stringify(response)}`);
    });
});

问题排查及解决方法 #

1. 核心原因：chrome.action.onClicked未被触发
   你在onInstalled事件里设置了openPanelOnActionClick: true，这会让Chrome在点击扩展按钮时直接打开侧边栏，完全跳过chrome.action.onClicked事件——也就是说你用来创建Offscreen文档的代码根本没执行。

   两种修正方案：

   • 移除chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });，让点击按钮触发onClicked事件；
   • 将Offscreen文档的创建逻辑迁移到其他触发时机，比如chrome.runtime.onInstalled事件，或者sidepanel.js的初始化代码中。

2. Offscreen文档的调试方式
   Offscreen文档不会显示在扩展详情的“已加载资源”列表里，正确的调试路径是：

   • 打开扩展的背景页调试窗口（chrome://extensions/ → 你的扩展 → 点击服务工作者/背景页的「检查视图」）；
   • 在调试窗口顶部菜单选择「更多工具 > 开发者工具」，然后在Sources标签页的Page目录下，找到chrome-extension://[你的扩展ID]/offscreen.html，即可调试offscreen.js。

3. 验证创建状态
   可以在await chrome.offscreen.createDocument()之后添加日志，或者再次调用chrome.runtime.getContexts()打印结果，确认Offscreen文档是否成功创建。

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