Hexo 工程化配置与发布指南（Node.js / GitHub Pages / Vercel）

本文面向“可维护、可复现、可部署”的目标，给出一套 Hexo 工程化配置流程。内容覆盖：环境基线、仓库初始化、主题接入、发布链路（GitHub Pages + Vercel）以及常见故障排查。

1. 环境基线

1.1 Node.js

Hexo 运行依赖 Node.js。安装后验证：

node -v
npm -v

建议统一 npm 源（国内网络环境）：

npm config set registry https://registry.npmmirror.com
npm config get registry

1.2 Git

git --version

配置全局身份（用于 commit author）：

git config --global user.name "<your-name>"
git config --global user.email "<your-email>"
git config -l

1.3 Hexo CLI

npm install -g hexo-cli
hexo -v

---

2. GitHub 连接基线（SSH）

生成密钥：

ssh-keygen -t rsa -C "<your-email>"

复制公钥：

cat ~/.ssh/id_rsa.pub

将公钥添加到 GitHub：Settings -> SSH and GPG keys -> New SSH key。

连通性测试：

ssh -T git@github.com

---

3. 初始化 Hexo 工程

hexo init my-blog
cd my-blog
npm i

本地开发最小闭环：

hexo clean
hexo generate
hexo server

访问：http://localhost:4000

快捷写法：hexo cl && hexo g && hexo s

---

4. 项目结构与核心配置

Hexo 核心目录（简化）：

my-blog/
├── _config.yml            # 全局配置
├── package.json
├── scaffolds/
├── source/
│   ├── _posts/            # 文章
│   └── about/
└── themes/

_config.yml 推荐先完成这些字段：

title: <site-title>
subtitle: <site-subtitle>
description: <site-description>
author: <author>
language: zh-CN
timezone: Asia/Shanghai
url: https://<your-domain-or-pages-url>
permalink: :year/:month/:day/:title/

---

5. 主题接入（Fluid）

5.1 安装主题

npm install --save hexo-theme-fluid

5.2 启用主题

在根目录 _config.yml：

theme: fluid
language: zh-CN

5.3 拆分主题配置

在博客根目录创建 _config.fluid.yml，将 themes/fluid/_config.yml 内容拷贝进去后再做定制。这样升级主题时冲突更少。

5.4 关于页

hexo new page about

编辑 source/about/index.md：

---
title: about
layout: about
---

这里是关于页内容。

---

6. 发布到 GitHub Pages

6.1 创建仓库

创建仓库：<username>.github.io

6.2 安装部署插件

npm install hexo-deployer-git --save

6.3 配置 deploy

编辑根目录 _config.yml：

deploy:
  type: git
  repository: git@github.com:<username>/<username>.github.io.git
  branch: main

6.4 执行发布

hexo clean
hexo generate
hexo deploy

若输出 Deploy done，说明静态产物已推送到 Pages 仓库。

---

7. 可选：Vercel 托管

如果你希望支持更灵活的域名管理、回滚与预览环境，可接 Vercel：

1. GitHub 登录 Vercel
2. Add New -> Project
3. 导入博客仓库
4. 默认参数直接 Deploy
5. Domains 里绑定自定义域名

---

8. 故障排查

8.1 hexo: command not found

npm install -g hexo-cli

并检查 Node.js 安装路径是否在 PATH。

8.2 Permission denied (publickey)

• 检查 ~/.ssh/id_rsa.pub 是否已加入 GitHub
• 运行 ssh -T git@github.com 定位认证问题

8.3 主题不生效

• _config.yml 的 theme 与目录名一致
• 修改后执行 hexo clean && hexo generate

8.4 Deploy 无更新

• 确认 _config.yml 的 deploy.repository 指向正确仓库
• 检查分支名（main / master）是否匹配

---

9. 建议的工程实践

• 文章仓库与 Pages 产物仓库分离（源码与产物解耦）
• 主题配置放在 _config.fluid.yml，减少升级冲突
• 使用 source/_posts 统一管理内容，Front-matter 规范化
• 发布前固定执行：hexo clean && hexo generate

至此，一套可复现的 Hexo 博客工程已完成：本地开发、主题管理、GitHub Pages 发布与 Vercel 托管均可稳定运行。