github-pages

GitHub Pages 技能

关于部署、配置和管理 GitHub Pages 站点的完整指南。

快速参考

站点类型	仓库名称	URL 格式
用户／组织站点	<username>.github.io	https://<username>.github.io
项目站点	任意仓库名称	https://<username>.github.io/<repo>

可用性：

• 公共仓库：GitHub Free（所有套餐）
• 私有仓库：GitHub Pro、Team、Enterprise

---

工作流路由

执行工作流时，直接输出此通知：

Running the **WorkflowName** workflow from the **GithubPages** skill...

工作流	触发条件	文件
QuickStart	“setup github pages”、“create pages site”	workflows/QuickStart.md
CustomDomain	“add custom domain”、“configure domain”	workflows/CustomDomain.md
JekyllSetup	“setup jekyll”、“add jekyll theme”	workflows/JekyllSetup.md
ActionsWorkflow	“custom build”、“github actions for pages”	workflows/ActionsWorkflow.md
Troubleshoot	“pages not working”、“fix github pages”	workflows/Troubleshoot.md
Deploy	“deploy to github pages”、“publish site”	workflows/Deploy.md

---

示例

示例 1：创建新的 GitHub Pages 站点

User: "Setup GitHub Pages for my project"
→ Invokes QuickStart workflow
→ Checks if user/org or project site
→ Configures publishing source (branch or Actions)
→ Creates initial content structure
→ Verifies deployment

示例 2：添加自定义域名

User: "Add my domain example.com to GitHub Pages"
→ Invokes CustomDomain workflow
→ Determines domain type (apex vs subdomain)
→ Provides DNS configuration instructions
→ Adds CNAME file or configures via Settings
→ Enables HTTPS enforcement

示例 3：设置 Jekyll 主题

User: "Add a theme to my GitHub Pages site"
→ Invokes JekyllSetup workflow
→ Lists available supported themes
→ Configures _config.yml
→ Sets up custom CSS/layouts if needed

示例 4：使用自定义构建进行部署

User: "Deploy my Next.js site to GitHub Pages"
→ Invokes ActionsWorkflow workflow
→ Creates custom GitHub Actions workflow
→ Configures build process
→ Sets up artifact deployment

---

站点类型

用户／组织站点

要求：

• 仓库名称必须为 <username>.github.io
• 每个帐户只能有一个
• 从默认分支发布

设置：

# Create repository named exactly: username.github.io
# Enable Pages in Settings > Pages
# Select source branch

项目站点

要求：

• 可以使用任意仓库
• 允许创建多个项目站点
• URL 中包含仓库名称

设置：

# Any repository works
# Enable Pages in Settings > Pages
# Choose: branch (root or /docs) OR GitHub Actions

---

发布源

选项 1：从分支部署

适用场景： Jekyll 站点、简单的静态站点

配置：

1. 转到 Settings > Pages
2. 选择“Deploy from a branch”
3. 选择分支（main、gh-pages 等）
4. 选择文件夹：/（根目录）或 /docs

行为：

• 推送到分支会触发自动构建
• 默认情况下，Jekyll 会处理 Markdown
• 自定义域名会自动创建 CNAME 文件

选项 2：GitHub Actions 工作流

适用场景： 自定义构建、非 Jekyll 生成器

配置：

1. 转到 Settings > Pages
2. 选择“GitHub Actions”
3. 在 .github/workflows/ 中创建工作流文件

行为：

• 可全面控制构建流程
• 适用于 Hugo、Gatsby、Next.js 等
• 上传并部署构建产物

---

Jekyll 集成

自动启用的插件

这些插件在 GitHub Pages 上会自动运行：

插件	用途
jekyll-coffeescript	CoffeeScript 支持
jekyll-default-layout	自动布局
jekyll-gist	嵌入 GitHub Gist
jekyll-github-metadata	仓库元数据
jekyll-optional-front-matter	可选 YAML front matter
jekyll-paginate	分页
jekyll-readme-index	将 README 用作索引
jekyll-titles-from-headings	自动生成标题
jekyll-relative-links	转换相对链接

支持的主题

无需额外配置即可使用：

• Architect
• Cayman
• Dinky
• Hacker
• Leap day
• Merlot
• Midnight
• Minima
• Minimal
• Modernist
• Slate
• Tactile
• Time machine

在 _config.yml 中使用：

theme: jekyll-theme-minimal
title: My Site
description: Site description

远程主题

使用 GitHub 上的任意 Jekyll 主题：

remote_theme: owner/repo-name

---

自定义域名

域名类型

类型	示例	DNS 记录
裸域名	example.com	A 或 ALIAS
WWW 子域名	www.example.com	CNAME
自定义子域名	blog.example.com	CNAME

DNS 配置

裸域名（A 记录）：

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

裸域名（AAAA 记录 - IPv6）：

2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

子域名（CNAME 记录）：

www.example.com → username.github.io
blog.example.com → username.github.io

验证命令

# Check A records
dig example.com +noall +answer -t A

# Check AAAA records
dig example.com +noall +answer -t AAAA

# Check CNAME records
dig www.example.com +nostats +nocomments +nocmd

---

使用限制

资源	限制
仓库大小	1 GB（建议值）
已发布网站大小	1 GB（上限）
带宽	100 GB/月（软限制）
构建次数	10 次/小时（软限制，仅限分支）
部署超时	10 分钟

限制：

• 不支持服务端语言（PHP、Python、Ruby）
• 不得用于商业交易或电子商务
• 必须遵守 GitHub 服务条款

---

安全最佳实践

1. 验证自定义域名 — 防止域名劫持攻击
2. 避免使用通配符 DNS — *.example.com 会带来安全风险
3. 启用 HTTPS — 证书配置完成后，始终强制使用 HTTPS
4. 不要暴露机密信息 — 即使仓库是私有的，网站仍可公开访问
5. 及时更新 DNS — 如果停用网站，请更新或删除 DNS 记录

---

常见问题与解决方案

问题	解决方案
网站未发布	检查分支/文件夹设置，确认入口文件存在
404 错误	确保根目录下有 index.html、index.md 或 README.md
自定义域名无法使用	等待 24 小时以完成 DNS 传播，并使用 dig 验证记录
HTTPS 不可用	DNS 验证完成后，最多等待 1 小时
混合内容警告	将所有资源中的 http:// 改为 https://
构建失败	在 Actions 选项卡中查看错误日志

---

文件参考

主题	参考文件
DNS 配置	references/DnsConfiguration.md
Jekyll 配置	references/JekyllConfiguration.md
Actions 工作流	references/ActionsWorkflows.md
故障排除指南	references/Troubleshooting.md
最佳实践	references/BestPractices.md

---

脚本

脚本	用途
scripts/verify-dns.sh	验证自定义域名的 DNS 配置
scripts/check-site-status.sh	检查 GitHub Pages 网站是否在线

---

外部文档

• GitHub Pages 快速入门
• 自定义域名配置
• Jekyll 文档
• 适用于 Pages 的 GitHub Actions

---

注意事项

• GitHub Pages 会在 CDN 层缓存约 10 分钟 — 最近推送的更改可能不会立即显示；可通过 ?nocache=$(date +%s) 查询参数检查。
• 自定义域名需要 CNAME 记录以及仓库中的 CNAME 文件 — 缺少其中任一项都会导致 HTTPS 证书生成失败，而且通常不会显示提示。
• Jekyll 插件必须在 GitHub 的白名单中 — 仅在 Gemfile 中声明的插件在某些旧配置中会静默导致构建失败。
• 分支与文件夹来源：gh-pages 分支、main 分支上的 /docs 文件夹，或 main 分支上的 / — 切换来源后，必须显式重新部署才能生效。
• HTTPS 强制执行针对每个 Page 属性单独设置 — 在设置界面中切换后，不会立即撤销仅限 HTTP 的访问；旧缓存会继续提供 HTTP 内容，直到过期。
• 构建错误日志位于 Actions 界面中，而不在 Pages 设置中 — 初次使用的用户可能会在错误的位置排查数小时。