本文记录一次从零搭建 Hexo 博客，并部署到 Cloudflare Pages 的完整流程。

整体链路是：

1
本地 Hexo 项目 -> GitHub 仓库 -> Cloudflare Pages 自动构建部署

适合想要用静态博客记录内容，同时又希望部署简单、访问速度稳定的场景。

🧰 准备工作

开始前需要先准备好这些工具和账号：

项目 用途
Node.js / npm 安装 Hexo 和项目依赖
Git 管理代码并推送到 GitHub
GitHub 账号 托管博客源码
Cloudflare 账号 部署静态站点

可以先检查本地环境：

1
2
3
node -v
npm -v
git --version

🛠️ 一、本地搭建 Hexo

📦 1. 安装 Hexo CLI

先全局安装 Hexo 命令行工具：

1
npm install hexo-cli -g

安装完成后可以检查版本：

1
hexo -v

🏗️ 2. 创建 Hexo 博客项目

创建一个名为 blog 的 Hexo 项目：

1
hexo init blog

blog 是项目目录名，可以按自己的需要修改。

进入项目目录：

1
cd blog

安装依赖：

1
npm install

💻 3. 本地启动博客

启动本地预览服务：

1
hexo server

也可以使用简写：

1
hexo s

默认访问地址通常是：

1
http://localhost:4000

📝 4. 创建文章

新建一篇文章：

1
hexo new "文章名"

文章会生成在：

1
source/_posts/

📦 5. 生成静态文件

生成最终要部署的静态文件：

1
hexo generate

也可以使用简写：

1
hexo g

生成后的文件会输出到：

1
public/

🐙 二、上传到 GitHub

👤 1. 配置 Git 用户信息

如果是第一次使用 Git，需要先配置用户名和邮箱：

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

检查配置是否成功：

1
git config --global --list

🌱 2. 初始化本地仓库

在 Hexo 项目根目录执行：

1
2
3
git init
git add .
git commit -m "Initial commit"

🗂️ 3. 在 GitHub 新建仓库

进入 GitHub 后按下面步骤创建仓库：

  1. 登录 GitHub。
  2. 点击右上角的 +，选择 New repository。
  3. 在 Repository name 中填写仓库名，例如 blog。
  4. Description 可以填写简单说明，例如 我的 Hexo 博客。
  5. 仓库可以选择 Public，方便后续 Cloudflare Pages 访问。
  6. 点击 Create repository 创建仓库。

🚚 4. 推送项目到 GitHub

把本地仓库关联到 GitHub：

1
git remote add origin https://github.com/Anson-sen/blog.git

切换默认分支为 main：

1
git branch -M main

推送到远程仓库：

1
git push -u origin main

后续更新文章时，一般只需要：

1
2
3
git add .
git commit -m "Update blog"
git push

☁️ 三、部署到 Cloudflare Pages

🌐 1. 创建 Pages 项目

进入 Cloudflare 后台后：

  1. 登录 Cloudflare。
  2. 进入 Workers & Pages 或 Pages。
  3. 点击 Create project。
  4. 选择连接 GitHub。
  5. 授权 Cloudflare 访问你的 GitHub 仓库。
  6. 选择刚刚上传的博客仓库，例如 blog。

⚙️ 2. 配置构建参数

Cloudflare Pages 构建 Hexo 项目时，关键配置如下：

配置项 填写内容
Framework preset None 或 Hexo
Build command npx hexo generate
Build output directory public
Root directory 留空，除非项目不在仓库根目录

构建命令：

1
npx hexo generate

发布目录：

1
public

配置完成后点击部署，Cloudflare 会自动拉取 GitHub 仓库并生成静态网站。

🧯 四、常见问题

🧶 1. 部署失败，并且日志里出现 Yarn

如果 Cloudflare Pages 部署失败，日志中出现和 Yarn 相关的错误，可能是项目里存在 yarn.lock，但你实际使用的是 npm。

常见原因是：

Cloudflare Pages 在安装依赖时使用了 Yarn，但项目里的 yarn.lock 不完整、过旧，或者和 package.json 不一致，导致安装失败。

image.png
如果你不想使用 Yarn，可以删除 yarn.lock，统一切换到 npm。

Windows PowerShell：

1
2
Remove-Item yarn.lock
npm install

如果已经被 Git 跟踪，需要从 Git 中移除：

1
2
3
4
git rm yarn.lock
git add package.json package-lock.json
git commit -m "Switch to npm"
git push

🕳️ 2. Cloudflare Pages 构建后页面空白

优先检查这几项：

  1. 构建命令是否是 npx hexo generate。
  2. 发布目录是否是 public。
  3. 本地执行 npm run build 是否能成功。
  4. _config.yml 里的 url 是否配置成正式域名。

✅ 五、总结

到这里，一个基于 Hexo、GitHub 和 Cloudflare Pages 的博客就搭建完成了。

后续写作流程可以固定为：

1
2
3
4
5
6
hexo new "文章标题"
hexo clean
hexo generate
git add .
git commit -m "Add new post"
git push

推送到 GitHub 后，Cloudflare Pages 会自动重新构建并发布网站。

📌 六、常用命令速查

🦋 Hexo 常用命令

命令 作用
hexo new "文章标题" 新建文章
hexo server 启动本地预览服务
hexo s hexo server 的简写
hexo clean 清理缓存和已生成的静态文件
hexo generate 生成静态文件
hexo g hexo generate 的简写
hexo deploy 执行部署命令，需要先配置 deploy

常用本地预览流程：

1
2
3
hexo clean
hexo generate
hexo server

如果项目里配置了 npm scripts，也可以使用：

1
2
3
npm run clean
npm run build
npm run server

🔧 Git 常用命令

命令 作用
git status 查看当前文件变更状态
git add . 暂存全部修改
git commit -m "提交说明" 提交修改
git push 推送到远程仓库
git pull 拉取远程仓库最新代码
git log --oneline 查看简洁提交记录

常用发布流程：

1
2
3
4
git status
git add .
git commit -m "Update blog"
git push

☁️ Cloudflare Pages 部署检查

如果推送后 Cloudflare 没有正常部署，可以按下面几项检查：

检查项 推荐值
Build command npx hexo generate
Build output directory public
Node.js version 建议使用当前本地一致的大版本
包管理器 npm 项目建议保留 package-lock.json，不要混用 yarn.lock

本地先验证构建：

1
2
npm install
npm run build

如果本地构建成功，再提交到 GitHub：

1
2
3
git add .
git commit -m "Build check"
git push