从零开始：如何在 Cloudflare Pages 上免费部署 Hexo 博客并解决常见错误

在 Cloudflare Pages 上轻松部署 Hexo 博客的简易教程

Hexo 作为轻量高效的静态博客框架，搭配 Cloudflare Pages 的全球CDN加速和免费托管服务，是搭建个人博客的理想选择。本文将分享两种核心部署方案，助你5分钟内上线专业博客。

了解 Cloudflare Pages 的限制

在开始部署前，只需记住三个关键限制：每月500次构建限额（超过后部署会失败），单个文件25MB大小限制和20,000个文件数量限制。对于纯静态博客，没有函数调用，故无需考虑该限制（和workers共用的100,000次调用）。

自动化部署方案

方案一：从零开始构建（适合需要完全自定义）

  1. 准备本地环境
    安装 Node.js 和 Hexo 后，创建你的博客项目：

    1
    2
    3
    npm install -g hexo-cli
    hexo init my-blog && cd my-blog
    npm install

  2. 连接GitHub仓库
    初始化Git仓库并推送到GitHub：

    1
    2
    3
    4
    git init && git add . 
    git commit -m "初始化Hexo博客"
    git remote add origin https://github.com/你的用户名/仓库名.git
    git push -u origin main

  3. 配置Cloudflare自动化部署
    在Cloudflare控制台的”Workers 和 Pages”中创建新项目，连接你的GitHub仓库。设置构建命令为 npm run build，输出目录为 public。保存后，Cloudflare会自动检测仓库变化并部署更新。

方案二：Fork模板快速启动（5分钟上线）

  1. 获取博客模板
    访问 Hexo模板仓库 并点击”Fork”，复制到你的GitHub账户。

  2. 配置Cloudflare自动化部署
    同样在Cloudflare Pages中创建项目，选择你Fork的仓库，使用相同的构建设置（命令：npm run build，目录：public）。

手动上传方案（绕过构建限制）

当你的构建次数接近每月限额时，可以采用此方法：

  1. 本地生成静态文件
    在Hexo项目目录运行：

    1
    hexo generate  # 生成public文件夹

  2. 上传生成的文件
    将整个public文件夹压缩为ZIP文件，在Cloudflare Pages创建项目时选择”手动上传”并提交该ZIP文件；或者在Cloudflare Pages中选择”手动上传”并直接选择public文件夹。

常见问题解决方案

问题：构建失败提示 hexo: not found
原因：Cloudflare环境未正确加载Hexo
解决：始终使用 npm run build 而非 hexo generate

问题：npm ERR! code EUSAGE 错误
典型日志：

1
npm ERR! `npm ci` can only install packages when your package.json...

解决步骤：

1
2
3
4
5
6
# 本地同步依赖
npm install
# 提交更新后的lock文件
git add package-lock.json
git commit -m "更新依赖"
git push

资源