Hexo + GitHub Pages 个人博客搭建 | 世傲命的技术观测站

这篇文章记录第一次从零搭建 Hexo + GitHub Pages 个人博客的过程。它不是官方文档的逐字复述，而是一份面向实操的过程笔记：每一步为什么要做、做完以后怎么验证、遇到问题时先查哪里。

早期个人博客最重要的不是主题有多复杂，而是先把发布链路跑通。只要能稳定做到“本地写 Markdown -> 生成静态页面 -> 推送 GitHub Pages -> 线上访问”，后续再换主题、加图床、加评论、加搜索都比较可控。

整体链路

Node.js / npm
  -> Hexo CLI
  -> 本地 blog 源码目录
  -> hexo generate 生成 public/
  -> hexo-deployer-git 推送到 GitHub Pages 仓库
  -> https://Shiaoming123.github.io/

这里有两个目录概念需要先分清：

目录	作用	是否直接写文章
Hexo 源码目录	保存 `_config.yml`、主题、Markdown 文章、图片	是
GitHub Pages 发布仓	保存构建后的 HTML/CSS/JS/图片	否

当时我还是把 Hexo 发布仓直接当作最终站点使用。现在博客已经迁移到 Astro，但这篇记录仍然有参考价值：它保留了静态博客部署的基本心智模型。

环境准备

需要准备四类工具：

工具	用途	验证方式
Node.js	提供 Hexo 运行环境	`node -v`
npm	安装 Hexo CLI 和依赖	`npm -v`
Git	管理源码和部署	`git --version`
GitHub Pages	托管静态站点	访问 `username.github.io`

先进入 Node.js 官网下载 Windows 安装包。

Node.js 官网下载页面

安装流程基本保持默认即可。需要注意的是安装路径：如果你习惯把开发工具集中放在某个盘符，可以在安装向导里修改路径，避免后续找不到 Node 或 npm。路径截图通常会暴露本机用户名或目录结构，公开博客里不建议放原图。

Node.js 安装向导

安装向导里会出现是否自动安装额外构建工具的选项。刚开始搭 Hexo 不一定需要，保持默认即可；等以后遇到原生依赖编译问题，再单独处理。

Node.js 可选工具安装项

安装完成后打开 PowerShell，检查 Node 和 npm 是否可用：

node -v
npm -v

如果命令不可用，优先检查三件事：

Node.js 是否安装成功。
是否重新打开了一个新的终端窗口。
Path 环境变量里是否包含 Node.js 安装目录。

安装 Hexo CLI

Hexo CLI 是创建、生成和预览博客的命令行工具。可以直接使用 npm 安装：

npm install -g hexo-cli

如果网络访问 npm 官方源较慢，可以换镜像源。旧环境里我曾经使用过 cnpm：

npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g hexo-cli

安装完成后检查 Hexo 版本：

hexo -v

能看到 Hexo、Node、npm 等版本信息，就说明基础环境已经可用。

初始化博客源码目录

选择一个你能长期维护的目录放博客源码。不要把源码随手放在下载目录或桌面临时文件夹里，否则后续迁移、备份和排错都会很麻烦。

示例：

mkdir blog
cd blog
hexo init
npm install

初始化完成后，目录里会生成 Hexo 所需的基础文件。由于终端截图通常会带出本机路径，公开文章里直接列目录结构更清晰：

核心文件说明如下：

文件或目录	作用
`_config.yml`	Hexo 主配置
`package.json`	npm 依赖和脚本
`source/_posts`	Markdown 文章目录
`themes`	主题目录
`public`	构建输出目录，生成后出现

本地预览：

hexo clean
hexo generate
hexo server

浏览器打开 http://localhost:4000/，如果看到默认页面，就说明本地生成和预览链路正常。

Hexo 默认本地预览页面

常用命令可以记成下面这组：

hexo clean      # 清理缓存和旧产物
hexo generate   # 生成静态文件，可简写为 hexo g
hexo server     # 本地预览，可简写为 hexo s
hexo deploy     # 部署到远程，可简写为 hexo d
hexo new post "文章标题"

Hexo 常用命令帮助信息

创建第一篇文章

推荐用 Hexo 命令创建文章，而不是手写空 Markdown 文件。这样 frontmatter 更稳定：

hexo new post "我的第一篇博客文章"

文章会生成在：

source/_posts/

一篇基础文章通常长这样：

---
title: 我的第一篇博客文章
date: 2025-06-22 18:00:00
tags:
  - Hexo
categories:
  - 博客建设
---

这里写正文。

写完后重新执行：

hexo clean
hexo generate
hexo server

如果本地能看到新文章，再进入部署环节。这个顺序很重要：先本地验证，再推线上，能节省很多排错时间。

创建 GitHub Pages 仓库

用户站点仓库命名格式是：

<username>.github.io

例如：

Shiaoming123.github.io

GitHub 创建新仓库

仓库创建后，GitHub Pages 会把这个仓库的指定分支作为静态站点来源。用户站点通常直接使用 main 分支根目录。

GitHub Pages 仓库创建完成

这一步最常见的问题是仓库名写错。用户站点必须严格匹配 username.github.io，大小写虽然在 URL 上通常不敏感，但仓库名最好保持一致。

配置 Hexo 部署

安装部署插件：

npm install hexo-deployer-git --save

然后编辑 _config.yml 末尾的 deploy 配置：

deploy:
  type: git
  repo: git@github.com:Shiaoming123/Shiaoming123.github.io.git
  branch: main

Hexo 部署配置示意

在配置文件中填写 deploy 字段

配置完成后执行：

hexo clean
hexo generate
hexo deploy

如果使用 SSH 地址，必须提前配置好 GitHub SSH key。第一次部署失败时，先看错误信息属于哪一类：

错误表现	常见原因	处理方向
`Permission denied (publickey)`	SSH key 未配置或未加入 GitHub	重新生成并添加 SSH key
`unable to auto-detect email address`	Git 用户名邮箱未配置	设置 `git config --global user.email`
页面没有更新	deploy 没推成功或 Pages 延迟	看发布仓 commit 和 Pages 状态
图片不显示	图片没提交、路径错误、图床不可访问	检查文件是否真的存在

切换主题

Hexo 默认主题只适合验证流程。等部署链路跑通后，可以再换主题。早期常见选择有 yilia、NexT、Butterfly 等。

Hexo 主题效果参考

以 yilia 为例：

git clone https://github.com/litten/hexo-theme-yilia.git themes/yilia

然后修改 _config.yml：

theme: yilia

主题切换后重新生成：

hexo clean
hexo generate
hexo server

主题配置经常会出现“改了但没生效”的情况。排查顺序是：

确认改的是 Hexo 根目录的 _config.yml，不是主题目录里的配置。
执行过 hexo clean。
本地预览是否已经重启。
主题版本是否和当前 Hexo 版本兼容。

图片管理和 PicGo

技术博客一旦开始写教程，图片管理就会变成长期问题。图片可以放在本地源码里，也可以放图床。早期我使用 PicGo + GitHub 仓库做图床。

PicGo 官网

PicGo 下载页面

PicGo 配置 GitHub 图床时通常需要这些字段：

配置项	说明
仓库名	例如 `Shiaoming123/Picgo_image`
分支名	通常是 `main`
存储路径	例如 `img/`
自定义域名	可使用 raw 链接或 CDN
token	只保存在本地配置，不写进文章

这里有一个很重要的经验：图床不是备份。图床链接一旦权限变化、仓库改私有、CDN 规则变化，公开文章里的图片就会失效。更稳妥的方式是：

原图保留在博客源码或可备份目录。
公开文章优先引用本地构建资产。
图床只作为分发层，不作为唯一存储。

这次博客迁移时就遇到了这个问题：旧文章引用的 PicGo raw 链接公网返回 404，但图片本身还在 Picgo_image 仓库里。最终的修复方式是把确认安全的截图复制回博客源码 public/images/legacy/hexo-github-blog-setup/，让页面不再依赖私有图床外链。

发布前检查清单

每次发布前可以按这个顺序检查：

hexo clean
hexo generate
hexo server

本地确认：

首页能打开。
新文章出现在列表里。
文章标题、目录、代码块、表格正常。
图片不是破图。
外链能打开。
没有把 token、私钥、账号敏感信息截图发出去。

线上确认：

发布仓出现新 commit。
https://Shiaoming123.github.io/ 能看到更新。
文章 URL 能直接打开。
RSS、sitemap、搜索索引能生成。

迁移后的复盘

Hexo 适合快速建立静态博客，但随着内容变多，长期维护会遇到几个问题：

主题和插件版本容易老化。
生成 HTML 不适合作为长期编辑源。
图片如果依赖外链，迁移时容易断。
文章 frontmatter、标签、分类需要统一规范。

这也是后来把博客迁移到 Astro 源码站点的原因：Markdown、内容集合、构建校验和静态部署链路更清晰。Hexo 这篇文章保留的是第一次搭建博客的完整过程，也提醒自己：发布链路可以简单，但源码、图片和内容结构必须从一开始就可维护。