一、前期准备（必须安装的环境）

1、Node.js（Hexo依赖）

去官网下载合适的LTS版本：https://nodejs.org 建议使用18版本以上。
具体安装使用自行搜索，安装完成后打开终端进行验证：

node -v

2、Git安装

官网：https://git-scm.com
安装后验证：git --version

3、github账号

如果没有则先注册一个，记住你账户的用户名，${username}.github.io就是你的个人站点。点击这里跳转到仓库创建

二、全局安装Hexo命令行工具

由于国内的网络问题，因此推荐使用pnpm，如果没有安装，也可以直接将pnpm替换为npm。

npm i -g pnpm

1、全局安装Hexo命令行工具并验证

pnpm i -g hexo-cli
# 有时候win下需要重启终端
hexo -v

2、创建博客目录并初始化

hexo init blog
cd blog
pnpm install 
# 如果安装失败，并提示Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.直接运行
pnpm approve-builds

解释：hexo init会在执行命令的文件夹中生成标准的Hexo目录结构，使用pnpm安装依赖。

3、本地预览

hexo server

浏览器直接访问http://localhost:4000，可以看到默认的landscape主题就安装成功了。

landscape主题图

三、安装并启用 Matery 主题

1、下载主题

推荐 git clone，方便后续更新，也可以直接去github上下载

cd themes
git clone https://github.com/blinkfox/hexo-theme-matery.git
# 重命名为更短的名字
mv hexo-theme-matery matery
cd ..

2、修改hexo配置，启用matery

打开blog目录下的_config.yml文件，找到theme:一行，改为：

# 和上面文件夹的名称保持一致
theme: matery

想要做什么修改，具体配置的内容参考官方文档：https://hexo.io/zh-cn/docs/configuration.html#%E7%BD%91%E7%AB%99

例如修改语言为中文：

language: zh-CN

3、创建主题需要的页面

hexo new page categories
hexo new page tags
hexo new page about
# 可选
hexo new page friends
hexo new page contact

然后编辑对应文件，即将layout与matery中对应上，下面是about的修改，其他的几个创建的页面也同理：

---
title: about
date: 2024-06-01 16:22:00
type: "about"
layout: "about"
---

这个hexo new命令只是在source目录下创建了一个文件夹，并创建了一个index.md文件，在hexo的规则中，source文件夹下的任何index.md最终都会生成一个独立的HTML网页，路径就是文件夹的名字，比如about/index.md 最终的访问地址就是localhost:4000/about，具体这个页面的渲染是依赖matery主题，在主题文件夹中也有_config.yml配置文件，搜索menu就会看到具体的路由配置，如果没有在hexo的source中创建对应的文件夹，当跳转的时候就会提示404页面。具体该页面的渲染内容，例如about页面，则是在matery中的layout下about.ejs中。

4、目录中的代码高亮配置：
打开博客根目录的 _config.yml，把 Writing 部分的高亮相关内容改成下面这样：

# Writing
new_post_name: :title.md
default_layout: post
titlecase: false
external_link:
  enable: true
  field: site
  exclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true

# ========== 代码高亮配置（Hexo 8 正确写法） ==========
syntax_highlighter: prismjs

highlight:
  enable: false

prismjs:
  enable: true
  preprocess: true      # 服务端预处理（推荐）
  line_number: true     # 显示行号
  tab_replace: ''

此外如果发现代码块收缩和下滑有一些样式冲突，则直接把：

code:
  lang: true
  copy: true
  shrink: false   # ← 先关掉收缩功能
  break: false

5、推荐安装的插件：

pnpm install hexo-generator-search --save          # 站内搜索
pnpm install hexo-wordcount --save                 # 字数统计
pnpm install hexo-permalink-pinyin --save          # 中文链接转拼音（SEO 友好）
pnpm install hexo-generator-feed --save            # RSS
# 可选 emoji
pnpm install hexo-filter-github-emojis --save

6、主题个性化配置

打开 themes/matery/_config.yml，这里可以改：

菜单、社交链接、头像、favicon
Banner 图片、背景图
评论系统（推荐 Gitalk 或 Valine）
不蒜子统计、Google Analytics 等
文章信息显示（字数、阅读时间等）

7、本地预览主题效果

hexo clean
hexo generate   # 或 hexo g
hexo server     # 或 hexo s

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

四、部署到GitHub Pages

1、安装hexo部署插件

pnpm install hexo-deployer-git --save

2、项目配置：

在根目录_config.yml末尾添加（把username换成你的 GitHub 用户名）：

deploy:
  type: git
  repo: git@github.com:username/username.github.io.git   # SSH 方式（推荐）
  # 或者 HTTPS：https://github.com/username/username.github.io.git
  branch: main   # 或者 master，看你仓库默认分支

3、在 GitHub 创建仓库

如果之前你已经创建，则这一步可以取消。

新建仓库，名字必须是你的用户名.github.io（例如 zhangsan.github.io）。
选择 Public，不要勾选添加 README。

4、部署

hexo clean
hexo deploy     # 或 hexo d
# 也可以一次搞定：hexo clean && hexo g && hexo d

第一次可能需要输入 GitHub 账号密码（或使用 Personal Access Token）。成功后等待 1～2 分钟，访问 https://你的用户名.github.io 即可看到网站。

使用这种方式是相当于把源码进行编译成静态网页推送到了这个仓库，本地的源码并没有推送上去，因此还需要再把本地代码进行保存推送。

五、创建博客

新建文章

hexo new “文章标题”

编辑 source/_posts/文章标题.md

生成 + 本地预览

hexo clean && hexo g && hexo s

部署上线

hexo clean && hexo d

文章 Front-matter 常用字段示例（Matery 支持很多扩展）：

---
title: 我的第一篇文章
date: 2026-08-17 10:00:00
categories: [技术, Hexo]
tags: [博客, Matery]
img: /images/cover.jpg          # 特色图片
top: true                       # 置顶
cover: true
summary: 这是摘要...
---