Plausible社区版在Remix框架中实现访客统计的技术实践

问题背景

在使用Plausible社区版进行网站分析时，开发者遇到一个特殊现象：在Remix框架构建的网站上，页面浏览事件能够正常记录，但独立访客数始终显示为1。这个问题在使用Plausible托管服务时并不存在，且在同一Plausible实例下的Next.js网站工作正常。

技术环境分析

该问题出现在基于Remix框架的Shopify Hydrogen项目中，通过Nginx反向代理部署Plausible社区版。技术栈特点包括：

1. 使用Docker Compose部署Plausible v2.1.1社区版
2. PostgreSQL 16作为主数据库
3. ClickHouse 24.3.3.102作为事件数据库
4. Nginx作为反向代理，配置了SSL证书
5. 采用类似Next.js的代理方式处理Plausible脚本和事件API

问题诊断

通过现象分析，可以得出以下技术判断：

1. 事件记录机制正常：页面浏览事件能够正确记录，说明基础的事件收集和存储功能正常
2. 访客识别异常：独立访客数始终为1，表明访客识别机制存在问题
3. 框架差异性：Next.js工作正常而Remix异常，说明问题与框架实现方式相关

根本原因

深入分析后发现问题源于Remix框架中特殊的脚本代理实现方式。开发者采用了以下技术方案：

1. 通过Remix路由代理加载Plausible脚本
2. 通过API路由代理转发事件数据
3. 在根组件中引用代理后的脚本

这种实现方式虽然能够成功发送事件数据，但破坏了Plausible用于识别独立访客的机制。具体表现为：

• 代理处理过程中可能丢失或修改了关键的请求头信息
• 脚本执行环境发生变化，影响访客指纹生成
• 跨域限制导致部分识别信息无法正确传递

解决方案

经过验证，最简单的解决方案是放弃脚本代理方式，直接引用原始Plausible脚本。具体修改包括：

1. 移除脚本代理路由（js.script.[.js].ts）
2. 在根组件中直接引用Plausible官方脚本
3. 保留事件API代理以确保数据隐私

修改后的实现既保证了独立访客统计的准确性，又通过API代理维护了数据隐私。

技术启示

这一案例为我们提供了以下技术经验：

1. 分析工具集成：第三方分析工具的集成需要考虑其完整的识别机制，不能只关注基础事件发送
2. 框架特性影响：不同框架的SSR/CSR特性会影响分析数据的准确性
3. 渐进式调试：从简单实现开始，逐步增加复杂度，有助于定位问题根源
4. 数据验证：部署分析工具时应使用多种场景验证数据准确性

最佳实践建议

基于此案例，建议在Remix框架中集成Plausible时：

1. 优先考虑直接引用官方脚本的方式
2. 如必须代理，确保完整保留所有请求头和响应头
3. 实现后使用多种设备和场景测试数据收集情况
4. 定期检查数据异常，建立监控机制

通过这种方式，开发者可以在保持数据隐私的同时，确保分析数据的准确性和完整性。