Github Pages切换推送仓库后自定义Workflow未生效，默认用Jekyll构建？

一、GitHub Pages 的默认构建动作 #

GitHub Pages 存在默认构建逻辑：

• 当仓库未配置自定义 GitHub Actions Workflow（即 .github/workflows/ 目录下无有效构建配置文件），且未关闭默认构建时，会自动启用 Jekyll 作为默认构建工具。
• 默认流程会读取仓库根目录内容，尝试用 Jekyll 生成静态资源，最终部署到指定的发布源分支（通常是 gh-pages）。

二、自定义 Workflow 不生效的核心原因 #

你的 Hugo 仓库中 gh-pages.yml 未生效，大概率是以下问题导致：

1. GitHub Pages 发布源配置错误 #

进入仓库的「Settings」→「Pages」→「Build and deployment」面板：

• 如果当前选择的是「Deploy from a branch」，GitHub 会直接忽略自定义 Workflow，强制走默认 Jekyll 构建流程。
• 必须将发布源切换为「GitHub Actions」，自定义的 gh-pages.yml 才会被触发执行。

2. gh-pages.yml 配置存在语法或逻辑错误 #

• 检查配置文件是否完整包含 Hugo 构建的必要步骤，示例配置如下：

  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
          with:
            submodules: true  # 若 Hugo 主题使用子模块需开启
            fetch-depth: 0
        - name: 安装 Hugo
          uses: peaceiris/actions-hugo@v2
          with:
            hugo-version: 'latest'
        - name: 构建静态文件
          run: hugo --minify
        - name: 部署到 GitHub Pages
          uses: peaceiris/actions-gh-pages@v4
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./public
  

• 前往仓库的「Actions」标签页查看 Workflow 运行日志，若配置有语法错误或依赖缺失，日志会明确标注失败原因。

3. 强制推送导致的文件丢失 #

你使用的 git push -F origin/main 是强制推送命令，可能在切换仓库推送时，误覆盖了 Hugo 仓库中的 .github/workflows/gh-pages.yml 文件。建议推送前先确认本地分支中该文件存在且内容正确，改用常规推送命令 git push origin main。

三、Emacs-Org Mode 仓库正常显示的原因 #

Org Mode 导出的是已生成好的静态 HTML 文件，Jekyll 默认构建流程会直接忽略这类已存在的静态资源，直接将其部署到 Pages，因此网站能正常显示。

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