Userscripts项目GM.xmlHttpRequest API版本兼容性解析

核心问题概述

在开发使用Userscripts项目的脚本时，开发者遇到了GM.xmlHttpRequest API在不同版本间的兼容性问题。特别是当尝试发送ArrayBuffer类型数据时，发现当前应用商店发布的1.5.4/4.5.4版本并不支持非字符串请求体，而文档中已经描述了v5.0.0将支持的新特性。

版本差异分析

当前稳定版(1.5.4/4.5.4)与即将发布的v5.0.0在GM.xmlHttpRequest实现上存在显著差异：

1. 请求体类型支持：

   • 当前版本：仅支持字符串和二进制字符串
   • v5.0.0：将支持ArrayBuffer等现代数据类型

2. 二进制数据处理：

   • 当前版本：需要使用遗留的binary参数
   • v5.0.0：采用更现代的API设计

临时解决方案

对于需要在当前版本发送二进制数据的开发者，可以采用版本检测和数据类型转换的方案：

if (typeof scriptManager !== 'undefined' && scriptManager.version < '5.0.0') {
  // 将ArrayBuffer转换为兼容格式
  requestBody = arrayBufferToString(arrayBuffer);
} else {
  // 直接使用ArrayBuffer
  requestBody = arrayBuffer;
}

关于禁止修改的HTTP头

讨论中还涉及到了修改禁止修改的HTTP头(如Origin等)的技术可行性：

1. Safari限制：

   • 不支持webRequestBlocking API
   • declarativeNetRequest的modifyHeaders功能需要Safari 16.4+

2. 潜在解决方案：

   • 对支持新API的设备使用updateSessionRules临时修改规则
   • 发送请求后立即移除规则
   • 注意不同Safari版本的功能支持差异

开发者建议

1. 版本适配：

   • 明确检查Userscripts版本
   • 为不同版本准备备用方案

2. API使用：

   • 优先使用文档中标记为稳定的功能
   • 对新特性保持谨慎，考虑降级方案

3. 环境考虑：

   • 注意Safari版本限制
   • 评估最低支持版本需求

未来展望

项目维护者表示计划在v4.7.x/1.7.x版本中向前移植部分v5.0.0的XHR改进，这将缩短开发者等待完整v5.0.0功能的时间窗口。同时，团队也在关注declarativeNetRequest等新API的整合可能性，以提供更强大的网络请求控制能力。

对于长期维护的脚本，建议建立完善的版本检测和功能降级机制，以应对不同运行环境下的API差异。