MkDocs Material 版本切换功能的问题分析与修复

在 MkDocs Material 文档主题中，版本切换功能是帮助用户在不同文档版本间导航的重要组件。近期用户报告了一个影响用户体验的严重问题：当用户尝试切换到另一个版本时，系统无法正确保留当前页面路径，而是直接跳转到目标版本的首页。

问题现象

当用户位于某个特定页面（例如配置页面）并使用版本切换器切换到另一个版本时，系统会错误地导航到目标版本的根目录，而不是保持相同的相对路径。例如：

• 当前页面：prerelease/config/
• 切换至 v0.17.0 版本
• 预期结果：v0.17.0/config/
• 实际结果：v0.17.0/

这个问题严重影响了用户体验，特别是对于需要频繁查阅不同版本间特定内容差异的技术用户。

技术分析

经过深入调查，发现问题源于版本 9.5.5 中对站点地图(sitemap)加载逻辑的重构。这个重构原本是为了支持即时导航功能，但在处理相对路径匹配时出现了逻辑缺陷。

具体来说，系统在比较当前路径与站点地图中的条目时，使用了完整的URL路径进行匹配，而没有正确处理相对路径的提取和比较。站点地图中存储的是完整的绝对路径（包含域名），而当前路径只提取了相对部分，导致匹配失败。

解决方案

开发团队在提交 ceacfe5a2 中修复了这个问题。修复的核心内容包括：

1. 修正了路径比较逻辑，确保正确处理相对路径匹配
2. 优化了站点地图加载流程，保持与即时导航功能的兼容性
3. 增强了测试用例，覆盖更多版本切换场景

修复后的版本（9.5.22）已经验证可以正常工作，用户现在可以无缝地在不同版本间切换，同时保持浏览的页面位置。

最佳实践建议

对于使用 MkDocs Material 的项目维护者：

1. 及时升级到最新版本以获得修复
2. 测试版本切换功能是否在所有目标页面上正常工作
3. 考虑为项目设置自动化构建和部署流程，以便快速发现类似问题

对于高级用户，还可以考虑扩展功能，使版本切换器能够处理不同部署环境（如开发服务器与生产环境）的路径差异，进一步提升使用体验。

MkDocs Material 团队持续关注用户体验，鼓励用户报告任何异常行为，共同完善这一优秀的文档工具。