Chrome扩展调用openPopup偶现报错：Uncaught (in promise) Error

通过background.js调用chrome.action.openPopup()打开Chrome扩展弹窗时，偶尔会触发以下错误：

Uncaught (in promise) error: failed to open popup.

弹窗有时能正常打开，但报错情况随机出现。相关代码如下：

manifest.json：

{
  "name": "Test Extension",
  "description": "Test Extension",
  "version": "1.0",
  "manifest_version": 3,

  "permissions": ["webNavigation"],
  "action": { "default_popup": "popup.html" },
  "background": { "service_worker": "background.js" }
}

background.js：

chrome.webNavigation.onCompleted.addListener(
  async () => {
    await chrome.action.openPopup();
  },
  { url: [{ urlMatches: "https://example.org/" }] }
);

popup.html：

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Test Extension</title>
    <script src="popup.js"></script>
  </head>
  <body></body>
</html>

popup.js：

document.addEventListener("DOMContentLoaded", () => {
  document.body.textContent = "This is a test.";
});

1. 捕获未处理的Promise错误 #

原代码未对chrome.action.openPopup()的Promise调用做错误捕获，一旦调用失败就会抛出未捕获错误，先补充错误处理逻辑：

修改background.js：

chrome.webNavigation.onCompleted.addListener(
  async () => {
    try {
      await chrome.action.openPopup();
    } catch (err) {
      console.log("打开弹窗失败:", err);
    }
  },
  { url: [{ urlMatches: "https://example.org/" }] }
);

2. 规避Chrome自动弹窗限制 #

Chrome对扩展无用户交互场景下的自动弹窗有严格安全限制，webNavigation.onCompleted属于页面加载触发的无用户交互事件，容易被拦截导致调用失败。可以先激活目标标签页再调用弹窗，提升成功率：

修改background.js：

chrome.webNavigation.onCompleted.addListener(
  async (details) => {
    try {
      // 先激活当前标签页
      await chrome.tabs.update(details.tabId, { active: true });
      await chrome.action.openPopup();
    } catch (err) {
      console.log("打开弹窗失败:", err);
    }
  },
  { url: [{ urlMatches: "https://example.org/" }] }
);

3. 避免重复调用冲突 #

页面可能多次触发webNavigation.onCompleted（比如子框架加载、页面刷新），重复调用openPopup()会引发冲突报错，添加防抖逻辑限制调用频率：

修改background.js：

let isPopupOpening = false;

chrome.webNavigation.onCompleted.addListener(
  async (details) => {
    if (isPopupOpening) return;
    isPopupOpening = true;
    
    try {
      await chrome.tabs.update(details.tabId, { active: true });
      await chrome.action.openPopup();
    } catch (err) {
      console.log("打开弹窗失败:", err);
    } finally {
      // 1秒后允许再次调用，可按需调整时长
      setTimeout(() => {
        isPopupOpening = false;
      }, 1000);
    }
  },
  { url: [{ urlMatches: "https://example.org/" }] }
);

4. 跳过已打开的弹窗 #

通过弹窗与后台的消息通信，维护弹窗状态，避免重复触发：

popup.js新增消息发送逻辑：

document.addEventListener("DOMContentLoaded", () => {
  document.body.textContent = "This is a test.";
  // 告知后台弹窗已打开
  chrome.runtime.sendMessage({ type: "POPUP_OPENED" });
});

background.js修改为：

let isPopupOpen = false;

// 监听弹窗消息更新状态
chrome.runtime.onMessage.addListener((message) => {
  if (message.type === "POPUP_OPENED") {
    isPopupOpen = true;
    // 弹窗关闭后重置状态
    setTimeout(() => {
      isPopupOpen = false;
    }, 100);
  }
});

chrome.webNavigation.onCompleted.addListener(
  async (details) => {
    if (isPopupOpen) return;
    
    try {
      await chrome.tabs.update(details.tabId, { active: true });
      await chrome.action.openPopup();
    } catch (err) {
      console.log("打开弹窗失败:", err);
    }
  },
  { url: [{ urlMatches: "https://example.org/" }] }
);

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