为Chrome扩展添加Service Worker后DevTools页面无法加载的原因

问题 #

我正在开发一款带DevTools面板和Service Worker的Chrome扩展，用了Manifest V3的极简配置：

{
  "manifest_version": 3,
  "name": "My Custom DevTools",
  "version": "1.0.0",
  "devtools_page": "devtools.html",
  "background": {
    "service_worker": "service-worker.js"
  }
}

实际测试时，Service Worker能正常启动，但浏览器始终不加载DevTools页面；移除background配置后，DevTools面板就能正常显示。Vue、React、Svelte这类知名开发者工具扩展都用类似配置，理论上应该可行，为什么加了Service Worker会导致DevTools页面失效？

相关代码如下：

register.js #

chrome.devtools.panels.create('My Custom DevTools', null, 'devtools-panel.html', (panel) => {
  console.log('DevTools panel was loaded', { panel })
})

service-worker.js #

console.log('Service worker started')

devtools.html #

<script src="register.js"></script>

devtools-panel.html #

<!DOCTYPE html>
<html style="display: flex">
<head>
  <meta charset="UTF-8">
  <link href="/favicon.ico" rel="icon">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <title>My Custom DevTools</title>
  <meta charset="utf8" />
</head>

<body>
  <h1>Custom DevTools Content</h1>
</body>
</html>

原因及解决方案 #

这个问题出在Manifest V3中扩展的启动时机和资源加载优先级上：

• 添加Service Worker后，Chrome会优先启动后台Service Worker，此时DevTools页面的注册脚本可能因为扩展上下文初始化顺序问题，没有被正确执行。
• 另一个核心原因是你的devtools.html缺少完整的HTML结构，虽然Chrome允许极简写法，但在有Service Worker的场景下，这种不完整的页面结构会触发加载异常。

修复步骤 #

1. 完善devtools.html的HTML结构：给devtools.html补充完整的HTML骨架，确保Chrome能正确识别并加载这个页面：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
</head>
<body>
  <script src="register.js"></script>
</body>
</html>

2. 校验资源路径与访问权限：确认register.js、devtools-panel.html等文件的路径无误，若扩展配置了web_accessible_resources，要将这些文件纳入允许访问的列表。
3. 排查Service Worker的潜在阻塞：如果Service Worker存在错误或异步阻塞逻辑，可能间接影响DevTools页面加载，可以暂时注释Service Worker内的代码，逐步排查冲突点。

调整后，DevTools页面就能和Service Worker正常共存，和Vue/React DevTools这类成熟扩展的运作逻辑一致。

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