Microsoft Clarity 与 Partytown 集成中的 CSSMediaRule 问题解析

背景介绍

Microsoft Clarity 是一款用户行为分析工具，而 Partytown 是一个将第三方脚本移至 Web Worker 运行的解决方案。近期在 Clarity 0.7.43 版本中引入的新特性导致了与 Partytown 的兼容性问题。

问题本质

问题的核心在于 Clarity 0.7.43 版本新增了对 CSSMediaRule 接口的依赖，而该接口在 Web Worker 环境中默认不可用。具体表现为：

1. 当 Clarity 脚本通过 Partytown 在 Web Worker 中执行时
2. 尝试访问 CSSMediaRule 接口时会抛出"CSSMediaRule is undefined"错误
3. 这个问题在 0.7.41 版本之前不存在

技术细节分析

Web Worker 环境与主线程环境存在差异，不是所有浏览器 API 都在 Worker 中可用。CSS 相关接口特别是 CSSMediaRule 就是其中之一。Clarity 新增的媒体查询规则处理功能无意中引入了这个环境依赖。

有趣的是，在 Worker 中检查 CSSMediaRule 的存在性会得到矛盾的结果：

• 'CSSMediaRule' in window 返回 true
• 但实际访问 window.CSSMediaRule 却得到 undefined

这表明 Worker 环境中存在接口声明但未实现的情况。

解决方案演进

1. 初期修复尝试：Clarity 团队很快发布了修复 PR，但问题在 0.7.45 版本中仍然存在

2. Partytown 的改进：Partytown 项目后来通过添加 CSSMediaRule 的 polyfill 从根本上解决了这个问题

3. 使用建议：开发者应使用 @qwikdev/partytown 替代旧的 @builder.io/partytown 包，因为前者包含了必要的 polyfill

最佳实践建议

对于需要在 Web Worker 中运行分析脚本的场景：

1. 确保使用最新版本的 Partytown 实现
2. 考虑在 Worker 环境中测试所有依赖的浏览器 API
3. 对于关键业务功能，建议在主线程和 Worker 中实现降级方案
4. 定期检查三方库的更新日志，特别是环境依赖相关的变更

总结

这次兼容性问题展示了前端性能优化与功能完整性之间的平衡挑战。通过社区协作，最终找到了既保持性能优化又能确保功能完整的解决方案。这也提醒开发者在采用新技术方案时需要全面考虑环境差异带来的潜在问题。