一、为什么选择 GitHub Pages + Hexo
如果你的目标是快速拥有一个可长期维护、成本低、适合写技术笔记和科研博客的网站，那么 GitHub Pages + Hexo 是一套很稳的方案。
这套组合的优点很直接：
- 免费托管静态站点
- 内容以 Markdown 为主，适合长期写作
- 可以放在 Git 仓库里版本管理
- 主题丰富，定制空间大
- 非常适合个人主页、科研博客、学习笔记、项目展示
你当前这个仓库用的就是这条路线，并且已经调整为：
main直推- GitHub Actions 自动构建
- GitHub Pages 自动发布
- 主题为
matery
二、整体流程先看懂
真正跑起来之后，日常流程其实只有这一条：
- 在本地修改
source/下的 Markdown 和页面文件 - 执行
hexo generate本地检查 - 推送到 GitHub 的
main分支 - GitHub Actions 自动构建并发布到 Pages
也就是：
1 | hexo clean |
如果你使用本仓库里的菜单脚本，也可以直接运行：
1 | ./hexo_menu.sh |
三、准备工作
开始前你需要准备这些环境：
- 一个 GitHub 账号
- 本地安装好
Git - 本地安装好
Node.js - 本地安装好
VSCode
建议版本：
- Node.js:
18或20 - npm: 跟随 Node.js
- Git: 最新稳定版
检查命令：
1 | node -v |
四、创建 GitHub 仓库
1. 用户主页仓库 和 项目仓库的区别
GitHub Pages 有两种常见形式：
- 用户主页仓库
仓库名固定为：
1 | <你的用户名>.github.io |
这种仓库通常部署后直接挂在根域名下，例如：
1 | https://yourname.github.io/ |
- 项目仓库
仓库名可以自定义，例如：
1 | jianbo-yuan |
部署后地址一般是：
1 | https://jianbo-yuan.github.io/jianbo-yuan/ |
你当前项目属于第二种，所以根路径不是 /，而是：
1 | url: https://jianbo-yuan.github.io/jianbo-yuan |
2. 新建仓库
去 GitHub 新建一个仓库，建议：
- 如果你做个人主页：仓库名用
<用户名>.github.io - 如果你做项目博客：仓库名自定义即可
创建完成后，把仓库 clone 到本地：
1 | git clone https://github.com/yourname/your-repo.git |
五、初始化 Hexo
如果你是从零开始，可以这样初始化：
1 | npm install hexo-cli -g |
初始化后会生成标准 Hexo 目录：
1 | _config.yml |
常用命令：
1 | hexo clean |
本项目里也定义了 npm 脚本：
1 | npm run clean |
六、切换或安装主题
你当前仓库已经启用了 matery 主题：
1 | theme: matery |
如果从零开始安装主题，一般流程是：
- 下载主题到
themes/ - 修改站点根目录
_config.yml - 按主题文档补充主题配置
以当前项目为例，主配置文件是：
- 站点配置：_config.yml
- 主题配置：themes/matery/_config.yml
七、配置站点基础信息
至少需要改这几项：
1 | title: Jianbo.Yuan |
这里最容易出错的是 url 和 root：
- 如果是用户主页仓库，通常
root: / - 如果是项目仓库，通常
root: /仓库名/
如果这里错了，静态资源路径和页面跳转很容易异常。
八、配置 GitHub Pages 自动部署
你当前仓库已经使用 GitHub Actions 自动部署，工作流文件在：
核心逻辑是：
1 | on: |
也就是说：
- 你推送
main - GitHub 自动执行
npm ci - 自动执行
npx hexo generate - 自动把
public/发布到 GitHub Pages
仓库侧还要确认两件事
- 仓库默认分支是
main - GitHub Pages 的 Source 选择
GitHub Actions
如果你已经有这个工作流，但页面不更新，第一时间去看：
- 仓库的
Actions页面 - 最近一次工作流日志
九、创建基础页面
Hexo 常见独立页面包括：
- 关于页
- 分类页
- 标签页
- 归档页
- 留言板
- 友情链接
新建方式：
1 | hexo new page "about" |
然后在对应的 index.md 里写 front matter，例如分类页：
1 |
|
十、如何写文章
1. 新建文章
标准命令：
1 | hexo new post "文章标题" |
你当前仓库还提供了一个向导式菜单：
1 | ./hexo_menu.sh |
在菜单里选择：
1 | 9. 新建文章向导 |
它会让你输入：
- 文章标题
- 内容简介
- 一级分类
- 二级分类
并且可以：
- 从已有分类中选择
- 直接新增一级分类
- 直接新增二级分类
2. 推荐 front matter 写法
当前项目推荐你至少写这些字段：
1 |
|
3. 一级分类和二级分类怎么写
Hexo 官方 front-matter 文档说明：categories 按顺序形成层级关系。
例如：
1 | categories: |
它表示：
1 | 科研工具 > 网站类 |
如果你要写多条独立的分类层级，可以用数组写法：
1 | categories: |
但对大多数博客来说，一篇文章只保留一条主分类链路就够了。
5. 如何在网站分类页显示所有分类目录列表
如果你希望在 /categories/ 页面中，不只是看到分类云或统计图，而是直接看到完整的分类目录清单，可以在主题的分类页模板中增加一个“分类目录树”模块。
当前这个仓库已经这样做了，相关文件是：
实现思路很简单：
- 遍历
site.categories - 按分类路径排序
- 输出每个分类的：
- 分类名
- 分类路径
- 文章数
- 在分类页中插入这个 widget
这样你的分类页就会自动显示所有分类目录，而不需要手工维护。
要注意的是，只有当文章 front matter 里的分类写法正确时，分类目录树才能正确显示层级关系。例如：
1 | categories: |
或者：
1 | categories: |
不要写成下面这种缩进错误的形式：
1 | categories: |
这种写法很容易被解析成一个扁平分类名，最终显示成：
1 | 科研工具 - 网站类 |
而不是你真正想要的两级目录。
4. 标签怎么写
标签是平级的，没有层级关系：
1 | tags: |
十一、如何设置文章主图、首页封面和摘要
你当前主题是 matery，它对这些字段有明确支持：
imgcovercoverImgsummary
主题文档里对应说明可参考：
1. 文章卡片主图
1 | img: /medias/featureimages/3.jpg |
作用：
- 首页文章卡片图
- 分类页文章图
- 归档页文章图
2. 是否加入首页轮播封面
1 | cover: true |
3. 首页轮播封面图
1 | coverImg: /medias/featureimages/7.jpg |
如果不写 coverImg，通常会回退到 img。
4. 自定义摘要
1 | summary: 这是文章摘要，会显示在首页卡片和部分列表页中。 |
如果不写，主题通常会自动截取正文内容。
5. 一份更完整的 front matter 示例
1 |
|
十二、文章图片怎么放
当前项目里 post_asset_folder 还是：
1 | post_asset_folder: false |
所以更稳妥的方式是统一把文章图片放到公共目录，再用绝对路径引用，例如：
1 |  |
如果你以后想做“每篇文章一个配套图片文件夹”，可以把：
1 | post_asset_folder: true |
打开，但那会改变后续文章资源管理方式。
十三、在 VSCode 中编辑 Markdown
推荐安装这些扩展：
Markdown All in OneMarkdown Preview EnhancedPaste Image
常用预览方式：
Ctrl + Shift + V：打开预览Ctrl + K V：侧边预览
这样你可以一边写 Markdown，一边看渲染效果。
十四、如何插入公式
行内公式：
1 | 这是行内公式 $E = mc^2$。 |
块级公式：
1 | $$ |
如果要让博客页面也显示公式，你需要两步：
- 打开主题全局开关
1 | mathjax: |
- 在文章 front matter 中开启
1 | mathjax: true |
十五、常用写作与维护命令
本项目里最常用的是这些命令：
1 | npm run clean |
如果你偏向 Git 直推工作流：
1 | git add . |
十六、常见问题
1. 页面样式错乱、图片不显示
优先检查：
_config.yml的url_config.yml的root- GitHub Pages 是否用的是
GitHub Actions
2. 推送了 main，但页面没更新
检查：
- GitHub
Actions页面是否执行成功 - workflow 是否监听
main - Pages 设置是否正确
3. 分类显示不对
先确认 front matter 里的写法是否正确，例如：
1 | categories: |
不要混用错误缩进形式，否则分类层级可能解析异常。
4. 文章没有主图
检查是否写了：
1 | img: /medias/featureimages/1.jpg |
如果没写，matery 通常会自动从主题默认图里取一张。
十七、建议的长期维护方式
对于个人博客，建议你把维护动作收敛为下面几步：
- 在 VSCode 里写 Markdown
- 使用规范的 front matter
- 本地执行
npm run build - 确认无误后推送
main - 让 GitHub Actions 自动发布
这样你的博客会比较稳定，后续增加文章、页面、分类、主图、公式都不会乱。
十八、结语
如果你只是想快速上线个人博客，那么最重要的是先把下面四件事做对：
- 仓库创建正确
_config.yml的url/root正确- 文章 front matter 写规范
main推送后能够自动触发 GitHub Pages
这四件事一旦稳定下来，后面主题优化、文章积累、页面扩展都会轻松很多。
