如何解决Chrome扩展Manifest V3中socket.io实现报错的问题

出现该报错的核心原因是Manifest V3的后台运行环境为Service Worker，不存在window、document等浏览器DOM API，而默认构建的socket.io客户端会检测这两个对象是否存在，因此触发引用错误。可以根据你的实际需求选择以下任意一种方案解决：

方案1：Mock DOM对象绕过检测 #

如果你的socket逻辑不需要用到socket.io和DOM相关的功能（比如http长轮询降级），可以在导入socket.io之前，在background.js顶部手动模拟全局DOM对象，绕过存在性检测即可：

// background.js 顶部最先执行该段代码
globalThis.window = {};
globalThis.document = {
  // 仅模拟socket.io检测会用到的方法，不需要实现实际逻辑
  createElement: () => ({})
};

// 之后再导入socket.io
import io from './path/to/socket.io-client.esm.js';
// 后续正常使用io初始化连接即可

注意：该方案依赖socket.io的具体实现逻辑，部分高版本socket.io如果实际调用了DOM相关方法，可能会出现后续报错，遇到这种情况建议更换为其他方案。

方案2：直接使用原生WebSocket API #

如果你不需要用到socket.io的专属能力（自动重连、消息确认、房间管理、传输协议自动降级），可以直接使用Service Worker原生支持的WebSocket API，无任何额外依赖，也不会出现DOM相关报错：

// 原生WebSocket使用示例
const ws = new WebSocket('wss://你的服务端WebSocket地址');

// 连接建立回调
ws.onopen = () => {
  console.log('WebSocket连接成功');
  // 发送消息
  ws.send(JSON.stringify({
    type: 'test',
    content: '测试消息'
  }));
};

// 接收消息回调
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('收到服务端消息：', message);
};

// 连接断开回调，可自行实现重连逻辑
ws.onclose = () => {
  console.log('WebSocket连接断开');
};

方案3：通过Offscreen API运行socket.io（兼容性最优） #

Chrome 109及以上版本支持offscreen权限，可以创建一个后台隐藏的、拥有完整DOM环境的离线页面，将socket.io的逻辑放在该页面运行，background通过消息通信和离线页面交互即可，完全兼容所有版本的socket.io：

1. 首先在manifest.json中添加offscreen权限：

{
  "manifest_version": 3,
  "permissions": ["offscreen"],
  // 其他配置项...
}

2. 在background.js中初始化离线页面：

// 先判断是否已存在离线页面，避免重复创建
async function initOffscreen() {
  if (await chrome.offscreen.hasDocument()) return;
  await chrome.offscreen.createDocument({
    url: 'offscreen.html',
    reasons: ['OTHER'],
    justification: '运行socket.io客户端'
  });
}
initOffscreen();

// 示例：向offscreen页面发送消息，触发socket发送逻辑
chrome.runtime.sendMessage({
  action: 'send_socket',
  event: 'test_event',
  data: '测试数据'
});

// 示例：监听offscreen页面转发的socket消息
chrome.runtime.onMessage.addListener((msg) => {
  if (msg.action === 'receive_socket') {
    console.log('收到socket消息：', msg.event, msg.data);
  }
});

3. 创建offscreen.html文件，在该文件中正常引入使用socket.io：

<!DOCTYPE html>
<html>
<body>
<script src="./path/to/socket.io.min.js"></script>
<script>
const socket = io('wss://你的socket.io服务端地址');

// 监听background发来的发送请求
chrome.runtime.onMessage.addListener((msg) => {
  if (msg.action === 'send_socket') {
    socket.emit(msg.event, msg.data);
  }
});

// 转发socket收到的消息到background
socket.onAny((event, data) => {
  chrome.runtime.sendMessage({
    action: 'receive_socket',
    event: event,
    data: data
  });
});
</script>
</body>
</html>

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