从Chrome扩展侧边栏调用captureVisibleTab API遇权限问题求助

我正在开发一款使用全局侧边栏捕获并显示截图的Chrome扩展。此前在popup中运行代码可正常工作，但将代码迁移到侧边栏后出现权限错误（曾短暂实现侧边栏截图功能，但扩展重载后失效且无法复现）。

相关代码 #

manifest.json #

{
  "manifest_version": 3,
  "name": "SidePanel - Screenshot Extension",
  "version": "1.0",
  "description": "Shows how to call sidePanel.open() to open a global side panel.",
  "minimum_chrome_version": "116",
  "background": {
    "service_worker": "service-worker.js"
  },
  "side_panel": {
    "default_path": "sidepanel-global.html"
  },
  "permissions": ["activeTab", "tabs", "windows", "sidePanel", "contextMenus"],
  "icons": {
    "16": "images/icon-16.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "action": {
    "default_title": "Launch DoDid"
  }
}

sidepanel-global.html #

<!DOCTYPE html>
<html>
<head>
  <title>Screenshot Extension</title>
  <script src="screenshot.js"></script>
</head>
<body>
  <button id="capture">Capture Screenshot</button>
  <div id="screenshotContainer"></div>
</body>
</html>

screenshot.js #

document.addEventListener("DOMContentLoaded", function() {
    const captureButton = document.getElementById("capture");
    const screenshotContainer = document.getElementById("screenshotContainer");
  
    captureButton.addEventListener("click", function() {
      chrome.tabs.captureVisibleTab(function(screenshotDataUrl) {
        const screenshotImage = new Image();
        screenshotImage.src = screenshotDataUrl;
        screenshotContainer.appendChild(screenshotImage);
      });
    });
  });

错误信息 #

Unchecked runtime.lastError: Either the '<all_urls>' or 'activeTab' permission is required.

问题原因 #

Manifest V3中，全局侧边栏的运行上下文与popup存在差异：点击popup时，浏览器会自动将activeTab权限关联到当前激活标签页；但侧边栏不会自动触发这个权限授予流程，即便已声明activeTab权限，直接调用captureVisibleTab仍会触发权限错误。

解决方法 #

方法1：通过扩展图标触发权限授予 #

让用户先点击扩展图标，触发activeTab权限授予后再打开侧边栏，确保权限生效：

1. 更新service-worker.js：

chrome.action.onClicked.addListener(async (tab) => {
  // 执行空脚本触发activeTab权限
  await chrome.scripting.executeScript({
    target: { tabId: tab.id },
    func: () => {}
  });
  // 打开侧边栏
  await chrome.sidePanel.open({ tabId: tab.id });
});

2. 完善manifest.json的action配置（可选，确保图标可点击）：

"action": {
  "default_title": "Launch DoDid",
  "default_icon": {
    "16": "images/icon-16.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

方法2：声明<all_urls>权限（不推荐） #

若无需严格遵循最小权限原则，可直接添加<all_urls>权限，让侧边栏直接拥有截图权限：

"permissions": ["activeTab", "tabs", "windows", "sidePanel", "contextMenus", "<all_urls>"],

方法3：通过后台脚本中转请求 #

侧边栏发送消息给后台脚本，由后台脚本调用截图API（后台脚本在权限激活后可正常执行）：

1. 修改screenshot.js：

document.addEventListener("DOMContentLoaded", function() {
  const captureButton = document.getElementById("capture");
  const screenshotContainer = document.getElementById("screenshotContainer");

  captureButton.addEventListener("click", function() {
    chrome.runtime.sendMessage({ action: "captureScreenshot" }, (response) => {
      if (response?.screenshotDataUrl) {
        const screenshotImage = new Image();
        screenshotImage.src = response.screenshotDataUrl;
        screenshotContainer.appendChild(screenshotImage);
      } else {
        console.error("截图失败：", chrome.runtime.lastError);
      }
    });
  });
});

2. 更新service-worker.js：

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === "captureScreenshot") {
    chrome.tabs.captureVisibleTab((screenshotDataUrl) => {
      sendResponse({ screenshotDataUrl });
    });
    return true; // 保持消息通道开放以接收异步结果
  }
});

注意：此方法仍需用户先点击扩展图标激活activeTab权限，可结合方法1的逻辑使用。

内容的提问来源于stack exchange，提问作者The Ginger Fox