企业官网建设流程全解析

al-folio 在 GitHub Actions 中部署失败但没有明确报错怎么排查？

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio

用 al-folio 模板建站后，push 到main分支会自动触发 GitHub Actions 的部署流程（deploy.yml），把构建产物发到 GitHub Pages。实际使用中常见的故障是：Actions 标签页显示失败，但日志翻不到明确的报错行；或者构建看起来"静默"结束，网站却一直没有更新。这篇文章基于仓库自带的 docs/TROUBLESHOOTING.md、docs/FAQ.md 和 docs/INSTALL.md，给出一条从"定位真实报错"到"确认部署恢复"的排查路径，适用于以 GitHub Pages 为发布目标、通过deploy.yml自动部署的站点。

先弄清部署链路，知道失败可能出在哪一段

deploy.yml的执行链路（见 .github/workflows/deploy.yml）：

1. 触发条件：push 到master/main分支且文件路径匹配（assets/**、**.md、**.yml、Gemfile、Gemfile.lock等），或通过workflow_dispatch手动触发；
2. 构建环境：ubuntu-latest，Ruby3.3.5、Python3.13、Node20，执行npm ci后运行bundle exec jekyll build（JEKYLL_ENV=production），再用purgecss -c purgecss.config.js清理无用 CSS；
3. 部署：把_site目录推送到gh-pages分支，由 GitHub Pages 发布。

排查时注意两点：部署步骤带if: github.event_name != 'pull_request'，所以 PR 触发的运行只构建不部署，PR 里红了不代表 main 分支部署不了；push 到gh-pages分支本身不会触发部署。

第一步：把"不明确"的报错变成明确报错

TROUBLESHOOTING.md 对"GitHub Actions 部署失败"给出的第一步是打开仓库的Actions标签页，逐条查看 error messages，找到红色的具体 step。

如果 Actions 日志里只提示 YAML 相关错误甚至构建静默（文档原文场景是 "GitHub Actions fails with YAML error, or build is silent"），文档给出的办法是本地复现，拿到精确报错行：

bundle exec jekyll build

同时在_config.yml和各 Markdown front matter 里检查未加引号的特殊字符（:,&,#）。文档给出的错误示例（文档示例，不是固定预期输出）：

# ❌ Wrong: Unquoted colons or ampersands title: My Site: Research & Teaching # ✅ Correct: Quote special characters title: "My Site: Research & Teaching"

缩进不一致也是同类问题，例如列表项前多一个空格会导致 YAML 解析异常；本地bundle exec jekyll build会指出具体错误行。

第二步：核对最容易漏掉的触发与权限条件

部署"失败"有时不是构建错，而是 workflow 根本没拿到执行条件。按 QUICKSTART.md Step 2 和 INSTALL.md 的 "Enabling automatic deployment"，逐项核对：

1. Workflow 权限：Settings → Actions → General → Workflow permissions必须选Read and write permissions。deploy.yml声明了permissions: contents: write，没有写权限时部署步骤无法推送gh-pages分支。
2. 分支：确认改动是提交到main（或master），而不是gh-pages。如果站点代码保留在其他分支，需要打开该分支上的.github/workflows/deploy.yml，把on→push→branches和on→pull_request→branches改成你实际使用的分支。
3. Pages 发布源：Settings → Pages → Source设为Deploy from a branch，分支选gh-pages（不是main）。发布源选错时的典型现象是本地构建正常、CI 报Unknown tag 'toc'，核对为gh-pages后等待约 5 分钟再看 Actions。
4. 仓库名：个人站点要求仓库名是<你的用户名>.github.io；项目站点则要求_config.yml中baseurl为/<仓库名>/。

第三步：检查_config.yml的 url 与 baseurl

url/baseurl配置错误在文档中既归在部署失败原因里，也是部署后"CSS 和 JS 不加载、链接全断"的最常见原因。按站点类型设置：

# 个人/组织站点（username.github.io） url: https://<你的用户名>.github.io baseurl: # 必须为空，不要删除这一行

# 项目站点（username.github.io/repo-name） url: https://<你的用户名>.github.io baseurl: /<仓库名>/ # 必须与仓库名一致

其中<你的用户名>和<仓库名>需替换为你自己的值。改完后提交并 push，重新触发部署。

第四步：按 Actions 里的报错文本对号入座

如果 Actions 日志中出现了明确的错误文本，FAQ.md 对以下几种常见报错给出了对应解法：

升级 CLI 的完整顺序在 INSTALL.md 的 "Recommended workflow (v1.x)" 中为：bundle update→bundle exec al-folio upgrade audit→bundle exec al-folio upgrade apply --safe→bundle exec al-folio upgrade report；报告写入al-folio-upgrade-report.md，Blocking项必须在升级完成前解决。

重新触发部署并确认恢复

原因修复后，按 TROUBLESHOOTING.md 的做法"Commit and push a small change to trigger redeployment"——提交一个很小的改动并 push 即可重新触发部署。不想改文件时，也可以用手动入口：Actions 标签页 → 左侧 "Deploy" → "Run workflow"。

判断部署恢复成功的依据（均来自文档给出的预期）：

• "Deploy site" workflow 显示绿色对勾，文档给出的参考时长约 4 分钟；
• 仓库中出现新的gh-pages分支（文档明确提醒：不要动这个分支）；
• "pages-build-deployment" workflow 完成，参考时长约 45 秒；
• 访问https://<你的用户名>.github.io（项目站点为https://<你的用户名>.github.io/<仓库名>/）能正常打开。

如果 Actions 全部通过但页面样式错乱（CSS/JS 未加载），TROUBLESHOOTING.md 的 "Site looks broken after deployment" 清单是：确认baseurl没有被误删、强制刷新浏览器缓存（ChromeCtrl+Shift+R/Cmd+Shift+R，FirefoxCtrl+F5）、等待约 5 分钟让 GitHub Pages 更新、再确认 Actions 已成功。自定义域名在每次部署后被清空的情况则与本文的构建失败无关，解法是在仓库根目录提交CNAME文件。

范围说明

本文只覆盖 GitHub Pages 自动部署链路（deploy.yml）的失败排查。仓库同时提供 Netlify 部署方式（INSTALL.md 中有 Build command 与环境变量配置）和非 GitHub Pages 服务器的bundle exec jekyll build构建方式，属于独立的部署方案，不在本条排查路径内。

主要参考文档：docs/TROUBLESHOOTING.md、docs/FAQ.md、docs/INSTALL.md、docs/QUICKSTART.md、.github/workflows/deploy.yml。

【免费下载链接】al-folioA beautiful, simple, clean, and responsive Jekyll theme for academics项目地址: https://gitcode.com/GitHub_Trending/al/al-folio