Guava项目官网样式失效问题分析与解决

在2025年4月1日，Google Guava项目团队发现其官方网站guava.dev出现了样式失效的问题，页面显示为非常简单的纯文本格式，失去了原有的美观样式。这个问题引起了开发团队的重视，因为官网是开发者了解和使用Guava库的重要入口。

问题现象

当访问guava.dev时，页面失去了所有CSS样式，呈现出未经美化的原始HTML结构。通过检查页面源代码，发现CSS文件的引用路径存在问题：

<link rel="stylesheet" href="/pages/google/guava/css/main.css">

这个路径实际上并不存在，而正确的路径应该是/css/main.css。这种路径错误导致了浏览器无法加载样式表，从而使页面失去了视觉设计效果。

问题排查过程

开发团队首先检查了相关配置文件，发现_config.yml中的baseUrl设置是正确的，值为/。这表明问题不是由基础URL配置错误直接引起的。

团队随后检查了GitHub Actions的构建日志，发现最近的构建过程没有明显的错误信息。构建使用的jekyll-build-pages版本(v1.0.13)和Jekyll版本(v3.10.0)与之前成功的构建一致，排除了构建工具版本变更导致问题的可能性。

通过对比其他Google开源项目(如truth.dev和dagger.dev)的网站，发现这些项目使用了不同的构建配置，因此没有出现类似问题。

解决方案

作为临时解决方案，开发团队尝试在_config.yml中为版本号添加引号。虽然这个改动看起来与CSS路径问题没有直接关联，但神奇地解决了问题。页面样式恢复正常，显示效果如下：

![恢复后的Guava官网样式]

值得注意的是，在后续的33.4.7版本发布后，即使移除了版本号的引号，问题也没有再次出现。这表明最初的解决方案可能只是巧合，真正的问题根源可能更加复杂。

经验总结

这个事件提醒我们几个重要的技术实践：

1. 网站部署后的定期检查非常重要，可以及时发现并解决问题
2. 配置文件的格式细节(如YAML中的引号使用)有时会产生意想不到的影响
3. 构建系统的更新可能会引入微妙的变化，需要密切关注
4. 保持构建环境的稳定性有助于问题排查

对于使用Jekyll构建的静态网站项目，建议开发团队：

• 建立本地测试环境，便于重现和调试问题
• 考虑实现自动化监控，及时发现网站异常
• 记录配置变更历史，便于追踪问题来源

虽然这次问题的根本原因尚未完全明确，但通过团队的快速响应和有效排查，最终确保了Guava项目官网的正常运行，为开发者提供了良好的文档查阅体验。