GitHub Pages 网页一键部署

把一个静态站点从零推到 GitHub Pages，表面看是几步操作，实际却要在项目目录、构建配置、GitHub Actions 工作流、分支策略之间反复横跳。尤其是第一次部署的人，往往会卡在 gh-pages 分支权限、Workflow 语法或 DNS 传播上。这个技能要解决的，正是把「建项目 → 写页面 → 建仓库 → 推送部署」串成一条可重复执行的流程，让 Agent 能自主完成整个链路，而不是每一步都停下来等你确认。

核心工作流

技能内部按四个阶段推进：

• 项目初始化：init_project.sh 生成基础目录结构，为后续文件落位做好准备。
• 页面生成：默认采用单页优先策略，除非需求明确要求多页；代码要求完整、无占位符，可直接上线。
• 仓库配置：deploy_github_pages.sh 会初始化 git，通过 gh CLI 创建远程仓库，推送首次提交并触发部署。
• 自动发布：推送到 main 后，GitHub Actions 会把内容部署到 gh-pages 分支，站点最终出现在 https://<username>.github.io/<repo>/。

在实现层面，技能偏向无依赖方案：优先使用原生 HTML、CSS 与 JavaScript，通过 flexbox / grid 实现响应式布局，仅在需要框架时才引入 CDN。同时内置了 base-html、portfolio、landing 三类模板，分别覆盖最小可用骨架、简历作品集和落地页场景，避免从零手写重复结构。

适用边界与注意点

这套流程最适合纯静态、单页或少量页面的站点。它不会帮你配置 Vite 或 Next.js 这类构建工具链，也不会处理需要后端接口的动态站点。如果你需要在部署前进行 SSR 或 SPA 路由重写，仍需自行补充构建步骤。

部署依赖 gh CLI 已通过 gh auth status 验证。常见故障排查路径如下：

• 站点未更新：确认仓库 Settings → Pages 的来源设为 gh-pages 分支；
• 权限报错：检查 GitHub Actions 是否成功运行，以及仓库写入权限；
• 构建失败：进入 Actions 日志，核对 .github/workflows/deploy.yml 的语法与文件路径。

另外，DNS 首次解析可能需要 5–10 分钟，这段时间访问 404 属于正常现象，不必反复重试部署。