MALSync项目在Firefox MV3扩展中的Jellyfin兼容性问题分析

问题背景

MALSync是一款流行的浏览器扩展，用于同步用户在不同媒体平台上的观看进度。在项目升级到Manifest V3版本后，开发团队发现了一个与Jellyfin媒体服务器集成的兼容性问题：在Firefox浏览器上无法正常工作，而在Chrome浏览器上则表现正常。

问题现象

当用户在Firefox上使用MALSync与Jellyfin交互时，控制台会出现以下错误信息：

MAL-Sync Api Call http://192.168.1.230:8096/System/Info?api_key=[REDACTED]
uncaught exception: NetworkError when attempting to fetch resource.

技术分析

1. CORS与权限问题

在Manifest V3中，Firefox对扩展的网络请求实施了更严格的CORS(跨域资源共享)策略。即使扩展已经获得了<all_urls>或特定域名的权限，请求仍可能因CORS限制而失败。

2. HTTP与HTTPS协议差异

深入调查发现，虽然Jellyfin服务器配置为HTTP协议，但Firefox扩展中的XHR请求被自动升级为HTTPS。这种自动升级行为源于Firefox MV3扩展的默认内容安全策略(CSP)中包含upgrade-insecure-requests指令。

3. 浏览器实现差异

Chrome和Firefox在MV3扩展的默认CSP策略上存在差异：

• Firefox默认包含"script-src 'self'; upgrade-insecure-requests;"
• Chrome则没有upgrade-insecure-requests指令

解决方案

1. 修改内容安全策略

通过在manifest.json中显式定义内容安全策略，覆盖默认设置：

"content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self';"
}

这种修改移除了upgrade-insecure-requests指令，允许扩展继续使用HTTP协议与本地Jellyfin服务器通信。

2. 替代实现方案

作为临时解决方案，开发人员发现将XHR调用替换为fetch API也能解决问题：

// 原XHR实现
return api.request.xhr('GET', url).then(res => {
  JSON.parse(response.responseText);
});

// 修改为fetch实现
return fetch(url).then(async res => {
  await response.json();
});

技术启示

1. 浏览器兼容性考量：即使是遵循相同规范(MV3)的扩展，在不同浏览器上的实现细节可能存在差异，需要特别关注。

2. 本地服务集成：与本地网络服务集成时，HTTP协议的使用仍然很常见，扩展设计需要考虑这种使用场景。

3. 安全策略影响：内容安全策略不仅影响页面内容加载，也会影响扩展的网络请求行为。

4. 调试技巧：使用Firefox的about:debugging页面可以有效地诊断扩展的网络请求问题。

最佳实践建议

1. 在开发跨浏览器扩展时，应尽早在不同浏览器上测试核心功能。

2. 对于需要与本地服务通信的扩展，建议在manifest中明确定义内容安全策略。

3. 考虑使用更现代的fetch API替代传统的XHR，以获得更好的兼容性和可维护性。

4. 在错误处理中，应明确区分网络错误、CORS错误和协议错误，以便更快定位问题。

这个问题展示了浏览器扩展开发中可能遇到的微妙兼容性问题，也提醒开发者在升级到新规范时需要全面测试各项功能。