Hexo 部署到 GitHub Pages 与免费域名配置完整指南

Hexo 适合做个人技术博客，GitHub Pages 适合托管静态站点。两者组合起来之后，日常维护可以很轻：本地写 Markdown，Hexo 生成静态文件，再把生成结果发布到 GitHub Pages。

这篇文章记录一套从零配置流程：如何创建 GitHub Pages 仓库、如何配置 Hexo、如何发布站点、如何绑定自定义域名，以及可以尝试哪些免费的域名或子域名服务。

信息核对时间：2026-07-01。

一、先理解两个仓库

维护 Hexo 博客时，最好把仓库分成两类：

blog-source
  _config.yml
  package.json
  package-lock.json
  source/
  scaffolds/
  tools/
  deploy.sh

username.github.io
  index.html
  archives/
  categories/
  tags/
  2026/
  css/
  js/
  CNAME

blog-source 是源码仓库，用来保存 Markdown 文章、图片、主题配置、脚本和依赖锁定文件。换电脑时 clone 这个仓库即可继续写文章。

username.github.io 是发布仓库，用来保存 Hexo 生成后的静态文件。GitHub Pages 读取这个仓库里的 HTML、CSS、JS 和图片，然后对外提供访问。

不要把 public/、.deploy_git/、node_modules/ 提交进源码仓库。它们都可以重新生成，提交进去只会让 diff 变得很吵。

二、准备 GitHub Pages 仓库

假设 GitHub 用户名是 username，需要创建一个仓库：

1	username.github.io

这是用户站点仓库。发布完成后，默认访问地址通常是：

1	https://username.github.io/

注意几点：

仓库名必须和 GitHub 用户名匹配，格式是 username.github.io。
如果只是个人公开博客，通常把仓库设为 public。
如果使用私有仓库发布 GitHub Pages，需要确认当前 GitHub 账号套餐是否支持。
不要把 Hexo 源码直接塞进这个仓库，发布仓库只放生成后的静态文件。

如果你已经有一个发布仓库，例如：

1	loki0210.github.io

那么 Hexo 的 deploy.repo 就应该指向它。

三、初始化 Hexo 项目

新建项目时可以这样做：

npm install -g hexo-cli
hexo init blog
cd blog
npm install

已有项目则直接安装依赖：

npm ci

常用脚本可以写进 package.json：

{
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  }
}

本地预览：

1	npm run server

默认访问：

1	http://localhost:4000/

构建检查：

1	npm run build

如果构建失败，优先检查 Markdown front matter、图片路径、主题配置和依赖版本。

四、安装 Git 部署插件

Hexo 发布到 GitHub Pages 常见做法有两种：

使用 GitHub Actions，把源码推到 GitHub 后自动构建。
使用 hexo-deployer-git，在本地生成静态文件并推到发布仓库。

如果想保持流程简单，可以使用第二种：

1	npm install hexo-deployer-git --save

然后在 _config.yml 配置：

url: https://username.github.io
root: /

deploy:
  type: git
  repo: git@github.com:username/username.github.io.git
  branch: master
  message: "Site updated: {{ now('yyyy-MM-dd HH:mm:ss') }}"

如果发布仓库默认分支是 main，就把 branch 改成 main。重点是 GitHub Pages 设置里选择的发布分支要和这里一致。

发布命令：

1
2
3

npm run clean
npm run build
npm run deploy

也可以写一个 deploy.sh：

#!/usr/bin/env bash
set -euo pipefail

npm run clean
npm run build
npm run deploy

给脚本加执行权限：

1	chmod +x deploy.sh

以后发布只需要：

1	./deploy.sh

五、配置 GitHub SSH 推送

如果使用 SSH 地址：

1	git@github.com:username/username.github.io.git

本机需要有 GitHub SSH key。

检查是否已经登录：

1	ssh -T git@github.com

正常会看到类似提示：

1	Hi username! You've successfully authenticated, but GitHub does not provide shell access.

如果没有 SSH key，可以生成：

1	ssh-keygen -t ed25519 -C "your-email@example.com"

然后把公钥内容添加到 GitHub：

1	cat ~/.ssh/id_ed25519.pub

GitHub 路径：

1	Settings -> SSH and GPG keys -> New SSH key

六、第一次发布

确认 _config.yml 里的站点地址：

1	url: https://username.github.io

如果还没有自定义域名，先使用 GitHub Pages 默认域名。

执行：

1
2
3

npm run clean
npm run build
npm run deploy

部署成功后，打开：

1	https://username.github.io/

如果 404，按顺序检查：

发布仓库是不是 username.github.io。
_config.yml 的 deploy.repo 是否指向发布仓库。
branch 是否和 GitHub Pages 设置一致。
GitHub Pages 是否已经启用。
发布仓库里是否真的出现了 index.html。
DNS 或 Pages 生效是否还在等待。

七、源码仓库也要推到 GitHub

发布仓库能访问，不代表源码已经保存。源码仓库需要单独推送。

创建源码仓库，例如：

1	blog-source

本地设置远端：

1	git remote add origin git@github.com:username/blog-source.git

如果当前远端还指向模板仓库，可以改掉：

1	git remote set-url origin git@github.com:username/blog-source.git

提交源码：

1
2
3

git add .
git commit -m "Update blog source"
git push -u origin master

换电脑时：

git clone git@github.com:username/blog-source.git
cd blog-source
npm ci
npm run build

日常写作流程：

# 1. 新增或修改文章
npm run build

# 2. 保存源码
git add source/_posts source/assets source/img _config.yml _config.async.yml
git commit -m "Update blog posts"
git push

# 3. 发布站点
./deploy.sh

源码提交和站点发布最好分开执行。这样即使部署失败，源码也不会丢。

八、绑定自定义域名

GitHub Pages 默认域名可用，但个人博客通常会绑定自己的域名，例如：

1	blog.example.com

或者：

1	example.com

1. 在 GitHub Pages 设置里填写域名

进入发布仓库：

1	username.github.io -> Settings -> Pages

在 Custom domain 填写：

1	blog.example.com

保存后，GitHub 会检查 DNS，并在条件满足后签发 HTTPS 证书。

2. 在 Hexo 里保留 CNAME

Hexo 每次构建都会重建 public/。如果手动在发布仓库里改 CNAME，下次 deploy 可能被覆盖。

更稳的做法是在源码仓库创建：

1	source/CNAME

内容只有一行：

1	blog.example.com

构建时 Hexo 会把它复制到 public/CNAME，部署后发布仓库也会保留这个文件。

同时把 _config.yml 的 url 改成正式域名：

1	url: https://blog.example.com

3. 子域名 DNS 配置

如果使用 blog.example.com 或 www.example.com，DNS 推荐配置 CNAME：

1
2
3

类型: CNAME
主机记录: blog
记录值: username.github.io

注意记录值不要带仓库名。应该是：

1	username.github.io

不是：

1	username.github.io/blog

4. 根域名 DNS 配置

如果使用根域名：

1	example.com

GitHub Pages 支持把根域名指向 GitHub Pages 的 A 记录：

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

可以额外配置 IPv6 的 AAAA 记录：

2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

实际配置时以 GitHub 官方文档为准。

5. 不要随便配 wildcard

不要为了省事配置：

1	*.example.com

通配符 DNS 容易带来子域名接管风险。只配置你真实使用的域名。

6. 开启 HTTPS

DNS 生效后，GitHub Pages 会做自动检查。检查通过后会申请证书。Enforce HTTPS 有时不会立刻可点，等一段时间再回来检查。

如果 HTTPS 一直失败，检查：

DNS 是否指向 GitHub Pages。
source/CNAME 是否和 GitHub Pages 设置里的域名一致。
是否存在旧的 A、AAAA、CNAME 冲突记录。
是否把 CNAME 指到了错误的仓库路径。
是否配置了不必要的通配符记录。

九、几个免费的域名或子域名申请网站

免费域名要先说清楚：很多所谓“免费域名”其实是免费子域名，不是你完全拥有的顶级域名。适合个人博客、测试项目、开源项目展示，但不适合重要商业站点。

1. EU.org

地址：

1	https://nic.eu.org/

EU.org 提供免费的 *.eu.org 子域名注册。它不是欧盟官方服务，也不是传统意义上的独立顶级域名注册，但对个人博客来说已经足够像一个正常域名。

特点：

免费。
需要先准备可用的 nameserver。
申请需要人工审核，通常不是即时开通。
适合长期个人项目，但要接受等待和审核不确定性。

配置 GitHub Pages 时，可以把 EU.org 域名交给支持 DNS 托管的服务管理，然后添加 GitHub Pages 所需的 CNAME 或 A 记录。

2. PP.UA

地址：

1 2	https://pp.ua/ https://nic.ua/en/domains/.pp.ua

.pp.ua 是乌克兰的免费域名区域，官方和注册商资料都明确说明它可以免费注册。

特点：

免费注册。
需要手机号激活。
可用于博客、测试项目、个人页面。
通常需要按规则续期，续期也可能需要验证。
WHOIS 隐私能力有限，注册前要看清规则。

如果你介意手机号、公开 WHOIS 或跨境服务稳定性，不要把它作为唯一主域名。

3. is-a.dev

地址：

1	https://github.com/is-a-dev/register

is-a.dev 是面向开发者的免费子域名服务。申请方式是 fork 官方仓库，按文档新增记录文件，然后提交 Pull Request。审核通过后 DNS 记录会发布。

特点：

免费。
域名形式适合开发者，例如 name.is-a.dev。
申请过程依赖 GitHub Pull Request。
适合个人主页、技术博客、开源项目展示。

如果博客本身是技术向内容，这类域名比较贴合定位。

4. JS.ORG

地址：

1	https://js.org/

JS.ORG 提供免费的 *.js.org 子域名，主要面向 JavaScript 相关项目，并且官方流程直接围绕 GitHub Pages 展开。

特点：

免费。
更适合 JavaScript 项目、前端库、工具或文档站。
页面内容需要和 JavaScript 有明确关联。
需要在仓库里放置匹配的 CNAME。

如果你的博客主要写 Android、Linux、后端，不一定适合申请 JS.ORG；如果是前端或 JS 项目文档，则很合适。

5. FreeDNS / afraid.org

地址：

1	https://freedns.afraid.org/

FreeDNS 提供免费 DNS、动态 DNS、静态 DNS、共享域名下的免费子域名等能力。

特点：

可申请共享域名下的子域名。
支持动态 DNS，更适合家庭服务器、临时项目、实验环境。
能否添加某些记录类型，取决于具体共享域名和权限。
域名观感不如独立域名稳定统一。

如果只是想快速得到一个可访问地址，它很方便；如果是长期个人品牌博客，建议优先考虑自有域名或更稳定的免费子域名。

十、免费域名选择建议

按个人博客场景排序：

长期博客：优先买一个便宜正式域名，其次 EU.org
开发者个人页：is-a.dev
JavaScript 项目文档：JS.ORG
测试站点或临时访问：FreeDNS
想要免费独立域名体验：PP.UA

免费服务要重点看四件事：

是否能配置 CNAME、A、AAAA 记录。
是否需要人工审核。
是否需要手机号、实名或公开 WHOIS。
是否有续期规则、滥用规则、项目类型限制。

真正长期使用的博客，域名成本其实不高。免费域名适合起步和实验，等博客稳定后，可以迁移到付费域名，并保留旧域名做跳转或备用入口。

十一、完整检查清单

发布前检查：

npm run build 能通过。
_config.yml 的 url 是最终访问域名。
_config.yml 的 deploy.repo 指向 username.github.io 发布仓库。
source/CNAME 存在，并且内容和 GitHub Pages 自定义域名一致。
DNS 子域名使用 CNAME 指向 username.github.io。
DNS 根域名使用 GitHub Pages A 记录。
GitHub Pages 设置里的发布分支正确。
GitHub Pages 的 Custom domain 已保存。
HTTPS 检查通过后开启 Enforce HTTPS。
源码仓库已经提交并推送。

十二、参考资料

Hexo One-Command Deployment：https://hexo.io/docs/one-command-deployment
Hexo GitHub Pages：https://hexo.io/docs/github-pages
GitHub Pages 自定义域名：https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site
GitHub Pages HTTPS：https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https
EU.org：https://nic.eu.org/
EU.org 注册说明：https://nic.eu.org/register.html
PP.UA：https://pp.ua/
NIC.UA 的 PP.UA 说明：https://nic.ua/en/domains/.pp.ua
is-a.dev：https://github.com/is-a-dev/register
JS.ORG：https://js.org/
FreeDNS：https://freedns.afraid.org/