自定义域名下的GitHub多项目展示方案：从配置到优化

引言

在开源开发或团队协作中，开发者常需同时维护多个GitHub项目。若每个项目独立部署（如使用GitHub Pages），访问者需记忆多个子域名（如user.github.io/project1、user.github.io/project2），既不便于统一管理，也影响用户体验。通过自定义域名集中展示多个项目，不仅能提升品牌一致性，还能简化访问路径。本文将详细介绍如何通过DNS配置、GitHub Pages设置及项目组织策略，实现“一个域名展示多个GitHub项目”的目标。

一、核心原理与工具选择

1.1 域名与DNS解析

自定义域名的核心是通过DNS（域名系统）将域名指向特定服务器或服务。例如，将projects.example.com解析到GitHub Pages的服务器，需在域名注册商（如阿里云、GoDaddy）的DNS控制台中添加CNAME记录或A记录。

• CNAME记录：将子域名（如projects）指向GitHub Pages的默认域名（如username.github.io），适用于动态IP场景。
• A记录：直接指向GitHub Pages的IP地址（如185.199.108.153），需定期更新IP（GitHub可能调整）。

1.2 GitHub Pages的两种模式

GitHub Pages支持两种部署方式：

• 用户/组织页：基于username.github.io仓库，每个GitHub账户仅限一个，用于展示个人或组织主页。
• 项目页：基于任意仓库的/docs目录或gh-pages分支，支持无限数量，适合独立项目展示。

关键点：若需通过自定义域名展示多个项目，需将项目页的CNAME文件配置为同一子域名（如projects.example.com），而非默认的username.github.io。

二、分步实施指南

2.1 购买并配置域名

1. 选择域名：推荐使用.dev、.io等技术相关后缀，如my-projects.dev。
2. DNS设置：
   • 登录域名注册商控制台，添加CNAME记录：

     主机记录：projects
     记录类型：CNAME
     记录值：username.github.io  # 指向GitHub Pages基础域名

   • 或使用A记录（需确认GitHub当前IP）：

     主机记录：projects
     记录类型：A
     记录值：185.199.108.153  # GitHub Pages主IP

3. 等待生效：DNS更新通常需10分钟至48小时。

2.2 配置GitHub Pages

方案一：项目页独立部署（推荐）

1. 为每个项目创建gh-pages分支：

   git checkout -b gh-pages
   echo "项目文档或入口页面" > index.html
   git push origin gh-pages

2. 在项目仓库设置中启用GitHub Pages：
   • 选择源分支为gh-pages。
   • 在“Custom domain”中填入projects.example.com。
3. 添加CNAME文件：
   • 在项目根目录创建CNAME文件，内容为projects.example.com。
   • 提交并推送：

     echo "projects.example.com" > CNAME
     git add CNAME
     git commit -m "Add CNAME"
     git push origin gh-pages

方案二：子目录聚合（需服务器支持）

若需将所有项目聚合到一个页面的子目录中（如projects.example.com/project1），需：

1. 使用静态站点生成器（如Hugo、Jekyll）：
   • 创建主仓库，配置_config.yml（Jekyll）或config.toml（Hugo）生成子目录。
   • 示例Jekyll配置：

     baseurl: "/project1"  # 项目1的子目录
     url: "projects.example.com"

2. 部署到gh-pages分支：
   • 生成后的文件需包含子目录结构，并通过GitHub Actions自动部署。

2.3 验证与调试

1. 检查DNS解析：

   dig projects.example.com
   # 应返回GitHub Pages的IP或CNAME

2. GitHub Pages状态：
   • 访问仓库的“Settings”→“Pages”，确认无警告。
   • 检查“Enforce HTTPS”是否开启（强制HTTPS可避免混合内容问题）。

三、高级优化技巧

3.1 项目分类与导航

• 统一入口页面：在projects.example.com下创建索引页，列出所有项目链接。

  <!-- index.html示例 -->
  <ul>
    <li><a href="/project1">项目1</a></li>
    <li><a href="/project2">项目2</a></li>
  </ul>

• 使用GitHub API动态生成：通过JavaScript调用GitHub API获取仓库列表，自动生成导航。

3.2 自动化部署

• GitHub Actions示例：

  name: Deploy Projects
  on:
    push:
      branches: [main]
  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v2
        - run: |
            git subtree push --prefix project1 origin gh-pages
            git subtree push --prefix project2 origin gh-pages

3.3 性能优化

• 启用CDN：通过Cloudflare等CDN加速域名访问。
• 压缩资源：使用工具（如html-minifier）压缩HTML/CSS/JS。

四、常见问题与解决方案

4.1 域名冲突

• 问题：多个项目配置相同CNAME导致冲突。
• 解决：确保每个项目的CNAME文件内容唯一，或使用子目录方案。

4.2 HTTPS证书错误

• 问题：自定义域名未启用HTTPS。
• 解决：在GitHub Pages设置中勾选“Enforce HTTPS”，并等待证书颁发（通常1小时内生效）。

4.3 缓存问题

• 问题：修改后页面未更新。
• 解决：在浏览器中强制刷新（Ctrl+F5），或清除GitHub Pages的CDN缓存（需联系GitHub支持）。

五、总结与扩展

通过自定义域名展示多个GitHub项目，可显著提升开发者的项目管理效率与访问者体验。核心步骤包括：

1. 配置DNS指向GitHub Pages。
2. 为每个项目设置独立的gh-pages分支或子目录。
3. 通过CNAME文件统一域名。
4. 优化导航与自动化部署。

扩展场景：

• 企业级应用：结合GitHub Enterprise与私有域名，实现内部项目展示。
• 多语言支持：通过子域名（如en.projects.example.com）区分语言版本。

通过本文的方案，开发者既能保持GitHub的便捷性，又能获得定制化的域名体验，适用于个人作品集、开源组织或团队协作场景。