GitHub Pages 部署配置指南

📋 部署前检查清单

  • GitHub Actions 工作流已创建
  • CNAME 文件已配置
  • _config.yml 已更新域名设置
  • Gemfile 已配置为 GitHub Pages 兼容

🚀 部署步骤

1. 推送代码到 GitHub

git add .
git commit -m "Configure for GitHub Pages deployment with custom domain"
git remote add origin https://github.com/agenticeconomics/AgenticEconomicsWeb.git
git push -u origin main

2. 在 GitHub 仓库中启用 GitHub Pages

  1. 访问仓库设置页面：https://github.com/agenticeconomics/AgenticEconomicsWeb/settings
  2. 滚动到 “Pages” 部分
  3. 在 “Source” 下选择 “GitHub Actions”
  4. 保存设置

3. 配置自定义域名

在 GitHub 中：

  1. 在 Pages 设置中的 “Custom domain” 字段输入：www.agenticeconomics.org
  2. 勾选 “Enforce HTTPS”
  3. 等待 DNS 检查完成

在您的域名提供商处：

配置以下 DNS 记录：

类型    名称                 值
CNAME   www                  agenticeconomics.github.io
A       @                    185.199.108.153
A       @                    185.199.109.153
A       @                    185.199.110.153
A       @                    185.199.111.153

或者，如果您的 DNS 提供商支持 ALIAS/ANAME 记录：

ALIAS/ANAME  @              agenticeconomics.github.io
CNAME        www            agenticeconomics.github.io

⚙️ GitHub Actions 工作流说明

我们创建的工作流文件 .github/workflows/jekyll-gh-pages.yml 包含：

触发条件

  • 推送到 main 分支时自动运行
  • 可手动触发（workflow_dispatch）

构建步骤

  1. Checkout: 检出代码
  2. Setup Ruby: 安装 Ruby 3.1 和依赖
  3. Setup Pages: 配置 GitHub Pages 环境
  4. Build: 使用 Jekyll 构建网站
  5. Upload: 上传构建产物

部署步骤

  1. Deploy: 部署到 GitHub Pages

🔧 配置文件说明

CNAME 文件

www.agenticeconomics.org

这告诉 GitHub Pages 将网站与您的自定义域名关联。

_config.yml 关键配置

url: "https://www.agenticeconomics.org"
baseurl: ""
github_username: agenticeconomics
repository: agenticeconomics/AgenticEconomicsWeb

Gemfile 配置

使用 github-pages gem 确保与 GitHub Pages 环境完全兼容：

gem "github-pages", "~> 231", group: :jekyll_plugins

📊 监控部署

检查部署状态

  1. 访问仓库的 “Actions” 标签页
  2. 查看最新的工作流运行状态
  3. 如有错误，点击查看详细日志

验证网站

部署完成后（通常 5-10 分钟），访问：

  • https://www.agenticeconomics.org
  • 检查所有页面是否正常加载
  • 验证 SSL 证书是否有效

🎯 预期结果

部署成功后，您的网站将：

  • 在 https://www.agenticeconomics.org 上可访问
  • 拥有有效的 SSL 证书（HTTPS）
  • 每次推送到 main 分支时自动更新
  • 拥有优化的加载性能和 CDN 分发

🐛 常见问题解决

DNS 配置问题

  • DNS 记录生效可能需要 24-48 小时
  • 使用 dig www.agenticeconomics.org 验证 DNS 配置

GitHub Actions 失败

  • 检查 Gemfile.lock 是否包含正确的依赖版本
  • 确保所有 markdown 文件的 frontmatter 格式正确

SSL 证书问题

  • GitHub Pages 会自动为自定义域名颁发 SSL 证书
  • 如果出现问题，尝试重新保存域名设置

构建错误

常见的构建错误和解决方案：

  1. 插件不兼容 
    解决：确保只使用 GitHub Pages 支持的插件
参考：https://pages.github.com/versions/
  2. Ruby 版本问题 
    解决：GitHub Actions 使用 Ruby 3.1，确保本地测试使用相同版本
  3. Liquid 语法错误 
    解决：检查所有 .md 文件中的双大括号和百分号标记语法

📈 性能优化

自动优化功能

GitHub Pages 自动提供：

  • Gzip 压缩
  • 全球 CDN 分发
  • 缓存优化
  • 图片优化

额外优化建议

  • 使用 WebP 格式图片
  • 压缩 CSS 和 JavaScript
  • 启用 Jekyll 缓存插件

🔐 安全配置

推荐的安全设置

  • 启用分支保护规则
  • 要求 PR 审查
  • 启用依赖性安全警报
  • 定期更新 Jekyll 和插件版本

📞 支持资源

部署完成后，您的 Agentic Economics Initiative 网站将在 https://www.agenticeconomics.org 上线！ 🎉