Extension.js 项目中的 Service Worker 注册问题分析与解决

在 Extension.js 项目开发过程中，开发者可能会遇到 Service Worker 注册失败的问题，错误提示为"Service worker registration failed. Status code: 2"。这个问题在使用 content-react 模板创建新扩展时尤为常见。

问题现象

当开发者使用 Extension.js 的 content-react 模板创建新扩展时，在 Chrome 扩展管理页面(chrome://extensions)点击重新加载按钮后，控制台会显示上述错误信息。值得注意的是，这个问题在以下情况下不会出现：

• 运行 dev 命令后手动加载未打包扩展
• 执行 build 和 start 命令时

问题根源分析

经过深入调查，这个问题主要与 Extension.js 项目的版本兼容性和构建流程有关。具体表现为：

1. 背景脚本(background.ts)中的日志语句无法正常输出
2. Service Worker 注册过程中出现状态码为2的错误
3. 该问题在特定版本(v2.0.0-alpha.8)中尤为明显

解决方案

针对这个问题，Extension.js 团队已经发布了多个修复版本。推荐的解决步骤如下：

1. 确保使用最新版本的 Extension.js CLI 工具：

   npx extension@latest create my-extension --template=content-react
   

2. 清理项目依赖和构建缓存：

   rm -rf node_modules/
   rm pnpm-lock.yaml
   pnpm store prune
   rm -rf dist/
   

3. 升级到 v2.0.0-rc.23 或更高版本

开发环境注意事项

在 Windows 11 系统下使用 pnpm 作为包管理器时，需要特别注意：

• 确保 Node.js 版本在 v20.16.0 或以上
• 使用 pnpm v9.12.2 或更高版本
• 清除所有缓存文件后再重新安装依赖

最佳实践建议

1. 始终使用最新稳定版本的 Extension.js
2. 在项目初始化后立即清理构建缓存
3. 定期检查项目依赖的版本兼容性
4. 开发过程中保持 Chrome 浏览器为最新版本

通过遵循上述建议，开发者可以有效避免 Service Worker 注册失败的问题，确保扩展开发流程的顺畅进行。