CNAME自动部署与HTTPS生效方案-编程实验室

在 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-pages@v3 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/checkout@v3 with: submodules: recursive fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v3 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-pages@v3 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）访问博客，浏览器地址栏应显示安全的锁标志。