Chrome runtime.Port onDisconnect多次触发问题排查求助

问题场景与异常表现 #

• 内容脚本通过browser.runtime.connect({name: 'processor'})与服务工作者建立长连接，端口存储为类字段；服务工作者用字典跟踪端口，断开时从字典移除，但未取消事件订阅。
• 异常现象：
  • 新端口注册后立即触发onDisconnect事件，但端口仍能正常收发对应标签页的消息
  • 标签页关闭时会触发第二次onDisconnect（仅在消息持续传输的场景下）
  • 服务工作者中端口断开日志数量多于新连接日志
  • 触发场景不稳定：新标签页导航有时出现问题，F5刷新页面则不会立即断开，测试结果非100%一致
• 旧代码原本运行正常，怀疑是代码遗漏或Chrome版本更新导致。

可能原因分析 #

1. Chrome服务工作者生命周期管控变化（重点怀疑） #

Chrome近年对服务工作者的休眠/唤醒逻辑做了更严格的管控：当服务工作者进入休眠状态前，可能会触发端口的onDisconnect事件，但如果后续有消息交互触发服务工作者唤醒，端口实际并未真正断开，从而出现"假断开"的情况。

• 新标签页导航时，服务工作者可能处于刚启动或即将休眠的临界状态，容易触发该假断开；而F5刷新时，页面与内容脚本启动更同步，服务工作者处于活跃状态，不会触发假断开。

2. 端口事件监听器残留导致的引用泄漏 #

即使将端口从字典中移除，onDisconnect和onMessage的事件监听器仍绑定在端口对象上，导致端口无法被垃圾回收。后续服务工作者重启、页面状态变化等隐性条件，可能再次触发该端口的onDisconnect事件。

3. 内容脚本重复注入与端口重复创建 #

部分场景下（如页面导航时的异步注入），内容脚本可能被重复注入，创建多个端口，但只有一个能正常存续，其余端口立即断开，导致断开日志数量超过连接日志。

解决方案建议 #

1. 优化端口管理与事件清理逻辑 #

处理onDisconnect时，不仅要移除字典中的端口，还要主动解绑事件监听器，避免残留引用：

// 服务工作者中处理端口断开的逻辑
function handlePortDisconnect(port) {
  const tabId = port.sender?.tab?.id;
  if (tabId) delete portMap[tabId];
  // 移除绑定的事件监听器
  port.onMessage.removeListener(handlePortMessage);
  port.onDisconnect.removeListener(() => handlePortDisconnect(port));
}

// 服务工作者监听新连接时，增加重复端口校验
browser.runtime.onConnect.addListener(port => {
  if (port.name !== 'processor') return;
  const tabId = port.sender?.tab?.id;
  if (!tabId) return;
  
  // 如果该标签页已有端口，先清理旧端口
  if (portMap[tabId]) {
    handlePortDisconnect(portMap[tabId]);
  }
  
  portMap[tabId] = port;
  port.onMessage.addListener(handlePortMessage);
  port.onDisconnect.addListener(() => handlePortDisconnect(port));
});

2. 适配Chrome服务工作者生命周期 #

• 监听服务工作者的休眠事件，主动清理所有端口，避免假断开：

browser.runtime.onSuspend.addListener(() => {
  // 休眠前主动清理所有端口
  Object.values(portMap).forEach(port => handlePortDisconnect(port));
});

• 内容脚本侧增加端口健康检查与重连逻辑，应对假断开：

class ContentScriptConnector {
  constructor() {
    this.port = null;
    this.connect();
  }
  
  connect() {
    this.port = browser.runtime.connect({name: 'processor'});
    this.port.onDisconnect.addListener(() => {
      // 延迟重试，避免频繁重连
      setTimeout(() => this.connect(), 1000);
    });
    this.port.onMessage.addListener(this.handleMessage.bind(this));
  }
  
  handleMessage(msg) {
    // 业务消息处理逻辑
  }
}

3. 排查内容脚本注入逻辑 #

• 检查manifest.json中的内容脚本配置，避免重复注入：

"content_scripts": [
  {
    "matches": ["<all_urls>"],
    "js": ["content.js"],
    "run_at": "document_start",
    "all_frames": false // 根据业务需求设置，避免多帧重复注入
  }
]

• 内容脚本中增加单例模式，确保每个页面仅创建一个端口：

if (!window.__CONTENT_CONNECTOR_INSTANCE) {
  window.__CONTENT_CONNECTOR_INSTANCE = new ContentScriptConnector();
}

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