Gitea 仓库中 INDEX.md 链接无法跳转的原因与正确写法

• 状态：已验证
• 来源：对话整理
• 更新时间：2026-03-12

关键结论

• Gitea 中以 / 开头的 Markdown 链接会被解析为站点根路径，而不是仓库根目录相对路径。
• 仓库内文档跳转应使用 ./、../ 或不带前导斜杠的相对路径。
• INDEX.md 不是 Gitea 仓库首页默认入口文件，通常应由 README.md 作为首页入口。

详细分析

• /topics/git/overview.md 会被解析为站点根路径下的资源，而不是当前仓库中的 topics/git/overview.md。
• INDEX.md 只是普通 Markdown 文件，内部链接是否可用取决于路径写法是否为仓库内相对路径。
• 文件名大小写不一致、中文路径或带空格路径，也可能导致仓库内跳转失败。

可执行步骤

1. 检查 INDEX.md 和其他导航文档中是否使用了 /xxx 形式的仓库内链接。
2. 将仓库内链接统一改为 ./topics/<topic>/overview.md、./topics/<topic>/<subtopic>.md 或对应的相对路径。
3. 在仓库根目录保留 README.md 作为首页入口，再由 README.md 跳转到 INDEX.md。
4. 检查目标文件名大小写是否与仓库实际路径完全一致。

命令 / 配置 / 代码

# 推荐写法
- [Git](./topics/git/overview.md)
- [Linux](./topics/linux/overview.md)

# 子目录场景
- [Git](../topics/git/overview.md)

# 不推荐
- [Git](/topics/git/overview.md)

风险与注意事项

• 文件路径大小写必须与仓库实际文件名完全一致。
• 中文文件名和空格文件名虽然通常可用，但不利于长期维护，建议保持稳定命名。
• 不要把 Gitea 的站点根路径规则误认为仓库根目录相对路径规则。