Jekyll+Github Pages部署遇404错误及Markdown渲染异常求助

我之前在使用Github Pages搭配Dinky主题时，也碰到过几乎一模一样的问题——本地测试一切正常，部署后只要给Markdown文件加了Front Matter（哪怕是空白的）就会404，没加的反而能正常渲染。给你几个亲测有效的排查和解决方向：

1. 先查看Github Pages的构建日志 #

这是最直接的排查方式：

• 打开你的Github仓库，进入「Settings」→「Pages」
• 下拉到「Build and deployment」区域，点击「View deployment」查看构建日志
• 重点关注有没有Front Matter解析失败、页面生成错误的提示。我当时就是日志里显示空白Front Matter被Jekyll判定为无效，导致页面根本没生成。

2. 对齐本地和线上的Jekyll版本 #

Github Pages有固定的Jekyll版本（目前为3.9.3），如果本地用的版本和线上不一致，很容易出现本地正常、线上报错的情况：

• 本地运行 jekyll -v 查看当前版本
• 如果版本不对，建议在项目根目录创建Gemfile，加入以下内容锁定版本：

  source "https://rubygems.org"
  gem "github-pages", group: :jekyll_plugins
  

• 然后运行 bundle install 和 bundle exec jekyll serve 进行本地测试，确保和线上环境完全一致。

3. 检查文件存放路径和命名 #

Dinky主题对页面的存放位置有隐性要求：

• 尝试把加了Front Matter的Markdown文件放到_pages文件夹里（没有的话直接新建），有些主题默认只会处理_pages目录下带Front Matter的页面，否则会生成错误的路径导致404。
• 文件名尽量用英文小写，不要带空格或特殊字符，避免路径解析出现异常。

4. 规范Front Matter的格式 #

哪怕是空白的Front Matter，也要确保格式绝对正确：

• 必须是三个半角短横线，前后不能有多余的空格或字符，示例：

  ---
  ---
  

• 可以先尝试加一个明确的title字段测试，比如：

  ---
  title: 我的测试页面
  ---
  

  有时候空白Front Matter在某些Jekyll版本里会被判定为无效，导致页面无法生成。

5. 检查主题的Permalink配置 #

打开主题的_config.yml文件，查看permalink设置：

• 如果设置了permalink: /:title/，那带Front Matter的页面会生成类似/your-page-title/的路径，而不是/your-page.html，如果你访问的是.html后缀的地址就会404。
• 可以暂时把permalink改成/:title.html测试，看是否能正常访问。

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