Safari扩展Manifest v3调用chrome.storage.local.set触发Service Worker错误

问题场景 #

在macOS 13.3.1(a)的Safari浏览器中，使用Manifest V3开发的扩展在以下操作时触发**"The service worker script failed to load due to an error"**错误：

• 重启Safari后点击设置页面的「Save Options」按钮
• 重启Safari打开设置页面后点击工具栏按钮

所有触发场景均涉及chrome.storage.local.set操作，该问题仅在Safari中出现，Chrome扩展无此问题，且Manifest V2版本代码可正常运行。

问题分析 #

Safari对Manifest V3的Service Worker生命周期管理、chrome.storage API的异步处理逻辑与Chrome存在差异：

1. 重启Safari后，扩展的Service Worker处于未完全激活状态，此时调用chrome.storage.local.set可能导致Service Worker上下文崩溃
2. Service Worker中若存在未捕获的错误（如storage事件监听逻辑异常），会触发加载失败提示
3. Safari对MV3扩展的模块语法（type: 'module'）兼容性存在特殊要求

解决方案 #

1. 确保Service Worker就绪后再调用存储API #

在执行chrome.storage.local.set前，先验证Service Worker的激活状态，避免在未就绪时调用存储接口：

async function ensureServiceWorkerReady() {
  try {
    // 通过发送消息确认Service Worker可响应
    await chrome.runtime.sendMessage({ type: 'SW_READY_CHECK' });
  } catch (error) {
    // 尝试重启Service Worker并等待就绪
    chrome.runtime.reload();
    await new Promise(resolve => setTimeout(resolve, 600));
    await chrome.runtime.sendMessage({ type: 'SW_READY_CHECK' });
  }
}

// 在保存操作中使用
document.getElementById('saveOptions').addEventListener('click', async () => {
  const userOptions = { /* 从UI获取的配置数据 */ };
  await ensureServiceWorkerReady();
  await chrome.storage.local.set(userOptions);
  // 后续提示逻辑
});

同时在Service Worker中添加消息监听：

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'SW_READY_CHECK') {
    sendResponse(true);
  }
  return true; // 标记异步响应
});

2. 捕获Service Worker中存储事件的所有异常 #

避免storage事件监听逻辑中的未捕获错误导致Service Worker崩溃：

chrome.storage.local.onChanged.addListener((changes, area) => {
  try {
    // 处理存储变化的业务逻辑
    if (changes.theme) {
      // 执行主题更新操作
    }
  } catch (error) {
    console.error('Storage change handler error:', error);
    // 可添加错误上报逻辑
  }
});

3. 调整Manifest配置的兼容性 #

检查manifest.json中的background字段，确保符合Safari的MV3要求：

• 若使用ES模块语法，保留type: 'module'；若使用CommonJS，移除该字段
• 确保service_worker路径正确，无大小写或路径错误

"background": {
  "service_worker": "background.js",
  "type": "module"
}

4. 启用Safari扩展调试定位具体错误 #

通过Safari开发者工具查看详细错误日志：

1. 打开Safari偏好设置，在「高级」中勾选「显示开发菜单」
2. 点击顶部菜单「开发」->「扩展」->「检查扩展」
3. 选中你的扩展的Service Worker，查看控制台输出的具体错误信息（如Promise未捕获、变量未定义等）

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