Hexo博客基础

【Hexo博客系列】No.1 搭建Hexo博客，快速简洁高效，零成本搭建个人博客

Hexo + GitHub Pages + Cloudflare Pages 完整指南

本文详细介绍了如何使用 Hexo 框架搭建一个个人博客，并将其部署到 GitHub Pages 和 Cloudflare Pages 上。

本文于 2026-08-13 按 Hexo、GitHub Pages 与 Cloudflare Pages 官方文档复核。Hexo 与 Node.js 的兼容范围会继续变化：Hexo 7 最低支持 Node.js 14，但旧 Node.js 已停止维护，新安装应使用仍受支持的 Node.js LTS，并在 package-lock.json 与部署平台中固定一致的主版本。

主要内容包括：

  • 环境准备：安装 Node.js 和 Git
  • 配置 Git 和 GitHub：设置 SSH 密钥，创建 GitHub 仓库
  • 初始化 Hexo 项目：安装 Hexo，创建新博客
  • 部署到 GitHub Pages：配置部署设置，推送静态文件
  • 部署到 Cloudflare Pages：连接 GitHub 仓库，自动部署
  • 基本使用方法：创建新文章，本地预览，发布更新

这个教程适合那些想要快速搭建个人博客，但又不想花费太多成本的人。通过使用 Hexo、GitHub 和 Cloudflare 的免费服务，您可以轻松创建一个高效、简洁的博客网站。

1. 事前准备

  1. 域名（非必须）
    你也可以使用免费域名，或者直接使用 GitHub.io 或 Pages.dev 分配的域名即可

  2. GitHub （必须）
    你需要注册一个 GitHub 账号

  3. Cloudflare （非必须）
    你需要注册一个 Cloudflare 账号，这样可以将博客部署在 CF 的 CDN 里加速
    （也可以直接使用 GitHub Pages 的域名）

2. 软件支持

  1. Node （必须）
  2. Git （必须）
  3. VSCode （非必须）
    这是一款轻量型的代码编辑器，可以帮助你养成一个很好的编程习惯

2.1 安装 Node

  1. 打开 Node 官网，下载和自己系统相匹配的 LTS 安装程序。本文检查时 Node.js 24 为 Active LTS，Node.js 22 仍处于 LTS 生命周期；不要为兼容旧教程安装已经停止维护的 Node.js 14/16/18。
    下载地址：https://nodejs.org/en

  2. 下载后安装，安装目录可以使用默认目录：C:/Program Files/nodejs/

  3. 安装完成后，检查是否安装成功：
    按 win + R → 输入 CMD → 回车，打开命令提示符，执行：

    1
    node -v

    看到版本信息，则说明安装成功。

  4. 如果访问 npm 官方仓库确实很慢，可以对单次安装临时指定镜像，不必永久修改全局配置：

    1
    npm install --registry=https://registry.npmmirror.com

    官方默认仓库是 https://registry.npmjs.org/。第三方镜像的同步时效、完整性和可用性不由 npm/Hexo 保证；安装失败时先切回官方源：

    1
    npm config set registry https://registry.npmjs.org/

2.2 安装 Git

  1. 进入官网下载适合你当前系统的 Git：
    https://git-scm.com/downloads

  2. 下载后傻瓜式安装，建议使用默认目录：C:/Program Files/Git

  3. 安装完成后，开始菜单会出现：

    • Git CMD：Windows 命令行风格
    • Git Bash：Linux 系统指令风格（建议使用）
    • Git GUI：图形化界面（新手不建议使用）

3. 配置 Git 密钥并连接至 GitHub

常用 Git 命令：

1
2
3
git config -l               # 查看所有配置
git config --system --list  # 查看系统配置
git config --global --list  # 查看用户（全局）配置

3.1 配置用户名和邮箱

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

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

3.2 配置公钥连接 GitHub

  1. 生成 SSH 公钥：

    1
    ssh-keygen -t ed25519 -C "你的邮箱"

    提示保存位置时可以接受默认路径；个人电脑建议为私钥设置口令，并使用系统的 SSH Agent 管理。

    生成后，在 C:\Users\你的用户名\.ssh\ 目录下会出现：

    • id_ed25519 （私钥，绝不能上传或发给别人）
    • id_ed25519.pub （公钥）

    用记事本打开 id_ed25519.pub，复制全部内容。

  2. 将公钥添加到 GitHub：

    • 登录 GitHub → 右上角头像 → Settings → SSH and GPG keys → New SSH key
    • 名字随便起，Key 栏粘贴刚才复制的公钥内容 → Add SSH key

  3. 测试连接：

    1
    ssh -T [email protected]

    第一次会提示 Are you sure you want to continue connecting (yes/no/[fingerprint])?，输入 yes 回车。
    出现类似 Hi xxx! You've successfully authenticated... 的信息，即连接成功。

3.3 创建 GitHub Pages 仓库

  1. 点击右上角 + → New repository
  2. 如果要创建用户主页，仓库名应为 <你的用户名>.github.io；普通项目站点也可以使用其他仓库名，访问路径会包含仓库名
  3. 可见性选择 Public（方便第一次部署检查问题）
  4. 点击 Create repository

4. 初始化 Hexo 博客

  1. 创建一个文件夹存放博客源码（示例：D:/Hexo-Blog），右键文件夹 → Open Git Bash here

  2. 安装 Hexo：

    1
    npm install -g hexo-cli && hexo -v

  3. 验证安装：hexo -v

  4. 初始化项目：

    1
    2
    3
    hexo init blog-demo
    cd blog-demo
    npm install

  5. 项目目录结构大致如下：

    • node_modules：依赖包
    • scaffolds：生成文章的模板
    • source：存放你的文章
    • themes：主题
    • _config.yml：博客核心配置文件
    • package.json：项目信息

  6. 启动本地预览：

    1
    2
    3
    hexo clean && hexo server
    # 或简写
    hexo cl && hexo s

  7. 浏览器访问：http://localhost:4000/
    看到页面说明本地环境搭建成功。

5. 将静态博客挂载到 GitHub Pages

  1. 安装部署插件：

    1
    npm install hexo-deployer-git --save

  2. 修改根目录 _config.yml 文件，最后部分改为：

    1
    2
    3
    4
    deploy:
      type: git
      repository: [email protected]:你的用户名/你的用户名.github.io.git
      branch: main

    注意缩进正确，使用 SSH 地址，分支现在一般为 main。

  3. 部署三连命令：

    1
    2
    3
    # Git Bash
    hexo clean && hexo generate && hexo deploy

    1
    2
    # PowerShell
    hexo clean; hexo generate; hexo deploy

    出现 Deploy done 即部署完成。

    稍等几分钟，访问：https://你的用户名.github.io

6. 将静态博客挂载到 Cloudflare Pages

Cloudflare Pages 应连接 Hexo 源码仓库，其中至少要有 package.json、锁文件、source/、主题和配置；不要连接 hexo deploy 生成的纯静态仓库。先把源码提交到一个单独仓库（例如 blog-source），并确保 .gitignore 排除了 node_modules/、public/、db.json 和本地密钥。

  1. 登录 Cloudflare → Workers & Pages → Create application → Pages → Import an existing Git repository。
  2. 授权并选择 Hexo 源码仓库。
  3. 设置生产分支为 main。
  4. 设置构建命令为 npm run build，构建输出目录为 public。
  5. 如果主题或插件要求特定 Node.js 版本，在项目变量中设置 NODE_VERSION；应与本地验证所用的 LTS 主版本一致。
  6. 点击 Save and Deploy。成功后访问 https://你的项目名.pages.dev，再按需绑定自定义域名。

以后推送源码提交会触发自动构建。构建失败时先检查依赖锁文件、主题是否完整包含在仓库或子模块中，以及日志里第一处有效错误。

如何使用

新建一篇博文

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

编辑文件：source/_posts/这是一篇新的博文.md
使用 Markdown 语法书写。
参考：https://hexo.io/zh-cn/docs/writing

本地预览

1
2
# Git Bash
hexo cl && hexo s
1
2
# PowerShell
hexo cl; hexo s

访问 http://localhost:4000/

发布更新

1
2
# Git Bash
hexo cl && hexo g && hexo d
1
2
# PowerShell
hexo cl; hexo g; hexo d

VSCODE 终端首次执行报错解决

如果 PowerShell 报“禁止运行脚本”，先确认命令来自可信安装。一般无需管理员权限，也不应修改整台机器的策略；只为当前用户设置：

1
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

只想在当前终端临时验证时，可以使用 -Scope Process；关闭终端后即失效。企业或学校电脑受组策略管理时，不要绕过管理员策略。

参考资料

致谢