在 GitHub Actions 自动部署流程中确保CNAME文件和自定义域名的 HTTPS 自动生效是博客持续交付的关键环节。其核心在于通过工作流配置将包含域名的CNAME文件持久化到最终部署的静态文件目录如gh-pages分支并利用 GitHub Pages 的自动 SSL 证书签发功能。以下是确保其生效的完整设置方法。核心原理与问题分析当你在 GitHub 仓库的 Settings - Pages 中设置了自定义域名如blog.example.com后GitHub 会尝试为此域名签发并配置 SSL 证书以启用 HTTPS。此过程依赖于一个关键文件位于 Pages 服务根目录下的CNAME文件。该文件内容就是你的自定义域名。问题根源在使用 GitHub Actions 自动构建和部署时例如 Hexo、Hugo 等静态网站生成器构建步骤通常在干净的临时目录中执行生成的public/或docs/目录是全新的不包含你之前手动创建或由其他方式生成的CNAME文件。因此每次自动部署后CNAME文件都会丢失导致自定义域名设置失效HTTPS 也可能因此中断。解决方案确保 CNAME 文件被包含在部署中解决方法分为两类核心都是让CNAME文件成为构建产物的一部分。方法一将 CNAME 文件置于博客源码目录推荐这是最直接和可靠的方法。将CNAME文件放在博客项目的源代码目录中并确保构建流程不会忽略或删除它。创建 CNAME 文件在你的博客项目根目录下的source文件夹中对于 Hexo创建一个名为CNAME的文件注意无后缀名。文件内容只写你的域名每行一个例如blog.example.com不要包含http://或https://前缀。配置静态生成器以保留 CNAME 文件某些静态网站生成器如 Hexo在构建时默认会处理source目录下的所有文件。但为了确保万无一失特别是当你的CNAME文件被意外渲染或忽略时需要在配置文件中明确声明。对于 Hexo编辑博客根目录的_config.yml文件找到skip_render配置项将CNAME添加进去。这告诉 Hexo 在生成静态文件时直接复制CNAME文件而不进行任何处理。# _config.yml skip_render: - CNAME - ‘404/index.html‘ # 如果有其他需要跳过的文件可以一起列出经过此配置执行hexo generate后source/CNAME文件会被原样复制到public/目录下 。验证与部署在本地运行hexo clean hexo generate检查生成的public/目录根节点下是否包含了CNAME文件。确认无误后将包含此配置的代码推送到主分支。GitHub Actions 工作流会执行相同的构建命令CNAME文件将随其他静态文件一同被部署到gh-pages分支。方法二在 GitHub Actions 工作流中动态创建 CNAME 文件如果你不希望将域名硬编码在源码中或者构建流程无法方便地保留CNAME文件可以在工作流步骤中动态创建它。在部署步骤peaceiris/actions-gh-pages之前添加一个步骤来创建CNAME文件到构建输出目录。# .github/workflows/deploy.yml 片段 jobs: build-and-deploy: runs-on: ubuntu-latest steps: # ... 之前的步骤检出代码、安装环境、构建 ... - name: Create CNAME file run: | echo blog.example.com ./public/CNAME # 将域名写入构建输出目录 # ... 之后的部署步骤 ...或者你也可以利用peaceiris/actions-gh-pagesAction 提供的cname参数它会在部署时自动创建CNAME文件。- name: Deploy uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public publish_branch: gh-pages cname: blog.example.com # 使用此参数自动生成CNAME文件配置自定义域名与强制 HTTPS确保CNAME文件被正确部署后你还需要在 GitHub 仓库设置中完成域名绑定和 HTTPS 强制跳转。在 GitHub 仓库设置中配置自定义域名访问你的 GitHub 仓库。点击Settings-Pages。在Custom domain输入框中填入你的域名如blog.example.com然后点击Save。等待并启用强制 HTTPS保存自定义域名后GitHub 会开始为你的域名自动申请并配置来自 Let‘s Encrypt 的 SSL 证书。这个过程通常需要几分钟到一小时。等待一段时间后刷新页面。你会看到Enforce HTTPS复选框从灰色不可选状态变为可选状态。如果复选框长时间保持灰色一个有效的解决方法是暂时清空Custom domain输入框点击Save。然后再次填入你的域名点击Save。这有时可以重新触发证书的签发流程 。一旦Enforce HTTPS复选框可以勾选请务必勾选它。这会强制所有通过你的自定义域名访问的流量都使用 HTTPS。完整工作流配置示例集成CNAME处理以下是一个整合了上述最佳实践的 Hexo 博客部署工作流配置示例。name: Deploy to GitHub Pages on: push: branches: [ main ] pull_request: branches: [ main ] permissions: contents: write jobs: build-and-deploy: runs-on: ubuntu-latest concurrency: ci-${{ github.ref }} steps: - name: Checkout repository uses: actions/checkoutv3 with: submodules: recursive fetch-depth: 0 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: ‘18.x‘ cache: ‘npm‘ # 缓存npm依赖以加速构建 - name: Install and Build run: | npm ci npx hexo clean npx hexo generate # 此步骤将包含skip_render配置的CNAME文件复制到public目录 # 方法二的替代方案如果未在Hexo中配置skip_render可使用此步骤动态创建 # - name: Create CNAME file (Alternative) # run: echo “blog.example.com“ ./public/CNAME - name: Deploy uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public publish_branch: gh-pages # 如果使用方法二且未使用上面的“Create CNAME file”步骤可以启用下面这行 # cname: blog.example.com总结与验证流程为确保万无一失建议遵循以下清单进行验证源码配置确认CNAME文件已置于source/目录且_config.yml中已配置skip_render: - CNAME。本地构建验证在本地运行构建命令检查public/目录根节点下是否存在内容正确的CNAME文件。工作流配置将更新后的代码和工作流配置文件推送到main分支。监控 Actions在仓库的 Actions 选项卡中查看最新工作流运行是否成功。检查部署步骤的日志确认gh-pages分支已更新。检查 Pages 设置工作流成功后前往 Settings - Pages。确认Custom domain已正确显示你的域名并且Enforce HTTPS复选框已成功勾选。最终访问测试使用你的自定义域名如https://blog.example.com访问博客浏览器地址栏应显示安全的锁标志。通过以上步骤GitHub Actions 在每次自动部署时都会将CNAME文件正确地包含在最终发布的静态网站中。GitHub Pages 服务检测到该文件后会维持你的自定义域名绑定并自动管理 SSL 证书从而实现 HTTPS 的自动生效和持续保障 。参考来源如何在GitHub Pages上为自定义域名配置HTTPS支持-百度开发者中心别再手动传代码了用GitHub Actions Cloudflare Pages实现静态网站自动部署保姆级教程-CSDN博客利用GitHubActions自动部署Hexo博客-腾讯云开发者社区-腾讯云