Hexo + Matery 主题从零搭建个人博客完整教程（GitHub Pages 部署 + 美化优化全流程）

为什么选 Hexo + Matery？

Hexo 是一个基于 Node.js 的静态博客框架，一条命令就能把 Markdown 文章生成完整的 HTML 站点。Matery 是 Hexo 生态中最受欢迎的 Material Design 风格主题之一，自带响应式布局、暗黑模式、代码高亮、相册灯箱、搜索、评论等全套功能。

相比 WordPress 需要服务器和数据库，Hexo 的纯静态方案配合 GitHub Pages 零成本、免运维、加载快，非常适合个人博客。

本教程最终效果预览：https://ryancoreai.github.io

读完这篇教程，你将拥有一个完全免费、加载飞快、可深度定制的个人博客站点。

一、环境准备

1.1 安装 Node.js

• 官网：https://nodejs.org/
• 下载 LTS（长期支持版），一路 Next 默认安装即可
• 验证安装（打开终端或 Git Bash）：

node -v
npm -v

1.2 安装 Git

• 官网：https://git-scm.com/
• 默认安装，验证：

git --version

1.3 注册 GitHub 账号

• 注册地址：https://github.com/

二、创建 GitHub 仓库（关键：命名规则）

1. 登录 GitHub → 右上角 + → New repository
2. 仓库名必须严格写：你的用户名.github.io
   • 例：用户名是 peter-create-ai → 仓库名 peter-create-ai.github.io
3. 选 Public
4. 其他默认 → Create repository

这个仓库就是你的博客站点入口，GitHub 会自动把它识别为 GitHub Pages 站点。

三、安装 Hexo 并初始化博客

3.1 换国内镜像（下载提速）

npm config set

3.2 全局安装 Hexo

npm install -g hexo-cli

验证：

hexo -v

3.3 创建博客项目

hexo init blog
cd
npm install

完成后目录结构：

blog/
├── _config.yml        # 全局配置文件（核心）
├── source/
│   └── _posts/        # 文章 Markdown 放这里
├── themes/            # 主题目录
├── scaffolds/         # 文章模板
└── package.json       # 插件依赖

四、安装必备插件

在博客根目录 (blog/) 执行以下命令：

4.1 部署插件

npm install hexo-deployer-git --save

将生成的静态文件推送至 GitHub Pages。

4.2 搜索插件

npm install hexo-generator-search --save

生成 search.xml，供 Matery 主题的本地搜索功能使用。

4.3 中文链接转拼音

npm i hexo-permalink-pinyin --save

文章标题包含中文时，URL 自动转为拼音，避免链接中出现乱码。

4.4 RSS 订阅 + 站点地图（SEO 优化）

npm install hexo-generator-feed --save
npm install hexo-generator-sitemap --save

这两个插件为搜索引擎提供标准化的内容索引，利于收录。

4.5 静态资源压缩（加载速度优化）

npm install hexo-all-minifier --save

自动压缩 HTML、CSS、JS、图片，显著减少页面体积。

五、配置 _config.yml（核心步骤）

用编辑器打开 blog/_config.yml，按以下内容修改：

5.1 网站基本信息

title:
subtitle:
description:
keywords:
author:
language:
timezone:

# URL 配置
url:
root:
permalink:
permalink_defaults:
pretty_urls:
  trailing_index:
  trailing_html:

5.2 文章与分页

new_post_name:
default_layout:
titlecase:
external_link:
  enable:
  field:
filename_case:
render_drafts:
post_asset_folder:
relative_link:
future:
highlight:
  enable:
prism_plugin:
  mode:
  theme:
  line_number:
index_generator:
  path:
  per_page:
  order_by:

关键点：

• post_asset_folder: false —— 图片统一管理更方便（见下文图片管理章节）
• highlight.enable: false —— 关闭 Hexo 默认高亮，改用主题自带的 Prism

5.3 搜索配置

search:
  path:
  field:

5.4 中文链接转拼音配置

permalink_pinyin:
  enable:
  separator:

5.5 RSS 配置

feed:
  enable:
  type:
    -
    -
  path:
    -
    -
  limit:
  content:
  content_limit:
  order_by:
  autodiscovery:

5.6 Sitemap 配置

sitemap:
  path:
  template:
  rel:
  tags:
  categories:

5.7 部署配置（到你的 GitHub 仓库）

deploy:
  type:
  repo:
  branch:

把所有 peter-create-ai 替换成你自己的 GitHub 用户名。

六、安装并启用 Matery 主题

6.1 下载主题

cd
git clone
cd

6.2 启用主题

在 _config.yml 中修改：

theme:

七、配置 Matery 主题（themes/matery/_config.yml）

Matery 主题有自己的配置文件 themes/matery/_config.yml，一定要改，否则首页显示的是默认信息。

7.1 首页个人信息

# 首页大图轮播
cover:
  enable:
  length:
  showTitle:

# 头像 & 社交链接
profile:
  avatar:
  name:
  socialLinks:
    -
      url:
    -
      url:

7.2 导航菜单

menu:
  Home:
  Archives:
  Categories:
  Tags:
  About:
  Friends:
  # 不需要的注释掉即可

7.3 文章与代码块配置

# 文章展示
postInfo:
  date:
  update:
  wordCount:
  totalCount:
  min2read:
  readCount:

# 代码块功能
code:
  break:
  lang:
  copy:
  shrink:

7.4 评论系统（推荐 Giscus）

# Giscus —— 基于 GitHub Discussions，免费、无广告、开源
giscus:
  enable:
  repo:
  repoID:
  category:
  categoryID:

申请 Giscus 非常简单：访问 giscus.app，填入仓库名，自动生成配置。

7.5 搜索 & 打赏

# 本地搜索（需 hexo-generator-search 插件）
search:
  enable:

# 打赏
reward:
  enable:
  QRCode:
    -
    -

7.6 首页文章摘要

Matery 默认在首页显示文章全文，建议配合 <!-- more --> 使用摘要截断：

这是文章开头，会显示在首页卡片中。

<!-- more -->

从这里开始的内容，需要点击文章进去才能看到。

八、创建 Matery 必需的页面

Matery 主题依赖以下页面结构，逐个创建：

7.1 分类页

hexo new page categories

编辑 source/categories/index.md：

---
title: categories
type: "categories"
layout: "categories"
---

7.2 标签页

hexo new page tags

编辑 source/tags/index.md：

---
title: tags
type: "tags"
layout: "tags"
---

7.3 关于页

hexo new page about

编辑 source/about/index.md：

---
title: about
type: "about"
layout: "about"
---

内容自由发挥，放自我介绍、联系方式等。

7.4 友链页

hexo new page friends

编辑 source/friends/index.md：

---
title: friends
type: "friends"
layout: "friends"
---

九、文章图片管理方案（推荐）

在 source/ 下创建 images/ 文件夹，所有图片统一放在这里：

source/
├── images/
│   ├── avatar.png
│   └── blog01.jpg
└── _posts/
    └── 你的文章.md

文章内引用图片

格式固定：

![图片描述

示例：

![博客配图

建议分类管理

图片多了可以建子目录：

![生活照
![学习笔记

图片命名规则

• 使用英文 + 数字命名，如 blog01.jpg
• 避免中文和空格
• 建议压缩后再上传（推荐在线工具 TinyPNG 或 squoosh）

为什么不用 post_asset_folder？
每次新建文章自动创建同名文件夹会分散图片管理。统一放在 /images/ 下，路径固定、好找、可复用。

十、写第一篇完整文章

9.1 新建文章

hexo new "我的第一篇博客"

生成文件：source/_posts/我的第一篇博客.md

9.2 文章 Front-matter 完整写法

---
title: 我的第一篇博客
date: 2026-05-10 12:00:00
categories: 生活
tags:
  -
  -
top: true       # 置顶，放在首页最上面
cover: true     # 首页轮播大图展示
toc: true       # 显示文章目录（默认就是 true）
---

9.3 Matery 文章专属配置项

9.4 Markdown 正文示例

以下是文章正文的常见写法，直接复制模板修改即可：

二级标题和段落

## 二级标题 后用空行分隔正文。正文直接写，无需额外标记。

列表

-
-
  -

插入图片

![插图

文字样式

**加粗文字**

引用块

> 学而不思则罔，思而不学则殆

行内代码

用 `hexo server`

Java 代码块

```java
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
```

提示：展示 “如何在 Markdown 里写代码块” 时，外层用四个反引号 ```` `````` ` 包裹，内层的三个反引号就不会被解析为结束标记。

写好文章后，配合 Matery 的目录导航和代码高亮，阅读体验就是上面这样。

十一、本地预览

hexo server

浏览器打开 http://localhost:4000

边写边预览，修改保存后页面自动刷新。按 Ctrl+C 停止服务。

十二、发布上线

11.1 一键部署命令

hexo clean && hexo g && hexo d

命令含义：

• hexo clean —— 清空旧生成的静态文件
• hexo g (generate) —— 生成新的静态 HTML
• hexo d (deploy) —— 推送至 GitHub Pages

11.2 访问博客

https://你的用户名.github.io

部署后等待 1-2 分钟，GitHub Pages 会自动刷新。

部署成功后，你的博客主页大概长这样。Matery 的大图轮播 + Material Design 卡片布局，颜值在线。

十三、部署英文作品集（进阶：单仓库多站点）

如果你的英文作品集（Portfolio）也需要上线，可以和博客共用一个 GitHub Pages 仓库：

1. 单独创建一个 Portfolio 项目，使用 Cactus 或其他主题
2. Portfolio 的 _config.yml 中设置 root: /portfolio/
3. 在博客部署前，把 Portfolio 的 public/ 复制到博客的 public/portfolio/ 下

这样就能同时拥有：

• 中文博客：https://用户名.github.io
• 英文作品集：https://用户名.github.io/portfolio/

十四、主题美化：统一配色方案

Matery 默认使用绿色作为主题色。以下是以紫色（#8b5cf6）为例的替代方案。

13.1 修改的完整文件清单

13.2 颜色映射表

13.3 批量查找替换命令（Bash）

# 在 themes/matery 目录下查找所有绿色残留
grep -rn "42b983\|0f9d58\|4cbf30\|38a274\|3ecf8e\|0ba360\|3cba92"
  --include="*.css"

十五、关闭不需要的功能

14.1 统计与分析

编辑 themes/matery/_config.yml：

# 关闭百度统计
baiduAnalytics:
  enable:
  id:

# 关闭 Google Analytics
googleAnalytics:
  enable:
  id:

# 关闭百度推送
baiduPush:

14.2 移除不用的插件

npm uninstall hexo-theme-landscape hexo-renderer-pug

hexo-theme-landscape 是 Hexo 默认主题，已用 Matery 就不需要了。hexo-renderer-pug 是 Pug 模板引擎，Matery 用的是 EJS。

十六、日常写作工作流

新文章

hexo new "文章标题"

本地预览

hexo server

访问 http://localhost:4000 实时查看效果。

发布上线

hexo clean && hexo g && hexo d

一句话总结

写 Markdown → hexo server 预览 → hexo clean && hexo g && hexo d 发布

十七、常见问题排查

Q1：部署后页面空白 / 404？

检查 _config.yml 中的 url 和 root：

• 根站点：root: /
• 子目录站点：root: /子目录名/

Q2：图片显示不出来（裂图）？

1. 确认图片放在了 source/images/ 下
2. 引用路径必须以 /images/ 开头，如 ![图](/images/xxx.jpg)
3. 不要用相对路径 ../images/

Q3：部署后网站没变化？

• GitHub Pages 有 1-5 分钟缓存，等一等
• 强制刷新浏览器：Ctrl+Shift+R
• 检查 GitHub 仓库的 Actions 页面是否显示绿色对勾

Q4：想要自定义域名？

1. 在 source/ 下创建 CNAME 文件，写入你的域名（如 blog.example.com）
2. 去域名 DNS 服务商添加 CNAME 记录指向 你的用户名.github.io
3. GitHub 仓库 Settings → Pages → Custom domain 填写域名

Q5：如何添加评论系统？

推荐 Giscus（基于 GitHub Discussions），比 Gitalk 更简单，无需申请 OAuth App：

1. 访问 giscus.app，填入仓库名
2. 在 GitHub 仓库 Settings → Features 中开启 Discussions
3. 把生成的配置填入 themes/matery/_config.yml：

giscus:
  enable:
  repo:
  repoID:
  category:
  categoryID:
  mapping:
  lang:

Matery 还支持 Gitalk、Valine、Waline、Twikoo 等，按需选择即可。

Q6：代码块没有语法高亮？

确认 _config.yml 中启用了 Prism.js：

prismjs:
  enable:
  preprocess:

Matery 主题内置了 Prism.js 的支持，开启后代码块会自动应用 Okaidia 暗色主题 + 行号。

Q7：首页显示文章全文而不是摘要？

在文章中加入 <!-- more --> 标签，前面的内容作为摘要显示在首页卡片中，后面的内容只有点进去才能看到。

总结

这篇保姆级教程从一个空仓库开始，手把手带你完成了：

1. 环境搭建 → Node.js + Git + GitHub 仓库
2. 博客创建 → Hexo 初始化 + 必备插件
3. 核心配置 → _config.yml 网站配置 + Matery 主题配置
4. 内容写作 → Front-matter 配置 + Markdown 规范 + 图片管理
5. 主题美化 → 全站配色统一（紫/蓝/任意色）
6. 功能增强 → 评论系统（Giscus）+ 搜索 + RSS + Sitemap
7. 部署发布 → 一键推送到 GitHub Pages
8. 进阶扩展 → 多站点部署、自定义域名、代码高亮（Prism.js 暗色主题）

如果你已经跟着教程做完了所有步骤，恭喜——你现在拥有的是一个零成本、完全自定义、加载飞速、好看又好用的个人博客。

写吧。写得越多，收获越多。