单个Jekyll帖子无法渲染异常求助

嘿，这个问题我之前帮好几个开发者踩过坑，结合GitHub Pages和Jekyll的特性，给你梳理几个优先级最高的排查方向，按顺序来大概率能解决：

• 先盯紧帖子的文件名
  Jekyll对帖子文件名的要求特别死，必须是YYYY-MM-DD-帖子标题.md（或.markdown）的格式，差一个细节都不行：

  • 日期必须是4位年+2位月+2位日，比如2024-05-20不能偷懒写成2024-5-20
  • 标题部分尽量只用小写字母、数字、连字符，别加空格、冒号、感叹号这类特殊字符（非要用的话得转义，但尽量避免给自己找麻烦）
  • 最后确认后缀是.md或.markdown，别不小心存成.txt了

• 检查_posts子文件夹的命名
  虽然Jekyll允许在_posts下面建子文件夹，但有些坑要注意：

  • 子文件夹名不能有空格、特殊符号，尽量用小写字母加连字符，比如2024-q2-posts就很安全，Posts 2024这种带空格的容易被GitHub Pages的渲染引擎忽略
  • 顺带瞅一眼_config.yml里的exclude配置，有没有不小心把这个子文件夹加进去了（不过你说同目录其他帖子正常，这个概率很低，但确认下没坏处）

• 扒一扒前置元数据的隐藏问题
  你说格式和其他帖子一致，但可能存在肉眼看不到的小问题：

  • 用纯文本编辑器（比如VS Code）打开帖子，检查文件编码是不是UTF-8无BOM格式——BOM头会让Jekyll直接认不出前置元数据，跳过这个帖子的生成
  • 仔细核对YAML格式：冒号后面必须有空格！比如title: 我的技术帖是对的，title:我的技术帖就会出问题；还有引号、括号要配对，比如tags: ["Jekyll", "GitHub"]别写成tags: ["Jekyll, GitHub"]
  • 有没有手滑加了published: false？哪怕是误写，这个帖子也会被隐藏

• 本地跑Jekyll验证一下
  本地测试能快速区分是帖子本身的问题还是GitHub Pages的特殊限制：

  1. 先在本地装好Jekyll和依赖（如果还没装的话）
  2. 到项目根目录运行bundle exec jekyll serve
  3. 打开本地站点（默认是http://localhost:4000），看看这个帖子能不能正常显示
  • 如果本地也不显示：那肯定是帖子本身的问题，回到前面的排查点找细节
  • 如果本地显示正常：那大概率是GitHub Pages的缓存或者版本问题，试试重新推送代码，或者去仓库的「Settings」→「Pages」页面点一下“Save”，触发重新构建

• 强制刷新GitHub Pages的缓存
  有时候GitHub Pages的渲染缓存会抽风，哪怕是同批次推送的帖子，也可能有一个没更新：

  • 可以给这个帖子加个无关的小修改（比如多打个空格），然后重新commit推送，触发重新渲染
  • 或者进仓库的「Settings」→「Pages」，随便改个无关设置（比如把默认分支重新选一遍）再保存，强制GitHub重新构建整个站点

内容的提问来源于stack exchange，提问作者BornToDoStuff