20.内容拓展：后台管理系统：Hexo Pro 集成指南

Hexo Pro 全方位指南：安装、排错与部署

1. 前言：为什么选择 Hexo Pro？

Hexo Pro 是专为 Hexo 博客打造的后台管理系统插件。传统的 Hexo 写作需要直接编辑 Markdown 文件并使用命令行操作，这对非技术背景的用户或希望提高效率的创作者来说可能不够直观。

安装 Hexo Pro 后，您将获得一个可视化的网页后台，轻松实现：

  • 可视化写作：像使用 Word 一样撰写和编辑文章。
  • 媒体管理：直接上传和管理图片。
  • 配置修改：通过图形界面调整博客设置。

2. 环境准备与安装

2.1 环境检查

在开始之前，请确保您的开发环境满足以下基础要求：

  • Hexo 版本: 7.x 或更高（终端运行 hexo version 查看）。
  • Node.js 版本: 建议 23 或更高（终端运行 node -v 查看）。
  • ⚠️ 注意：Node.js 20.x 版本存在已知兼容性问题，请务必阅读后文的“故障排除”章节。

2.2 安装插件

在您的 Hexo 博客 根目录 下打开终端，运行：

1
npm install hexo-pro --save

2.3 启动服务

安装完成后，使用特定的参数启动本地服务：

1
hexo server

2.4 访问与初始化

当终端显示 Hexo is running at http://localhost:4000/ 后：

  1. 浏览器访问：http://localhost:4000/pro/
  2. 设置管理员：首次访问时，系统会提示您创建一个管理员账户。为了安全起见，强烈建议 您设置强密码，不要跳过此步骤。

3. 常见问题：ES Module 错误排查与修复

在使用 Node.js 20.x 搭配 Hexo 7.x 时，许多用户在启动或加载 Hexo Pro 时会遇到严重的崩溃错误。

3.1 错误现象

终端或 Hexo Pro Desktop 可能会抛出如下错误信息：

Error [ERR_REQUIRE_ESM]: require() of ES Module .../strip-ansi/index.js not supported.

img

或者提示 Console 未注册：

加载项目失败: Console server has not been registered yet!

img

3.2 问题根源

这是一个典型的 CommonJS 与 ES Module (ESM) 冲突：

  1. Hexo 7.x 机制：Hexo 核心仍主要使用 require() (CommonJS) 方式加载插件。
  2. 依赖包升级：Hexo 的底层依赖包（如 strip-ansi）在其新版本中已完全转为 ES Module。
  3. Node.js 限制：Node.js 20.x 严格遵守规范，禁止通过 require() 加载 ESM 模块，导致程序崩溃。

3.3 解决方案

您可以根据实际情况选择以下任意一种方案修复：

方案 A：升级 Node.js 版本（推荐，最简便）

Node.js 23+ 默认开启了 require(esm) 支持，可以自动处理这种兼容性问题。

  1. 前往 Node.js 官网或使用 nvm 将 Node.js 升级到 v23.0.0 或更高版本。
  2. 重新运行 hexo server -d 即可解决。

方案 B：锁定依赖版本（兼容性方案）

如果您必须停留在 Node 20.x 环境，可以通过修改 package.json 强制使用旧版兼容的依赖包。

  1. 打开博客根目录的 package.json 文件。
  2. 添加 overrides 字段，锁定 strip-ansi 为 CommonJS 兼容版本（6.0.1）：
1
2
3
4
5
6
7
8
9
10
{
  "dependencies": {
    "hexo": "^7.3.0",
    "hexo-pro": "..."
  },
  "overrides": {
    "strip-ansi": "6.0.1"
  }
}

  1. 删除 node_modules 文件夹和 package-lock.json 文件。
  2. 重新运行 npm install。

4. 部署实战：发布到 GitHub Pages

当您在 Hexo Pro 后台写好文章后，下一步就是将其发布到互联网。最经典且免费的方案是 GitHub Pages。

4.1 准备工作：SSH 配置与验证

为了让 Hexo 能够自动把代码传到 GitHub，您必须配置 SSH 密钥。

  1. 检查现有的 SSH Key：在终端输入：
1
ls -al ~/.ssh

如果看到 id_rsa 和 id_rsa.pub，说明已有密钥。如果没有，请生成：

1
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

(按三次回车即可)

  1. 添加公钥到 GitHub：
  • 查看公钥内容：cat ~/.ssh/id_rsa.pub
  • 复制所有内容。
  • 进入 GitHub -> Settings -> SSH and GPG keys -> New SSH key，粘贴并保存。

image-20260103100251979

  1. 关键步骤：验证连接
    在终端输入以下命令进行核验，这是确保部署成功的关键：
1
ssh -T git@github.com
  • 如果是第一次连接，输入 yes。
  • 如果您看到 Hi [Username]! You've successfully authenticated...，说明连接成功。

4.2 创建 GitHub 仓库

  1. 登录 GitHub，创建一个新仓库。
  2. 仓库名称（重要）：必须命名为 您的用户名.github.io。
  • 例如：如果是用户 Lazzz, 仓库名必须是 Lazzz.github.io。

4.3 配置 Hexo

  1. 安装 Git 部署插件：
1
npm install hexo-deployer-git --save
  1. 修改根目录下的 _config.yml 文件：
1
2
3
4
5
deploy:
  type: git
  # 务必使用 SSH 地址 (以 git@ 开头)，不要使用 HTTPS
  repo: git@github.com:您的用户名/您的用户名.github.io.git
  branch: main

4.4 一键部署

在终端（或 Hexo Pro 后台的部署按钮）执行：

1
hexo clean && hexo g -d
  • hexo clean: 清理缓存。
  • hexo g: 生成静态网页。
  • hexo d: 推送到 GitHub。

4.5 开启 Pages 服务

  1. 进入 GitHub 仓库页面 -> Settings -> Pages。
  2. 在 Build and deployment 下：
  • Source 选择 Deploy from a branch。
  • Branch 选择 main 分支的 /(root) 目录。
  1. 保存后等待约 1-3 分钟，访问 https://您的用户名.github.io 即可看到您的博客。

5. 日常使用流程总结

配置完毕后，您的日常博客维护流程将变得非常流畅：

  1. 启动：在终端运行 hexo server -d。
  2. 写作：访问 http://localhost:4000/pro/ 进行创作和排版。
  3. 部署：文章写完后，在终端运行 hexo g -d 发布上线。