Web Deploy GitHub Pages

概述

该技能支持自主创建并部署静态网站至 GitHub Pages。它涵盖从项目结构初始化到通过 GitHub Actions 自动部署的完整流程，专为单页应用、个人作品集和落地页（landing page）优化。

核心工作流

1. 项目初始化

创建项目结构：

bash scripts/init_project.sh 

生成以下目录结构：

project-name/
├── index.html
├── styles.css
├── script.js
├── README.md
└── .github/
    └── workflows/
        └── deploy.yml

2. 开发

按以下原则构建网站：

• 优先单页设计：默认采用单页布局，仅在明确需要多页时例外
• 自主生成：输出完整、可直接上线的生产就绪代码，不包含占位符
• 现代设计：使用现代 CSS（Flexbox、Grid）、响应式布局与简洁美观的视觉风格
• 零依赖：尽可能使用纯 HTML/CSS/JS；如需框架，则通过 CDN 引入

可基于 assets/templates/ 中的模板快速启动：

• base-html/ —— 最小化 HTML5 脚手架
• portfolio/ —— 含多个标准区块（如 Hero、About、Skills 等）的作品集/CV 模板
• landing/ —— 含 Hero 区域与行动号召（CTA）的落地页模板

3. GitHub 仓库配置

bash scripts/deploy_github_pages.sh  

该脚本执行以下操作：

1. 初始化本地 Git 仓库
2. 通过 GitHub CLI 创建远程 GitHub 仓库
3. 配置 GitHub Pages 设置
4. 推送初始提交
5. 触发首次部署

4. 部署

每次向 main 分支推送代码时，GitHub Actions 将自动完成部署。该工作流包括：

• 检出源代码
• 部署至 gh-pages 分支
• 使网站在 https://.github.io// 地址上线

架构规范

HTML 结构

• 使用语义化的 HTML5 元素
• 添加 SEO 和社交分享所需的 meta 标签
• 配置响应式 viewport
• 包含 favicon 及各尺寸图标

CSS 设计

• 移动优先的响应式设计
• 使用 CSS 变量实现主题定制
• 采用 Flexbox/Grid 构建布局
• 启用平滑过渡与动画效果
• 在适用场景下提供暗色模式支持

JavaScript

• 优先使用原生 JavaScript（Vanilla JS）
• 遵循渐进增强（Progressive Enhancement）原则
• 合理使用事件委托（Event Delegation）
• 确保无控制台报错（No console errors）

性能

• 对图片资源进行优化
• 生产环境使用压缩后的静态资源（minified assets）
• 在合适位置启用懒加载（lazy loading）
• 保障首屏快速加载

快速示例

示例 1：作品集 CV 网站

用户请求：“为我创建一个作品集 CV 网站”

操作步骤：

1. 运行 init_project.sh portfolio-cv
2. 以 assets/templates/portfolio/ 为基准模板
3. 生成含 Hero、About、Skills、Projects、Contact 等完整区块的 HTML
4. 运行 deploy_github_pages.sh portfolio-cv username 完成部署

示例 2：应用落地页

用户请求：“为我的应用制作一个落地页”

操作步骤：

1. 运行 init_project.sh app-landing
2. 以 assets/templates/landing/ 为基准模板
3. 生成含 Hero、Features、Pricing、CTA 等关键区块的页面
4. 运行 deploy_github_pages.sh app-landing username 完成部署

故障排查

GitHub Pages 未成功部署

• 检查仓库 Settings → Pages → Source 是否设置为 gh-pages 分支
• 确认 GitHub Actions 工作流已成功运行
• 检查 DNS 传播状态（通常需 5–10 分钟）

权限错误

• 确保已通过 GitHub CLI 登录：gh auth status
• 检查 GitHub 上当前用户的仓库访问权限

构建失败

• 查阅仓库中 GitHub Actions 的日志输出
• 验证 .github/workflows/deploy.yml 文件语法是否正确
• 检查文件路径及引用是否准确无误

资源

scripts/

• init_project.sh —— 初始化项目结构
• deploy_github_pages.sh —— 部署至 GitHub Pages

references/

• workflow.md —— 详细工作流说明文档
• design-patterns.md —— 设计最佳实践指南

assets/

• templates/base-html/ —— 最小化 HTML5 脚手架
• templates/portfolio/ —— 作品集/CV 模板
• templates/landing/ —— 落地页模板
• .github/workflows/deploy.yml —— GitHub Actions 工作流模板