这是一篇真正面向国内网络环境的 Hexo 博客搭建与云端部署通关指南。文章会记录初始化 Hexo、配置 Butterfly 主题、同步源码到 GitHub，再通过 Cloudflare Pages 自动构建上线的完整流程，也会顺带说明几个常见的踩坑点。

一、本地环境准备与初始化

建议先创建一个干净的博客目录，避免把依赖文件散落在系统目录中。

1
2
mkdir myblog
cd myblog

1. 使用镜像源初始化

如果 GitHub 直连超时，可以使用 Gitee 镜像初始化 Hexo：

1
hexo init --clone https://gitee.com/hexojs/hexo-starter.git

提示：即使中途因默认主题下载触发 GitHub 报错，只要最后显示 INFO Start blogging with Hexo!，基础框架就已经复制完成。

2. 配置 npm 镜像并安装依赖

1
2
npm config set registry https://registry.npmmirror.com
npm install

二、安装 Butterfly 并配置页面

我选择了 Butterfly 主题，它自带归档、标签、分类、友链和搜索等常见博客能力，后续只需要维护配置文件和 Markdown 内容即可。

1
npm install hexo-theme-butterfly hexo-renderer-pug hexo-renderer-stylus --save

然后在根目录 _config.yml 中把主题切换为 butterfly，再新建独立主题配置文件 _config.butterfly.yml。

1. 注意 YAML 语法

修改菜单、评论等配置时，冒号后面如果还有内容，必须紧跟一个空格，否则会导致编译或页面渲染异常。

1
2
3
4
menu:
  首页: / || fas fa-home
  时间轴: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags

2. 创建核心路由页面

标签页、分类页、友链页和关于页都需要在 source 目录中创建对应页面，并声明正确的页面类型：

1
2
3
4
hexo new page tags
hexo new page categories
hexo new page link
hexo new page about

以标签页为例，source/tags/index.md 的 Front-matter 需要包含：

1
2
3
4
5
---
title: tags
date: 2026-06-02 19:53:53
type: "tags"
---

友链页使用 type: "link"，分类页使用 type: "categories"。

3. 检查本地构建

主题安装并配置完成后，先清理再生成：

1
hexo clean && hexo generate

看到 INFO xx files generated 即代表本地构建成功。之后再执行下面的本地预览命令，在浏览器中逐页检查菜单、图片和链接是否正常：

1
hexo server

三、源码同步至 GitHub

在 GitHub 上创建一个公开空仓库，例如命名为 hexo，然后把本地代码推送上去：

1
2
3
4
5
6
git init
git remote add origin https://github.com/你的用户名/hexo.git
git branch -M main
git add .
git commit -m "feat: 初始化 Hexo 博客"
git push -u origin main

如果网络环境不稳定，可以在推送前为本机 Git 配置代理。具体监听端口需要以你本地代理软件显示的信息为准：

1
2
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

四、托管至 Cloudflare Pages

Cloudflare Pages 提供全球 CDN，并且支持 GitHub 推送后自动构建部署。

1. 不要选错产品

进入 Cloudflare 控制台后，依次选择 Workers 和 Pages、创建、Pages，然后点击 连接到 Git 并选中博客仓库。

2. 配置构建参数

构建参数需要与实际仓库结构保持一致：

  • 生产分支：main
  • 框架预设：选择 Hexo，或选择 Custom 后手动填写
  • 根目录：如果源码在仓库根目录就填 /；如果源码在子目录中，则填写对应子目录，例如 myblog
  • 构建命令：npx hexo generate
  • 构建输出目录：public

点击 保存并部署 后，Cloudflare 会自动拉取源码并在云端完成构建。构建成功后，可以在 Pages 的 自定义域 页面绑定自己的域名。

五、以后写文章的三步流程

把源码推送到 GitHub 后，Cloudflare Pages 会自动重新构建，所以日常发布只需要执行 Git 三步：

1
2
3
git add .
git commit -m "发布一篇新文章"
git push -u origin main

几秒钟后刷新网站，新文章就会自动上线。祝你的独立博客之旅一路顺风！