Chrome扩展开发：无法建立消息连接（接收端不存在）问题排查

需求说明 #

• 扩展启动（浏览器启动/更新）时打开含主密码表单的弹窗
• 主密码不匹配或弹窗被关闭时，执行指定状态更新逻辑
• 接收密码验证消息后，更新本地存储并关闭弹窗

当前代码实现 #

Service Worker代码 #

/// <reference types="chrome-types"/>

(async () => {
    console.log('Extension started. Modal opened...');

  const window = await chrome.windows.create({
    url: chrome.runtime.getURL("html/index.html"),
    type: "popup",
    width: 400,
    height: 600,
  });

  chrome.windows.onRemoved.addListener((windowId) => {
    if (windowId === window?.id) chrome.runtime.sendMessage({ monitoringEnabled: true, reason: 'tab closed' }).catch(console.log);
  });

  chrome.runtime.onMessage.addListener((message) => {
    if (Object.hasOwn(message, 'monitoringEnabled')) {
        console.log(`Monitoring ${message.monitoringEnabled ? 'enabled' : 'disabled'}. ${message.reason ? `Reason: ${message.reason}` : ''}`)

        chrome.storage.local.set({ monitoringEnabled: message.monitoringEnabled });

        if (window?.id) chrome.windows.remove(window.id);
    }

    return true;
  });
})();

弹窗页面脚本 #

const MASTER_PASSWORD = 'some_thing_here';

document.getElementById('submit-button').addEventListener("click", (e) => {
    const password = document.getElementById('master-password-text-field').value;

    if (password !== MASTER_PASSWORD) return chrome.runtime.sendMessage({ monitoringEnabled: true, reason: 'invalid password' })
    
    return chrome.runtime.sendMessage({ monitoringEnabled: false })
})

异常现象 #

1. 弹窗关闭时触发错误，且onMessage监听器未被触发
2. 弹窗脚本发送消息时，监听器虽触发但处理后仍出现连接错误

原因分析 #

• 异常1：Service Worker在onRemoved回调中调用chrome.runtime.sendMessage时，是向自身发送消息，但Chrome扩展的消息机制中，发送方无法监听自己发出的消息，导致消息无人处理，同时触发发送失败错误。
• 异常2：弹窗脚本调用chrome.runtime.sendMessage后，Service Worker的onMessage监听器仅返回true声明异步响应，但未实际调用sendResponse回复消息，导致Chrome判定消息通道超时，抛出连接错误。

可行修复方案 #

修复异常1：移除不必要的自发送消息逻辑 #

将弹窗关闭后的逻辑直接内联到onRemoved回调中，无需通过消息传递：

chrome.windows.onRemoved.addListener((windowId) => {
  if (windowId === window?.id) {
    console.log('Monitoring enabled. Reason: tab closed');
    chrome.storage.local.set({ monitoringEnabled: true });
  }
});

修复异常2：完善消息响应机制 #

修改Service Worker的onMessage监听器，添加响应回调：

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (Object.hasOwn(message, 'monitoringEnabled')) {
      console.log(`Monitoring ${message.monitoringEnabled ? 'enabled' : 'disabled'}. ${message.reason ? `Reason: ${message.reason}` : ''}`);

      // 异步操作后发送响应
      chrome.storage.local.set({ monitoringEnabled: message.monitoringEnabled }).then(() => {
          if (window?.id) chrome.windows.remove(window.id);
          sendResponse({ success: true });
      });

      // 返回true表示将异步调用sendResponse
      return true;
  }
});

同时优化弹窗脚本，阻止表单默认行为并处理响应：

document.getElementById('submit-button').addEventListener("click", async (e) => {
    e.preventDefault(); // 避免表单提交导致页面刷新
    const password = document.getElementById('master-password-text-field').value;
    const message = password !== MASTER_PASSWORD 
        ? { monitoringEnabled: true, reason: 'invalid password' }
        : { monitoringEnabled: false };
    
    try {
        await chrome.runtime.sendMessage(message);
    } catch (err) {
        console.log(err);
    }
});

额外优化建议 #

• 由于Service Worker可能因休眠导致window变量失效，可将弹窗ID存储到chrome.storage.local，或在onRemoved回调中通过窗口URL/类型判断是否为目标弹窗
• 弹窗页面可添加密码输入框的回车提交逻辑，提升用户体验

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