Hexo 博客搭建教程（上）：GitHub Pages + Cloudflare Pages 免费托管全流程

说明：本文初版写于 2026 年 3 月，2026 年 10 月修订。本教程介绍如何用 Hexo 搭建个人博客，并免费部署到 GitHub Pages 和 Cloudflare Pages，适合零基础新手。

1. 事前准备

  1. 域名（非必须）：可以使用 GitHub.io 或 Pages.dev 分配的免费二级域名；
  2. GitHub 账号（必须）：github.com，用于托管博客源码；
  3. Cloudflare 账号（必须）：cloudflare.com，用于部署到 Cloudflare Pages 并获得 CDN 加速。

2. 安装必备软件

  1. Node.js（必须）：nodejs.org，下载与自己系统对应的安装包；
  2. Git（必须）：git-scm.com，下载后按默认选项安装；
  3. VSCode（非必须）：code.visualstudio.com，轻量代码编辑器，写文章时用起来更顺手。

2.1 安装 Node.js

  1. 打开 Node.js 官网，下载与自己系统匹配的安装程序；
  2. 安装时可以使用默认目录（如 C:/Program Files/nodejs/）；
  3. 安装完成后，按 Win + R，输入 cmd 回车，在命令行执行 node -v，能看到版本号即安装成功。

npm 默认从国外服务器下载依赖，速度较慢，建议换成国内镜像源：

1
npm config set registry https://mirrors.huaweicloud.com/repository/npm/

2.2 安装 Git

  1. 去官网下载对应系统的 Git 安装包；
  2. 按默认选项一路安装即可；
  3. 安装完成后，在开始菜单可以看到 Git CMD、Git Bash、Git GUI：
    • Git Bash 是 Linux 风格的命令行（推荐使用）；
    • Git GUI 是图形界面，新手学习阶段不建议用。

3. 配置 Git 并连接 GitHub

常用 Git 命令：

1
2
git config -l            # 查看所有配置
git config --global --list  # 查看全局配置

3.1 配置用户名和邮箱

1
2
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

用 git config -l 检查是否配置成功。

3.2 生成 SSH 公钥并配置到 GitHub

  1. 执行以下命令生成 SSH 密钥（提示输入文件路径时直接回车即可，新手不建议设置密码）：
1
ssh-keygen -t rsa -C "你的邮箱"
  1. 生成后打开用户目录下的 .ssh 文件夹，会看到 id_rsa（私钥）和 id_rsa.pub（公钥）；
  2. 用记事本打开 id_rsa.pub，复制全部内容；
  3. 进入 GitHub，点击右上角头像 → Settings → SSH and GPG keys，名字随便起，把公钥粘贴到 Key 一栏保存。

3.3 测试连接

1
ssh -T [email protected]

首次连接会提示 Are you sure you want to continue connecting (yes/no/[fingerprint])?，输入 yes。看到欢迎信息即表示连接成功。

3.4 创建 GitHub.io 仓库

  1. 点击右上角 + → New repository；
  2. 仓库名必须为 <你的用户名>.github.io（前缀为你的 GitHub 用户名）；
  3. 可见性选 Public（方便首次部署排查问题），点击 Create repository。

4. 初始化 Hexo 博客

  1. 新建一个文件夹存放博客源码（示例路径 D:/Hexo-Blog），在文件夹内右键选择 Open Git Bash here；
  2. 安装 Hexo 命令行工具并验证：
1
2
npm install -g hexo-cli
hexo -v
  1. 初始化项目并安装依赖：
1
2
3
hexo init blog-demo
cd blog-demo
npm install

  1. 初始化后的目录结构：

    • node_modules：依赖包；
    • scaffolds：文章模板；
    • source：存放你的文章；
    • themes：主题；
    • _config.yml：博客主配置文件。

  2. 启动本地预览：

1
hexo clean && hexo server

打开浏览器访问 http://localhost:4000/，能看到默认页面即构建成功。

5. 部署到 GitHub Pages

  1. 安装部署插件：
1
npm install hexo-deployer-git --save
  1. 修改项目根目录下的 _config.yml，找到末尾的 deploy 配置（注意缩进），把 repository 换成你自己的仓库地址，分支用 main：
1
2
3
4
deploy:
  type: git
  repository: [email protected]:<你的用户名>/<你的用户名>.github.io.git
  branch: main
  1. 执行部署三连：
1
2
hexo clean && hexo generate && hexo deploy
# 可缩写为：hexo cl && hexo g && hexo d
  • hexo clean：清理之前生成的文件；
  • hexo generate：生成静态页面；
  • hexo deploy：推送到 GitHub。

部署时可能需要输入 GitHub 用户名和密码。看到 Deploy done 即部署成功，稍等两分钟后访问 https://<你的用户名>.github.io 即可看到博客。

6. 部署到 Cloudflare Pages

  1. 登录 Cloudflare，进入 Workers 和 Pages → Pages → 连接到 Git；
  2. 授权并选择你的博客仓库；
  3. 点击”保存并部署”，等待构建完成；
  4. 看到”成功！您的项目已部署到以下区域：全球”后，访问分配的 pages.dev 域名即可。

之后如果只用 Cloudflare Pages 托管，可以把 GitHub 上的源码仓库设为 Private 私有库。绑定自己的域名也在 Pages 项目的”自定义域”里操作。

7. 日常使用

新建文章

1
hexo new "这是一篇新的博文"

然后用编辑器打开 source/_posts/ 下对应的 .md 文件，用 Markdown 格式写作。详细语法可查阅 Hexo 官方写作指南。

本地预览

1
hexo clean && hexo server

浏览器打开 http://localhost:4000/ 预览。

发布更新

1
hexo clean && hexo generate && hexo deploy

常见问题

Q：VSCode 终端执行 Hexo 命令报错？

A：以管理员身份打开 PowerShell，执行以下命令后重试：

1
Set-ExecutionPolicy RemoteSigned

Q：部署后访问 GitHub.io 显示 404？

A：刚部署完需要等几分钟；检查仓库名是否为 <你的用户名>.github.io 且为 Public；检查 _config.yml 里 deploy.repository 地址和分支是否正确。

参考资料

下期预告：Hexo 进阶——主题美化。

🎬 YouTube：https://www.youtube.com/@DECODING-w7d
👥 官方群组：https://t.me/+tVg48WK48tlkNGVl
📣 官方网站：http://smjmgx.dpdns.org/