使用Jekyll为GitHub Pages部署网页，日志成功但浏览器没有该网页。

[LiuHangyuWE]

背景

我希望将我的 GitHub 笔记仓库 software-projects-learning-notes 部署成一个公开的网站，方便查阅和分享。我选择了 GitHub Pages 的原生解决方案，使用 Jekyll 来构建静态网站。然而，在这个过程中，我遇到了从“页面 404”到“链接失效”再到“构建失败”等一系列问题。

已尝试的排查方法和结论：

1. 所有子页面（包括英文版）都 404 Not Found

   • 网站主页（中文 README.md）可以正常显示，并且有主题样式。
   • 点击主页上的任何链接（比如英文版徽章、指向 01-Project-Management 的链接）都会跳转到 404 页面。
   • 原因 ：Jekyll 的处理机制 —— Front Matter**。Jekyll 为了效率，只会处理那些它认为“应该被处理”的页面。它判断的依据是文件顶部是否有 YAML Front Matter，也就是两行 ---。为所有希望被 Jekyll 处理并生成网页的 Markdown 文件（包括中文主页 README.md、英文页 README.en.md 以及所有子目录里的 README.md）都在文件的绝对顶部添加空的两行 ---。在中文 readme 文件加上两行---后，反而所有网页均 404 not found 了。
   • 并且，加两条横线的方法本身也影响 md 文档美观。于是使用默认方式，为所有页面默认布局。

   defaults:
      - scope:
           path: "" # 匹配所有文件
   values:
     layout: "default"

2. 修改了 _config.yml 或 .md 文件后，网站没有更新

   • 我确认已经提交了修改，但 Actions 里没有新的构建任务，或者构建成功了但网站还是旧的样子。
   • 考虑到可能是 浏览器缓存：浏览器为了提高加载速度，会缓存旧的页面内容（包括 404 页面）。使用浏览器的开发者工具进行“清空缓存并硬性重新加载”（在刷新按钮上长按或右键点击），使用无痕模式访问。仍旧 404。
   • 极少数情况下，GitHub 的部署触发器可能会“卡住”。进入 Settings -> Pages，将部署源从 Deploy from a branch 切换到 GitHub Actions，然后再立刻切换回来并保存。这个操作会强制刷新后台的触发器。
   • 这两个方法仍然不行。

3. _config.yml 文件配置问题：

   • baseurl 和 url 的设置是关键。项目主页需要设置 baseurl: "/"。
   • 检查发现 url 存在拼写错误（https:/ 少一个斜杠）和大小写不一致的问题，已经改正。

4. 首页文件缺失问题 (index.html 或 index.md)：

   • 初期认为可能是因为根目录只有 README.md 而没有 index.md。
   • 思考并看 action 的日志后发现，GitHub Pages 默认使用 jekyll-readme-index 插件，会自动将 README.md 渲染为首页。
   • 因此，问题不在于缺少 index.html 或 index.md。

5. 本地环境与云端环境的区别：

   • 明确了 GitHub Pages 的构建是在云端完成的，与本地是否安装 Ruby/Jekyll 无关。
   • 本地安装 Ruby/Jekyll 的主要目的是为了方便本地预览和调试，实现“所见即所得”的开发流程，避免反复推送代码等待云端构建结果。

目前仍然不行。我正在使用 jekyll-theme-minimal 主题。我不确定这是我的配置问题，还是可能与主题本身有关。