Chrome扩展chrome.runtime.sendMessage传入ID在页面上下文失效问题排查

问题原因拆解 #

• 普通网页（top页面）不属于扩展上下文，默认没有权限调用Chrome扩展的消息API，必须通过扩展配置授权。
• 不带ID报错：普通网页没有关联的扩展ID，省略ID时chrome.runtime.sendMessage无法确定目标扩展，直接抛出错误。
• 带ID无效果：扩展未配置允许该网页发送外部消息，Chrome会拦截请求，不会传递到扩展的监听逻辑中。

解决步骤 #

1. 配置扩展的manifest.json #

在扩展的manifest.json中添加externally_connectable字段，指定允许发送消息的网页域名。测试阶段可暂时用<all_urls>，生产环境建议限制具体域名：

{
  "manifest_version": 3,
  // 其他扩展配置...
  "externally_connectable": {
    "matches": ["*://*.your-domain.com/*"] // 替换为你的网页域名
  }
}

2. 扩展中添加外部消息监听 #

扩展的后台脚本（如background.js）需要使用chrome.runtime.onMessageExternal监听外部网页的消息，而不是普通的chrome.runtime.onMessage：

// background.js
chrome.runtime.onMessageExternal.addListener((message, sender, sendResponse) => {
  console.log('收到网页消息:', message);
  // 编写你的消息处理逻辑
  sendResponse({ result: '消息已接收' });
  // 若处理为异步操作，需返回true保持响应通道开启
  // return true;
});

3. 普通网页中正确调用API #

网页中必须指定扩展ID，同时建议添加回调函数捕获错误：

// 网页脚本
chrome.runtime.sendMessage('bgmpeololjflcbghnmfkfldminickkog', { text: "hogee." }, (response) => {
  if (chrome.runtime.lastError) {
    console.error('发送失败:', chrome.runtime.lastError.message);
    return;
  }
  console.log('扩展响应:', response);
});

排查要点 #

• 检查manifest.json是否存在语法错误，配置后需重新加载扩展（Chrome扩展页面点击「重新加载」按钮）。
• 确认网页域名完全匹配externally_connectable.matches的规则，注意http和https是不同协议，需分别配置或用*://覆盖。
• 查看Chrome控制台的错误信息，chrome.runtime.lastError会给出具体失败原因（如「扩展未安装」「权限不足」等）。

内容的提问来源于stack exchange，提问作者丶 Limeー来夢 丶