Jekyll文章已提交但不显示？GitHub Pages构建排查清单

先给结论：GitHub 仓库里能看到 commit，不等于 Jekyll 已经成功生成并部署了网站。新文章不显示时，应先看 GitHub Pages 的构建记录，再按文件名、Front Matter 日期、YAML、编码、插件和发布源逐层排查。不要先反复修改标题或日期。

本文保留原页面的技术问题入口，但已按当前 Jekyll 与 GitHub Pages 文档重写。它适合维护个人博客、企业文档站或项目官网的开发者；如果你的目标是让企业内容更容易被搜索引擎理解，还应结合 外贸网站 SEO 基础框架检查抓取、内容和业务追踪。

一、先判断：是文章没有生成，还是网站没有部署

把问题分成三层，能避免把不同故障混在一起：

1. 源文件层：文件是否放在正确的 _posts 目录，文件名、Front Matter 和编码是否有效。
2. 构建层：Jekyll 是否成功解析了 YAML、日期、Liquid、Markdown、主题和插件。
3. 部署与访问层：构建是否已经发布到正确的 branch 或 GitHub Actions 环境，访问的 URL 是否是正确的站点地址。

如果 Actions 或 Pages 构建失败，网页不会因为 commit 成功而自动出现；如果构建成功但页面仍旧不显示，再检查发布源、路径、永久链接和浏览器缓存。GitHub 官方建议从构建错误信息和 Actions workflow 运行记录开始，而不是只看仓库的提交历史。

二、第一轮检查：文件名与 Front Matter

1. _posts 文件名要符合 Jekyll 约定

Jekyll 官方文档给出的文章文件格式是：

YEAR-MONTH-DAY-title.MARKUP

例如：

2026-07-30-github-pages-jekyll-debug.md
2026-07-30-企业官网上线检查.markdown

年份、月份和日期应使用四位、两位、两位数字；扩展名要对应你实际使用的 Markdown 或 HTML 处理器。不要把草稿随意放在 _posts 后期待它按普通文章发布：Jekyll 的草稿通常放在 _drafts，预览时需要使用 --drafts。

2. 文件必须从合法的 YAML Front Matter 开始

Front Matter 必须是文件的第一部分，并位于两行三短横线之间。最小示例：

---
layout: post
title: "GitHub Pages 上的 Jekyll 排错"
date: 2026-07-30 10:00:00 +0800
categories: [blog]
tags: [jekyll, github-pages]
---

文章正文从这里开始。

常见错误包括：三短横线前有隐藏字符、YAML 使用 Tab、冒号后没有空格、字符串中的冒号没有引号、缩进不一致，或日期不是实际存在的日历日期。GitHub 的构建排错文档还特别列出无效日期、无效 YAML 和非 UTF-8 文件等错误类型。

3. 不要用“改成前一天”掩盖时区问题

Jekyll 文章日期可能来自文件名，也可以由 Front Matter 中的 date 覆盖。若文章的时间带有时区，应使用类似 2026-07-30 10:00:00 +0800 的明确格式。未来日期的文章默认不会被发布，除非构建配置显式允许 future posts；因此应检查实际日期、站点时区和 future 配置，而不是把每篇文章机械改成前一天。

可以先做一个最小测试：复制一篇确定能显示的文章，只改文件名、标题和正文。如果最小文件能出现，问题通常在原文章的 YAML、Liquid、插件或正文内容，而不是 GitHub 仓库本身。

三、第二轮检查：GitHub Pages 构建记录

进入仓库的 Actions，找到最近一次 Pages 或 Jekyll workflow：

1. 先确认 workflow 是否被触发，以及它使用的是你刚刚提交的 commit。
2. 展开失败的 job，记录第一条具体错误，不要只记住页面上的 “build failed”。
3. 修复后重新 push；如果站点使用自定义 GitHub Actions workflow，则按 workflow 的触发方式重新运行。
4. 同时检查仓库设置中的 Pages 发布源，确认 branch、目录或 Actions 选择没有改变。

GitHub 官方当前建议用 GitHub Actions 作为 Pages 的部署方式之一；无论你采用 branch 还是 Actions，都必须以实际构建日志确认发布链路。GitHub 页面上的 commit 记录只能证明代码进入仓库，不能证明构建产物已经部署。

高频构建错误与处理方向

四、第三轮检查：本地复现与最小回滚

如果日志信息不够清楚，先在本地用项目自己的 Ruby、Bundler 和依赖版本复现。GitHub 官方也建议在本地测试 GitHub Pages 站点，以减少“本地能跑、线上不能跑”的环境差异。

1. 保存当前分支和最近一次能正常发布的 commit。
2. 在项目目录安装并使用项目声明的依赖，不要随意升级主题或插件。
3. 执行项目既有的 Jekyll build/serve 命令，查看最早出现的错误文件和行号。
4. 把新增文章临时移出 _posts；如果站点恢复，再逐步恢复正文、图片、Liquid 和 Front Matter，定位触发点。
5. 修复后先用一个小 commit 验证构建，再合并其他内容。

如果站点由外部 CI、主题仓库或自定义 Actions 发布，还要检查 workflow 权限、依赖锁定、构建目录和发布 artifact。不要把“邮件没有报错”当作成功证据；应以 Actions 状态、Pages 环境和公开 URL 三者一致为准。

五、编码、中文和资源路径的注意事项

• 文章、YAML 和模板尽量统一使用 UTF-8。Jekyll 文档提醒 Windows 环境尤其要注意编码和 BOM；GitHub 也把非 UTF-8 文件列为常见构建问题。
• 中文文件名并非自动等于构建失败，但排查时可先用简单英文文件名确认是否为路径或编码问题。
• 图片、CSS、JavaScript 和下载文件的路径应按站点的 baseurl、域名和发布目录计算。资源加载失败可能让页面看起来“不完整”，但它与文章没有生成是两个问题。
• 如果正文依赖 JavaScript 才显示，先确认原始 HTML 中是否存在主要内容；不要把客户端渲染失败误判为 Jekyll 没有生成文章。

六、发布前的五分钟验收清单

1. 文件位于正确的 _posts 路径，文件名符合 YYYY-MM-DD-title.ext。
2. Front Matter 位于第一行，YAML 可解析，日期真实且时区明确。
3. 文章没有被标记为 published: false，也不是未用 --drafts 预览的草稿。
4. GitHub Actions 或 Pages 构建成功，日志没有被忽略的 warning/error。
5. 公开 URL 返回正确页面；标题、正文、图片和站内链接均可用。
6. 如果是企业内容，再用 SEO 网站问题排查清单核对索引、重复 URL、页面体验和业务追踪，而不是只看页面能否打开。

结论：先看构建证据，再改文章

Jekyll 新文章不显示，最有效的顺序通常是：Actions/Pages 构建记录 → 文件名与 Front Matter → 日期和时区 → YAML、编码、Liquid 与插件 → 发布源和公开 URL。原文把“文件名必须用连字符”“中国时区必然导致文章不渲染”等经验写成了绝对规则，已改为以当前官方文档和实际构建日志为准。不同项目的主题、插件、发布源和版本可能不同，不能保证按某一个步骤就一定恢复。

官方资料与下一步

• Jekyll：Posts：文章目录、文件名、Front Matter 和草稿。
• Jekyll：Front Matter：日期、编码和预定义变量。
• Jekyll：Configuration Options：时区与构建选项。
• GitHub Docs：Troubleshooting Jekyll build errors：构建错误分类与修复方向。
• GitHub Docs：Testing your GitHub Pages site locally：本地复现方法。

资料核查日期：2026年7月30日。本文是技术排错资料，不代表 AdTodo 负责你的 GitHub、Ruby、Jekyll、主题或 CI/CD 环境，也不保证构建、收录或排名结果。