GitHub Pages 部署纯 HTML 需手动配置源分支（用户页用 main 分支根目录），并设置正确 permissions 与 environment；若跨仓库部署则需 PERSONAL_TOKEN 和 peaceiris/actions-gh-pages@v3。
直接部署纯 HTML 页面到 GitHub Pages 完全不需要构建步骤，但 GitHub Actions 默认不会自动识别静态文件部署逻辑——你得明确告诉它“把哪些文件推到哪个分支”，否则 pages 服务压根收不到内容。
为什么 push 到 main 分支不生效？
GitHub Pages 默认只从特定分支+路径读取内容：
• 用户页（username.github.io）必须从 main（或 master）分支的根目录提供文件；
• 项目页则需从 gh-pages 分支或 docs/ 目录。
如果你只是把 index.html 提交到 main，却没启用 Pages 设置，或者启用了但源设成了 gh-pages 分支，那页面就永远 404。
常见错误现象：
• Settings → Pages → Source 显示 “None” 或灰色不可选状态
• 手动访问 https://username.github.io 返回 404，但仓库里明明有 index.html
• Actions 日志显示成功，但 Pages URL 一直不更新
- 确认仓库名是
username.github.io（不是my-blog等其他名） - 进入
Settings → Pages，手动将 Source 设为Deploy from a branch，Branch 选main，Folder 选(root) - 保存后等 30 秒再刷新，不要跳过这步——Actions 不会帮你点这个按钮
最简可用的 deploy.yml 怎么写？
不需要 Node.js、不装依赖、不跑 build，只要把文件“原样推过去”。关键是用 actions/checkout@v4 拉代码，再用 peaceiris/actions-gh-pages@v3 或 actions/deploy-pages@v4 推到目标分支。后者更轻量，但只支持部署到当前仓库的 Pages；前者可指定任意目标仓库（比如你想从 src-repo 自动推到 username.github.io）。
立即学习“前端免费学习笔记（深入）”；
若你的 HTML 就在仓库根目录（即 index.html、style.css 等都在 / 下），用这个最小配置：
监控一个或多个 GitCode 仓库的 PR，通过 OpenClaw Gateway 自动执行 AI 审查，发布 PR 评论，并发送钉钉和企业微信通知。
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
注意：
• permissions 三行缺一不可，尤其 contents: write 是为了允许创建 gh-pages 分支（即使你设的是 main 源，底层仍可能走此分支）
• environment 块必须存在且带 url 字段，否则 deploy-pages 会报错 page_url is required
想从 A 仓库自动推到 B 仓库（如 hexo-blog → wangwen135.github.io）？
这时不能用 actions/deploy-pages@v4，它只认当前仓库。必须换回 peaceiris/actions-gh-pages@v3，并手动指定目标仓库和 token。
- 在目标仓库（
wangwen135.github.io）的Settings → Secrets and variables → Actions中，新建 secret，名字比如叫PERSONAL_TOKEN，值填一个带repo权限的 Personal Access Token（不是GITHUB_TOKEN，后者无跨仓库写权限） - 在源仓库（
hexo-blog）的工作流中，with块要显式写清github_token、publish_branch和publish_dir -
publish_dir必须是构建后的真实路径，比如 Hexo 默认是./public；如果是纯 HTML 项目，且文件就在根目录，就填.（一个点）
示例片段：
- name: Deploy to wangwen135.github.io
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.PERSONAL_TOKEN }}
publish_branch: main
publish_dir: ./public
external_repository: wangwen135/wangwen135.github.io
容易被忽略的细节
GitHub Pages 的缓存行为很隐蔽：它不强制刷新 CDN，有时改了 index.html，浏览器 F5 还是旧版。这不是 Actions 的锅，而是 Pages 本身默认开了强缓存（Cache-Control: public, max-age=600）。如果发现页面没更新，先试：
• 清浏览器缓存 + 强制刷新（Ctrl+Shift+R 或 Cmd+Shift+R）
• 访问带时间戳的 URL，比如 https://username.github.io/?t=123 看是否最新
• 检查 Actions 日志末尾有没有 “Page built successfully”，而不是只看 “Completed”
另外，actions/deploy-pages@v4 内部会自动生成 gh-pages 分支，但该分支不可见于仓库的 Branches 列表（属于 GitHub 托管的 Pages 分支），别白费力气去翻。
