如何在Manifest V3中添加后台脚本？V2转V3遇document未定义报错

问题根源 #

Manifest V3的后台Service Worker是无DOM环境，不存在document、window这类浏览器页面对象。你现在直接在service-worker.js里导入popup.js（原本是依赖DOM的弹窗页面代码）和浏览器版socket.io.js，必然触发document is not defined错误——这些代码从设计上就不该在后台Service Worker里运行。

解决方案：拆分代码职责 #

把不同环境的代码彻底分离，各司其职：

1. 剥离Popup相关代码 #

popup.js是给弹窗页面（popup.html）服务的，直接在popup.html里引入即可，完全不需要在Service Worker里导入：

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <!-- 弹窗样式代码 -->
</head>
<body>
  <!-- 弹窗内容结构 -->
  <script src="socket.io.js"></script>
  <script src="popup.js"></script>
</body>
</html>

2. 调整Service Worker的Socket.io使用 #

如果后台需要保持socket长连接，不要用浏览器版的socket.io.js，改用适配Service Worker环境的socket.io客户端ES模块版本。修改service-worker.js：

// service-worker.js
import { io } from './socket.io.esm.min.js'; // 使用支持Service Worker的ES模块版本

// 后台专属逻辑：监听扩展安装、处理跨环境消息等
chrome.runtime.onInstalled.addListener(() => {
  console.log('扩展已完成安装');
});

// 建立后台socket连接
const socket = io('你的服务器地址');
socket.on('connect', () => {
  console.log('后台socket连接成功');
});

3. 内容脚本的正确用法 #

如果是要在目标网页中使用socket.io，你之前的chrome.scripting.registerContentScripts思路没问题，但要注意：

• 确保matches字段匹配你需要注入的网站域名（比如["*://*/*"]覆盖所有网站）
• 内容脚本运行在网页环境中，可以正常使用document等DOM API
• 不要把内容脚本逻辑和后台Service Worker代码混淆

关键提醒 #

• Service Worker只负责后台任务：监听扩展事件、处理跨环境消息、后台数据同步等，绝对不能编写依赖DOM的代码
• 弹窗、内容脚本、Service Worker是三个独立的运行环境，各自的代码要放在对应位置，通过Chrome扩展的消息API（chrome.runtime.sendMessage/onMessage）实现互相通信

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