GitHub Pages + Hexo 部署个人博客：绑定免费域名与自动化部署实践

拥有一套独立、可控的个人博客系统，并将它托管在可靠且免费的平台上，是许多开发者和技术爱好者的常见需求。本文将详细介绍如何结合静态博客框架 Hexo、GitHub 的 Pages 服务，并最终通过 Vercel 绑定免费域名，实现一套从写作到发布的免费、自动化个人博客方案。

准备工作与环境配置

本方案基于以下核心组件：

• 博客框架：Hexo，一个快速、简洁且强大的 Node.js 静态博客框架。
• 托管平台：GitHub Pages，提供免费的静态网站托管服务。
• 持续集成：GitHub Actions，用于自动化构建和部署。
• 域名与扩展托管：免费域名（例如 starttech.dpdns.org）和 Vercel，用于提供自定义域名访问和全球 CDN。

首先，确保你的本地或服务器环境已安装好 Git 和 Node.js。安装 Hexo 的命令行工具并初始化博客项目：

npm install hexo-cli -g
hexo init blog

执行 hexo init blog 后，会在当前目录创建一个名为 blog 的文件夹。进入该目录，可以看到 Hexo 自动生成的项目结构，其中包含关键的 _config.yml（站点配置文件）、package.json（Node.js 项目依赖）、scaffolds（模板文件夹）、source（存放文章源文件的目录）以及 themes（主题目录）等。

创建 GitHub 仓库与 SSH 密钥配置

博客的源代码和部署都将通过 GitHub 管理。首先，你需要在 GitHub 上创建一个新的仓库。创建时，仓库名称需要遵循特定的格式：你的用户名.github.io。例如，用户名为 jsonhc，则仓库名应为 jsonhc.github.io。这个名称不仅作为代码仓库，也将是你博客通过 GitHub Pages 访问的默认域名。

为了让本地环境能够顺畅地与 GitHub 仓库进行代码推送，需要配置 SSH 密钥认证。检查你的 ~/.ssh/ 目录下是否已有密钥对：

ls -l ~/.ssh/

如果已有 id_ed25519（私钥）和 id_ed25519.pub（公钥）文件，可以直接使用。如果没有，请使用 ssh-keygen 命令生成。接着，将公钥文件（id_ed25519.pub）的内容全部复制。

登录 GitHub，进入 Settings -> SSH and GPG keys 页面，点击 “New SSH key”。将复制的公钥内容粘贴到 “Key” 区域，并起一个易于识别的标题（例如 worker02），然后保存。配置成功后，你可以在该页面看到已添加的密钥列表，状态显示为 “Never used - Read/write”。

推送 Hexo 源码至 GitHub

SSH 密钥配置无误后，便可以将本地的 Hexo 项目克隆到服务器或本地进行后续操作，并将初始化好的博客源码推送上去。

首先，克隆你刚刚创建的空白仓库：

git clone git@github.com:jsonhc/jsonhc.github.io.git

克隆完成后，进入仓库目录，将之前 hexo init 生成的博客所有文件复制过来：

cp -a blog/* jsonhc.github.io/
cd jsonhc.github.io/

此时，jsonhc.github.io 目录下的文件应与 blog 目录一致，包含 _config.yml、package.json、node_modules、scaffolds、source、themes 等核心文件和目录。

接下来，执行标准的 Git 操作，将代码推送到远程仓库的 main 分支：

git add .
git commit -m “init”
git push -u origin main

推送成功后，刷新你的 GitHub 仓库页面，可以看到所有 Hexo 源文件已经完整地上传，仓库结构清晰地展示出来。

配置 GitHub Actions 实现自动化部署

为了让博客在每次代码更新后自动构建并发布，我们需要配置 GitHub Actions 工作流。这涉及到两个关键步骤：创建 Personal Access Token (PAT) 和编写工作流配置文件。

1. 创建 GitHub Personal Access Token

这个 Token 将作为工作流部署时的身份凭证。访问 github.com/settings/tokens，点击 “Generate new token (classic)”。在权限选择中，至少需要勾选 repo（完全控制仓库）权限。生成成功后，务必立即复制并保存好 Token 字符串，因为关闭页面后将无法再次查看。

2. 将 Token 添加为仓库密钥

回到你的博客仓库页面，进入 Settings -> Secrets and variables -> Actions。点击 “New repository secret”，名称填写为 GH_PAGES_TOKEN（这个名称将在工作流配置中被引用），值粘贴上一步复制的 Token，然后保存。保存后，你可以在仓库秘密列表中看到名为 GH_PAGES_TOKEN 的条目。

3. 创建并配置 GitHub Actions 工作流文件

在仓库根目录下创建 .github/workflows/deploy.yml 文件。这个文件定义了自动化部署的流程：监听 main 分支的推送事件，使用最新的 Ubuntu 环境，依次执行代码检出、配置 Node.js、安装 Hexo 及项目依赖、生成静态文件，最后使用专用 Action 将 public 目录部署到 gh-pages 分支。

以下是该工作流配置的完整内容，你需要将其逐字复制到 deploy.yml 文件中：

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ‘22’

      - name: Install dependencies
        run: npm install hexo-cli -g && npm install && hexo clean && hexo generate && hexo deploy

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GH_PAGES_TOKEN }}
          publish_dir: ./public

文件创建并推送后，GitHub Actions 会自动开始运行。你可以在仓库的 “Actions” 标签页下查看工作流运行状态。初次运行可能会触发两个工作流：一个是创建 deploy.yml 文件的记录，另一个是实际的 “pages build and deployment”。确保部署作业成功完成。

成功运行后，你的仓库会自动创建一个名为 gh-pages 的分支。这个分支里存放的就是 Hexo 生成的、最终用于访问的静态网站文件，包括 index.html、css、js 等资源。

启用并配置 GitHub Pages

静态文件已就绪，现在需要告诉 GitHub Pages 从哪个分支获取内容。进入仓库的 Settings -> Pages 页面。在 “Build and deployment” 部分的 “Source” 选项中，选择 “Deploy from a branch”。在下拉菜单中，将分支设置为 gh-pages，文件夹保持为 /(root)，然后点击保存。

保存后，页面会显示 “Your site is live at …”，后面跟着 https://你的用户名.github.io 的链接。点击访问，你应该能看到 Hexo 默认主题的博客首页，上面有一篇标题为 “Hello World” 的示例文章。这标志着基于 GitHub Pages 的博客已经部署成功，并且实现了推送代码自动更新的 GitHub CI/CD 流程。

使用 Vercel 绑定免费自定义域名

虽然 用户名.github.io 的域名可以访问，但一个自定义域名更能体现个人品牌。这里我们使用 Vercel 这一优秀的静态网站托管平台来绑定免费域名，它同样免费并提供全球 CDN。

1. 导入 GitHub 项目到 Vercel

访问 vercel.com 并使用 GitHub 账号登录。在控制台点击 “Add New… -> Project”。在导入 Git 仓库的界面，Vercel 会列出你的 GitHub 仓库。找到你的博客仓库（jsonhc.github.io）并点击 “Import”。

在授权步骤，Vercel 会请求访问 GitHub 仓库的权限。为了安全，建议在 “Install on your personal account” 时，选择 “Only select repositories”，并指定仅授权给你的博客仓库。

2. 配置并部署项目

在项目配置页面，Vercel 通常能自动识别出 Hexo 项目并预设好配置（Application Preset 显示为 Hexo）。你只需确认项目名称，其他设置如根目录（./）保持默认即可，直接点击 “Deploy”。

部署过程非常快，完成后会跳转到恭喜页面，并展示你的博客预览图。此时，你的博客已经拥有了一个由 Vercel 提供的临时域名。

3. 添加并验证自定义域名

在 Vercel 的项目仪表盘，进入 “Domains” 设置。输入你已获得的免费域名，例如 starttech.dpdns.org，然后点击 “Add”。

添加后，Vercel 会提供一组 DNS 记录（通常是几条 CNAME 或 A 记录）。你需要到你域名的 DNS 服务商（例如 CloudFlare）的管理面板，按照 Vercel 给出的记录值逐一添加。关于如何在 CloudFlare 上管理 DNS 记录，可以参考相关 运维/DevOps/SRE 指南。

DNS 记录配置完成后，等待一段时间（通常几分钟到几小时）让其全球生效。之后回到 Vercel 的 Domains 页面刷新，域名状态会从 “Pending Verification” 变为 “Valid”。至此，你的博客已经可以通过免费的自定义域名 starttech.dpdns.org 访问了。

总结

通过以上步骤，我们成功搭建了一套完全免费的博客系统：使用 Hexo 进行内容创作和管理，利用 GitHub Actions 实现自动化构建，最终通过 Vercel 绑定自定义域名并提供高速、稳定的全球访问。这套方案不仅成本为零，而且将现代开发中的版本控制（Git）、持续集成/持续部署（CI/CD）和静态网站托管最佳实践融合在一起。你只需专注于在 source/_posts 目录下用 Markdown 写作，然后执行 git push，剩下的所有流程都将自动完成。

这种基于 Node.js 生态和 Git 工作流的博客搭建方式，非常适合开发者。如果你想了解更多关于静态网站生成、Node.js 项目优化或其他 DevOps 实践，欢迎持续关注 云栈社区 的相关技术分享。

参考资料

[1] 通过github pages部署hexo博客系统，关联免费域名并免费托管, 微信公众号：mp.weixin.qq.com/s/BKzgHnOabfTRdzeRr86H6A

版权声明：本文由 云栈社区 整理发布，版权归原作者所有。