Wakapi浏览器插件心跳请求兼容性问题分析

问题背景

Wakapi作为一个开源的编程时间追踪工具，提供了与WakaTime兼容的API接口。近期有用户报告，在浏览器插件更新后，心跳数据无法正常同步到Wakapi服务器。通过分析日志发现，浏览器插件发送的OPTIONS预检请求被服务器拒绝，返回405 Method Not Allowed错误。

技术细节

问题核心在于CORS(跨域资源共享)预检请求的处理机制。现代浏览器在发送某些类型的跨域请求前，会先发送一个OPTIONS方法的预检请求，以确定服务器是否允许实际请求。

在Wakapi的兼容API端点中，原本可能没有正确处理OPTIONS方法请求。当浏览器插件更新后，可能开始更严格地遵循CORS规范，导致预检请求失败，进而阻止了实际心跳数据的发送。

解决方案

开发团队通过提交40e01c1修复了这个问题，主要改动包括：

1. 在兼容API路由中显式处理OPTIONS方法请求
2. 确保预检请求能够获得正确的CORS响应头
3. 允许浏览器插件完成完整的CORS检查流程

验证方法

用户可以通过以下方式验证问题是否解决：

1. 检查浏览器开发者工具中的网络请求，确认OPTIONS请求是否获得200状态码
2. 观察实际的心跳POST请求是否能够成功发送
3. 确认Wakapi仪表板中是否开始显示浏览器活动数据

最佳实践建议

对于自托管Wakapi实例的管理员，建议：

1. 及时更新到包含此修复的版本
2. 定期检查服务器日志中的CORS相关错误
3. 确保反向代理配置不会干扰OPTIONS请求的处理
4. 测试不同浏览器插件的兼容性

总结

这个案例展示了API兼容性维护中的常见挑战，特别是当客户端行为发生变化时。通过正确处理CORS预检请求，Wakapi确保了与各种客户端工具的稳定兼容性，为用户提供了无缝的时间追踪体验。