GitHub Pages发布有两种方式：分支发布适合纯静态站，Actions工作流适合需构建的前端项目；配置需声明权限、执行构建、上传产物（如./dist）、自动部署，并注意路径与安全设置。
GitHub Actions 集成 GitHub Pages 发布，核心是用自动化工作流替代手动推 dist 文件到分支的过程。关键不在于“能不能”，而在于选对方式——分支发布适合简单静态站，Actions 工作流更适合需要构建（如 Vue/React/Astro）或想统一管控流程的项目。
明确发布源类型
GitHub Pages 支持两种发布源：
-
分支发布：直接指定一个分支（如
main或gh-pages）和文件夹（/或/docs），推代码即上线。无需 Actions，适合纯 HTML/CSS/JS 项目。 -
Actions 工作流发布：由 workflow 触发构建、上传产物、自动部署。适合需编译的前端项目（如
npm run build输出dist），也支持自定义生成器（Hugo、Astro 等）。
配置 Actions 工作流的关键步骤
一个标准 workflow（如 .github/workflows/deploy.yml）需包含四部分：
-
权限声明：必须设
pages: write才能部署，contents: read用于检出代码，id-token: write为 OIDC 安全实践（非强制但推荐）。 -
构建阶段：检出代码 → 安装 Node/pnpm → 安装依赖 → 运行
build命令（如pnpm run build）→ 产出dist/目录。 -
上传产物：用
actions/upload-pages-artifact@v3指定路径（如./dist），它会打包成符合 Pages 要求的压缩包。 -
自动部署：用
actions/deploy-pages@v2（或JamesIves/github-pages-deploy-action@v4）完成最终发布。后者更灵活，支持自定义分支名、提交信息等。
注意权限与安全设置
若 workflow 需推送代码（比如写回仓库或跨仓同步），需额外配置：
- 在仓库 Settings → Actions → General → Workflow permissions 中，将权限设为 Read and write permissions；
- 若要操作私有仓库或触发其他仓库 workflow，需创建 Personal Access Token（PAT），勾选
repo权限，并以secrets.BLOG_REPO_TOKEN形式存入目标仓库 Secrets； - 公开仓库的 Pages 站点默认对外可访问，即使源码库是私有的——敏感内容务必在构建前清理或排除。
调试常见问题
部署后页面空白或 404，多数源于路径配置错误：
- Vue/React 项目需确认
vue.config.js或craco.config.js中publicPath/homepage设置正确（如"https://username.github.io/repo-name/"）； - 检查 workflow 中
upload-pages-artifact的path是否指向实际构建输出目录（常见误写为./build但实际是./dist）； - 访问 Pages 设置页（Settings → Pages），确认 Source 显示为 GitHub Actions，而非 “Deploy from a branch”。
