配置Route53自定义子域名指向GitHub Pages仓库页面失败求助

问题描述 #

我创建了一个仓库，通过GitHub Actions部署到GitHub Pages，目前可通过<用户名>.github.io/repo-name正常访问，但在AWS Route53中将子域名repo-name.oneexample.com指向该页面时始终失败。已排除Route53解析延迟问题，网上多数教程仅覆盖子域名指向用户主页的场景，不符合我的需求。

已尝试的配置方案 #

• 场景1
  • 为oneexample.com配置指向GitHub Pages官方4个IP的A记录
  • 为repo-name.oneexample.com配置指向<用户名>.github.io的CNAME记录
  • 在仓库GitHub Pages设置中添加repo-name.oneexample.com
• 场景2
  • 为repo-name.oneexample.com配置指向<用户名>.github.io的CNAME记录
  • 在仓库GitHub Pages设置中添加repo-name.oneexample.com
  • 在仓库根目录创建CNAME文件，内容为repo-name.oneexample.com
• 场景3
  • 为oneexample.com配置指向GitHub Pages官方IP的A及AAAA记录
  • 在仓库GitHub Pages设置中添加oneexample.com

以上方案均未生效，我的需求是将子域名repo-name.oneexample.com解析至仓库对应的GitHub Pages页面（<用户名>.github.io/repo-name），主域名为oneexample.com。

正确配置步骤（针对子域名指向仓库Pages） #

1. 仓库GitHub Pages配置 #

• 进入仓库Settings → Pages，在「Custom domain」栏输入repo-name.oneexample.com并点击Save。此时GitHub会自动在仓库根目录生成CNAME文件（内容为repo-name.oneexample.com），确保该文件存在于你部署的分支（即Actions监听的Develop分支）。
• 等待GitHub完成域名验证，确认Pages设置页面显示「Your site is live at https://repo-name.oneexample.com」，无错误提示。

2. AWS Route53 DNS配置 #

• 仅需配置子域名的CNAME记录，无需对主域名oneexample.com做任何GitHub Pages相关配置：
  • 记录类型：CNAME
  • 名称：repo-name（无需填写完整域名，Route53会自动拼接主域名）
  • 值：<用户名>.github.io（注意不要附加/repo-name，GitHub会通过CNAME自动映射到对应仓库的Pages服务）

错误方案分析 #

• 场景1/3中给主域名配置A/AAAA记录是多余操作，反而可能干扰GitHub的域名验证流程，导致子域名无法正常映射。
• 场景2的配置逻辑正确，但可能存在细节错误：比如DNS记录名称填成了完整的repo-name.oneexample.com，或者未等待GitHub完成域名验证就测试访问。

GitHub Actions排查 #

你怀疑的${{ steps.deployment.outputs.page_url }}仅用于在GitHub环境中显示部署后的URL，不会影响实际部署路径或DNS解析。你的Actions配置是正常的：

• actions/upload-pages-artifact上传了整个仓库目录，包含自动生成的CNAME文件
• actions/deploy-pages会正确将内容部署到GitHub Pages服务，无论使用默认域名还是自定义域名

额外验证步骤 #

1. 检查仓库Develop分支根目录的CNAME文件是否存在，内容是否为repo-name.oneexample.com
2. 用nslookup repo-name.oneexample.com或dig repo-name.oneexample.com验证DNS解析，确认CNAME指向<用户名>.github.io
3. 清除浏览器缓存或使用无痕模式访问repo-name.oneexample.com，避免缓存导致的访问异常
4. 查看GitHub Pages设置页面的错误提示，按照提示完成域名验证（如添加TXT记录等）

内容的提问来源于stack exchange，提问作者Arthuro Verissimo