根本原因是GitHub Pages功能未启用或源分支/目录配置错误，而非Actions未运行；必须手动在Settings→Pages中启用并设为Deploy from branch→main→(root)，否则即使index.html存在且Actions成功也会404。
为什么 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。
- 漏掉
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- 确认你的仓库名是
username.github.io，否则 Pages 不生效 - 确保
index.html确实在仓库根目录，而不是src/或dist/下 - 不要在 workflow 中加
run: npm install或run: yarn build——那是构建型项目的逻辑，和纯 HTML 冲突
最容易被忽略的一点：Actions 只管“推”，不管“读”。Pages 能不能显示，最终取决于 Settings → Pages 里的那个手动开关是否打开、分支是否选对、路径是否为 root——这个动作没有任何自动化能替代。
