HTML中GitHub Actions自动部署HTML页面到GitHub Pages的配置-html教程-PHP中文网

根本原因是github pages功能未启用或源分支/目录配置错误，而非actions未运行；必须手动在settings→pages中启用并设为deploy from branch→main→(root)，否则即使index.html存在且actions成功也会404。

html中github actions自动部署html页面到github pages的配置

为什么 push 到 `main` 分支后 GitHub Pages 仍 404？

根本原因不是 Actions 没跑，而是 GitHub Pages 根本没被“启用”或“指向正确位置”。Actions 不会自动帮你打开 Pages 功能，也不会替你选分支——它只负责推文件，读取逻辑由 Pages 服务自己控制。

用户页（仓库名是 username.github.io）必须从 main 分支根目录提供文件，且 Settings → Pages → Source 必须手动设为 Deploy from a branch + main + (root)
如果 Settings 里 Source 显示 “None” 或灰色不可选，说明 Pages 功能未激活，Actions 再成功也没用
即使仓库里有 index.html，若 Pages 设置里选的是 gh-pages 分支，而你只往 main 推，页面照样 404
保存 Settings 后要等约 30 秒，再刷新页面，不要立刻点链接测试

`actions/deploy-pages@v4` 和 `peaceiris/actions-gh-pages@v3` 怎么选？

二者都能部署，但适用场景不同，选错会导致权限失败或跨仓库推送异常。

actions/deploy-pages@v4：轻量、官方维护、只支持部署到当前仓库的 Pages；不需要额外密钥，靠 permissions: pages: write 自动获取 token；适合纯 HTML 项目直接推 main 或生成 gh-pages 分支
peaceiris/actions-gh-pages@v3：支持跨仓库部署（比如从 src-repo 推到 username.github.io），但必须配 secrets.ACTIONS_DEPLOY_KEY；若只用于本仓，反而多一层密钥管理负担
如果你的 HTML 就在根目录（index.html、style.css 都在 /），优先用 actions/deploy-pages@v4，配置更少、出错率更低

`permissions` 三行缺一不可，尤其 `contents: write`

GitHub 在 2023 年底收紧了 Actions 权限模型，pages: write 单独存在并不够——它只允许写 Pages 构建产物，但创建 gh-pages 分支（或更新 main）需要 contents: write。

Lovefromio Github

使用 `gh` CLI 与 GitHub 交互。通过`gh issue`、`gh pr`、`gh run` 和 `gh api` 管理 issue、PR、CI 运行以及高级查询。

下载

漏掉 contents: write → Actions 日志报错：Permission denied: cannot create/update branch
漏掉 id-token: write → 若后续要用 OIDC 访问其他服务（如 AWS），会卡在认证环节
三项必须同时声明，顺序无关，但不能省略任何一项

最简可用的 `.github/workflows/deploy.yml` 长什么样？

不构建、不装 Node、不跑 npm build，就是把现有 HTML 文件原样部署过去。这是纯静态页的黄金配置。

name: Deploy HTML to Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4