🚀 Hexo + GitHub 私有仓库 + Cloudflare Pages 搭建个人博客全攻略

如果你希望博客源码保存在 GitHub，又不想自己维护服务器，Cloudflare Pages 是一个省心的选择：本地写 Markdown博客文章，推送到 GitHub 后，Cloudflare 自动抓取、生成网页并发布到网站。本教程将带你从零开始，使用 Node.js 和 Git 在 Windows 环境下配置 Hexo 博客，并将其安全地托管在 GitHub 私有仓库中，最后通过 Cloudflare Pages 实现全球加速免费部署。

本教程将实现以下目标：

  • 一个可以本地预览的 Hexo 博客；
  • 一个用于保存源码的 GitHub 仓库（建议选择Private私有）；
  • 一个自动部署的 pages.dev 网站；
  • 配置自定义域名。

本文记录的是我实际搭建博客的过程。网站面板界面可能随时间变化会有调整，但“本地撰写 → 源码仓库 → 云端构建 → public 目录上线”的逻辑不会变。

⚙️ 一、准备工作（运行环境和编辑器安装）

1. 安装 Node.js

Hexo 是基于 Node.js 运行的静态博客框架，必须先安装 Node.js 环境。

  • 下载： 访问 Node.js 官网，建议下载并安装 LTS（长期支持版）。
  • 验证： 打开电脑的 PowerShell 或 CMD，输入以下命令，看到版本号即代表安装成功：
1
2
node -v
npm -v

📷 查看node是否安装成功
📷 查看npm版本

2. 安装 Git

Git 用于管理你的博客源码并将其推送到 GitHub。

  • 下载： 访问 Git 官网 下载并安装。
  • 验证： 在命令行中输入：
1
git --version 或者 git -v

📷 查看git是否安装成功

  • 配置初始信息：（必须配置，否则无法提交代码）
1
2
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub注册邮箱"

编辑器可以使用 VS Code、Notepad++ 或Vim等其他你熟悉的工具。YAML 文件对缩进敏感，不要使用会破坏空格的富文本编辑器。

🏗️ 二、本地初始化 Hexo 博客

  1. 在电脑上找一个专门存放博客的位置，创建一个空文件夹（例如 D:\laomingong）。
  2. 在该文件夹内空白处右键，选择 在终端中打开 或打开 PowerShell 并切换到该目录：
1
cd D:\laomingong
  1. 全局安装 Hexo 脚手架：
1
npm install -g hexo-cli
  1. 初始化 Hexo 模板：（后面的 . 代表在当前文件夹直接生成）
1
hexo init .
  1. 一键安装依赖：（使用自动生成的 package.json 清单下载插件）
1
npm install

💡 本地预览： 此时输入 hexo s 或者 hexo server | npx hexo server，并在浏览器打开 http://localhost:4000，即可看到你的博客页面。在终端按 Ctrl + C 可停止预览。

📷 localhost.png

新建一篇文章

1
hexo new "我的第一篇文章" 或者 hexo n "我的第一篇文章"

文章会出现在 source\_posts文件夹中。用编辑器打开 Markdown 文件，在第二个 --- 后写正文，再次运行下面的命令即可预览。

重新生成内容

1
2
3
hexo clear
hexo generate
hexo server

上述命令也可以简写为

1
2
3
hexo cl
hexo g
hexo s

成功后会生成 public 文件夹。Cloudflare Pages 做的事情，本质上就是在云端重复构建博客内容并发布。

🔐 三、配置 GitHub 私有仓库

为了保护你的源码（包括未来的草稿、隐私配置等），我们将其上传到 GitHub 的私有仓库中。

1. 解决跨平台换行符警告

由于跨平台换行符差异，Windows 用户在提交前建议关闭自动转换提示，避免终端报错：

📷 跨平台时的CRLF修正

1
git config --global core.safecrlf false

2. 本地初始化 Git 仓库

在博客根目录（D:\laomingong）下执行：

1
2
3
git init
git add .
git commit -m "我的第一篇文章"

3. 建立 GitHub 私有仓库

  1. 登录 GitHub，点击右上角的头像 -> 选择 Repositories -> New 或者直接点击左侧的 New 创建新仓库。

📷 创建新仓库

  1. Repository name： 输入你的仓库名（例如 laomingong）。
  2. Public/Private： Public和Private均可，但为了更好地保护源码，建议选择 Private（私有）。
  3. 其他选项（README、.gitignore）不要勾选，保持默认即可。
  4. 点击 Create repository。

📷 仓库信息设置

4. 绑定并首次推送

在 GitHub 生成的空白页面上，复制你的 HTTPS 链接（格式为 [https://github.com/用户名/仓库名.git](https://github.com/用户名/仓库名.git)）。

仓库下载地址

在本地终端运行下面的命令：

1
2
3
4
5
6
7
8
# 1. 绑定远程仓库（将下面链接换成你自己的）
git remote add origin https://github.com/你的用户名/你的仓库名.git

# 2. 将本地默认分支重命名为 main
git branch -M main

# 3. 首次推送并建立绑定关系（会弹出浏览器要求进行 GitHub 账号授权验证）
git push -u origin main

📷 博客根目录文件列表

Hexo 默认生成的 .gitignore 通常会排除 node_modules 和 public。提交前建议打开确认，避免把依赖目录和构建产物上传到源码仓库。不要把访问令牌或其他密钥写进 _config.yml 文件。

5. 验证绑定是否成功:在命令行输入命令：

1
git remote -v

如返回下面的信息，则证明绑定成功：

查看仓库是否绑定成功

1
2
origin  https://github.com/你的用户名/仓库名 (fetch)
origin  https://github.com/你的用户名/仓库名 (push)

☁️ 四、配置 Cloudflare Pages 自动化部署

Cloudflare Pages 会在云端自动读取你的 GitHub 私有仓库，通过服务器把 Markdown 编译成静态网页并发布。

1. 创建 Pages 项目

  1. 登录 Cloudflare 控制台。
  2. 点击左侧菜单栏的 计算 -> Workers 和 Pages -> 点击 创建应用程序。
  3. 选择 Pages 标签页，点击 导入现在 Git存储库 -> 开始使用。
  4. 按照提示授权你的 GitHub 账号，并从列表中选择你刚刚创建的 laomingong（私有仓库），点击 开始设置。

📷 GitHub仓库选择

私有仓库也能连接，但授权时应遵循最小权限原则，只开放需要部署的仓库。

📷 selectrepository1.png

📷 selectrepository2.png

📷 创建Cloudflare Pages

2. 核心构建参数配置（关键步骤）

在设置页面，请严格按照以下参数填写：

  • 项目名称： 保持默认（或自定义）
  • 生产分支： main
  • 框架预设 (Framework preset)： 选择 None（保持未选择状态）
  • 构建命令 (Build command)： 填入 npx hexo generate 或者 npx hexo clean &&　npx hexo generate
  • 构建输出目录 (Build output directory)： 填入 public
  • 根目录 (Root directory)： 保持留空，不用填写。

构建命令务必填写 npx hexo generate 或 npx hexo g 或 npx hexo clean &&　npx hexo generate，不要写为 npm hexo generate 或 npm run build

📷 构建参数

3. 极重要：配置环境变量

由于 Hexo 新版本需要较高版本的 Node.js 环境，必须手动指定：

  1. 在当前页面下方展开 环境变量（高级） 区域。
  2. 点击 添加变量：
  • 变量名称 (Variable name)： NODE_VERSION
  • 值 (Value)： 24 (直接填大版本号即可) 版本号一定要和本地node版本保持一致，本地node版本号使用命令 node -v 查看

📷 构建参数

  1. 点击最下方的 保存并部署。

🎉 大功告成！ 几分钟后，Cloudflare 就会提示部署成功，并会为你分配一个免费的 xxx.pages.dev 专属二级域名，点击即可访问你的个人博客！

🌐 五、绑定独立域名

系统分配的域名难以记忆，可以在 Pages 项目中进入 Custom domains自定义域，添加自己的域名，例如 laomingong.com：

  • 域名已托管在同一 Cloudflare 账号：通常可自动创建 DNS 记录；
  • 域名在其他 DNS 服务商：按页面提示添加 CNAME；

📷 在Cloudflare中配置域名

同时在 Hexo 根目录的 _config.yml 设置正式网址：

1
url: https://laomingong.com

📷 配置文件中自定义域名

修改后提交并推送：

1
2
3
git add .
git commit -m "配置博客独立域名"
git push

📅 六、日常撰写博客与文章发布流程

以后每当你写了新文章，或者修改了博客配置，只需要在本地终端固定执行“日常三部曲”，线上的博客就会自动同步更新：

1
2
3
4
5
6
7
8
# 1. 将所有修改或新文章登记到暂存区
git add .

# 2. 提交到本地记录，并写下本次更新了什么
git commit -m "更新了一篇关于Git的新博客"

# 3. 一键推送到 GitHub（首次加 -u 参数，以后只需直接打 git push）
git push

自动运行逻辑： 当你敲下 git push 后，GitHub 私有仓库会收到最新的代码 ➔ Cloudflare Pages 检测到代码变动 ➔ 自动在云端执行 npx hexo generate ➔ 几秒钟后，你的个人博客网站便完成了全网更新！

📷 部署日志

🖥️ 七、换电脑之后或者使用多台电脑写博客的操作

换电脑后，不要重新执行 hexo init，也不需要重新连接 Cloudflare Pages。只要把 GitHub 中保存的 Hexo 源码克隆到新电脑，就能继续写文章。

1、新电脑首次配置

还是先下载安装 node.js 和 Git,验证成功后，使用 git config --global 命令配置用户名和邮箱。这一步和前面一样。

接下来克隆博客源码，在 GitHub 博客仓库页面点击 Code，复制 HTTPS 地址，然后在新电脑执行：

1
2
3
cd D:\
git clone --recurse-submodules https://github.com/你的用户名/仓库名.git
cd 仓库名

--recurse-submodules 可以同时下载以 Git 子模块形式安装的 Hexo 主题。

恢复项目依赖

仓库一般不会上传 node_modules，所以需要重新安装：

1
npm ci

使用 npm ci 而非 npm install 是因为前者会严格根据仓库中的 package-lock.json 恢复依赖，适合在新电脑上还原已有项目。

使用 hexo s ,在浏览器中输入 https://localhost:4000 能够正常显示主题和历史文章，就说明博客环境恢复成功。

2、在新电脑上写文章

创建文章： npx hexo new "文章标题", 使用 npx hexo generate & npx hexo s 在本地预览。

确认排版、链接和图片都正常后，上传文章并触发部署：

1
2
3
git add .
git commit -m "发布文章标题"
git push

只要 Cloudflare Pages 仍然连接着这个 GitHub 仓库，推送到生产分支后就会自动构建和发布，不需要在新电脑上登录 Cloudflare 重新配置。

3、多台电脑写作时的正确顺序

如果旧电脑和新电脑都会使用，每次开始写作前先执行： git pull --rebase,写完后再执行：

1
2
3
git add .
git commit -m "发布文章标题"
git push

简单来说，就是： 开始写之前先git pull,写完之后再git push 。否则，两台电脑同时修改同一篇文章，容易产生 Git 冲突。

⚠️ 八、常见问题排查

仓库本地与远端的命名不匹配

📷 分支名不匹配报错

使用命令将本地默认的 master 仓库分支名改为 main

1
git branch -M main

关于命令格式的问题

通常来说，如果你使用 npm install -g hexo-cli 进行的全局中安装，那么hexo命令前面的npx可以省略，并且可以缩写。否则建议使用带npx的完整命令

功能 npx完整命令（推荐） hexo-cli（全局） 缩写（仅全局）
初始化博客 npx hexo init . hexo init . ❌ 无缩写
安装依赖 npm install npm install ❌ 无缩写
启动本地服务 npx hexo server hexo server hexo s
生成静态文件 npx hexo generate hexo generate hexo g
部署到远程 npx hexo deploy hexo deploy hexo d
清理缓存 npx hexo clean hexo clean hexo cl
新建文章 npx hexo new post "title" hexo new post "title" hexo n "title"
新建页面 npx hexo new page about hexo new page about ❌ 无缩写
列出所有命令 npx hexo help hexo help ❌ 无缩写
查看版本 npx hexo -v hexo -v ❌ 无缩写

构建提示 npm ci 或依赖错误

确认仓库中存在 package.json 和 package-lock.json。本地删除依赖后重新安装并构建，再提交锁文件。这里因为是Cloudflare在云端使用hexo框架来生成博客文章，所以构建命令一定是：

1
npx hexo generate

而不能是

1
2
3
npm hexo generate
或
npm run build

node.js 和 git 安装成功，但查看版本报错

系统不识别命令

这种情况可能是程序的路径还没有在系统变量中生效，一般可以退出命令窗口重新进入即可。

部署成功但页面是 404

优先确认输出目录是 public，根目录没有误填子目录，并检查构建日志中是否真的生成了 public/index.html。

CSS 或文章链接路径错误

独立域名修改_config.yml中的 url: https://laomingong.com 字段后运行：

1
2
3
npx hexo clean
npx hexo generate
npx hexo server

推送后没有触发部署

检查推送的是否为生产分支 main，再到 Cloudflare 的部署设置中核对仓库连接。必要时可在 Deployments 中手动重试失败的构建。

🌟 九、这套方案适合谁

本方案适合希望低成本起步、愿意使用 Git、又不想维护 Linux 服务器的人。它的限制也很明显：网站主要是静态内容，复杂后端功能需要额外服务；平台规则、构建额度和部署方式也不完全由自己控制。

如果你还在 Cloudflare Pages 与 GitHub Pages 之间犹豫，可以继续阅读《Hexo 托管选型：GitHub Pages 与 Cloudflare Pages 有什么区别》。如果以后需要更强的控制能力，再迁移到 VPS + Nginx 也不会浪费前面的内容和域名积累。