Qexo项目中友链页面首次加载不显示的问题分析与解决

问题现象

在使用Qexo v3.6.0搭建的网站中，用户发现友链页面存在一个奇怪的显示问题：当从其他页面跳转到友链页面时，友链内容无法正常显示，只有手动刷新页面后才会出现。这个问题在使用PostgreSQL数据库和Vercel部署的环境中尤为明显。

问题根源分析

经过技术排查，这个问题主要与Next主题的Pjax实现机制有关。Pjax是一种通过Ajax和pushState技术实现的页面无刷新加载技术，它能够提升网站浏览体验，但在处理动态内容加载时可能会出现问题。

具体到本案例中，友链内容是通过Qexo的loadQexoFriends函数动态加载的，而Pjax在页面切换时不会自动重新执行这个函数，导致内容无法显示。

解决方案

方案一：配置Pjax重载函数

最直接的解决方案是为Pjax配置重载函数，确保在每次Pjax完成页面加载后都重新执行友链加载逻辑：

document.addEventListener('pjax:complete', function() {
    loadQexoFriends(id, url);
});

这段代码需要放置在主题模板或页面中，监听Pjax完成事件并触发友链加载。

方案二：使用raw标签处理脚本

在Markdown文件中直接插入JavaScript代码时，可能会遇到特殊字符被错误解析的问题。可以使用Liquid模板语言的raw标签来避免这个问题：

{% raw %}
<script>
document.addEventListener('pjax:complete', function() {
    loadQexoFriends(id, url);
});
</script>
{% endraw %}

方案三：完全禁用Pjax

如果对Pjax不熟悉或遇到难以解决的问题，最简单的方案是在Next主题配置中完全禁用Pjax功能。虽然这会牺牲部分用户体验，但能确保所有功能正常工作。

最佳实践建议

1. 脚本放置位置：建议将Pjax重载脚本放在主题的公共模板文件中，而不是单个页面，确保全局生效。

2. 错误处理：在重载函数中添加错误处理逻辑，避免因某个页面缺少必要参数而导致整个脚本失效。

3. 性能优化：可以考虑添加防抖机制，避免短时间内多次触发重载函数。

4. 兼容性检查：确保重载函数在所有浏览器中都能正常工作，特别是要考虑移动端浏览器的兼容性。

总结

Qexo项目中友链页面首次加载不显示的问题，本质上是一个典型的Pjax与动态内容加载的兼容性问题。通过合理配置Pjax事件监听器，可以很好地解决这类问题。对于不熟悉前端技术的用户，建议仔细阅读相关文档或寻求社区帮助，以确保解决方案的正确实施。