Hexo 完整使用指南（从搭建到部署）-平芜编程栈

你想了解 Hexo 的相关使用方法，Hexo 是一款快速、简洁且高效的静态博客生成框架，基于 Node.js 构建，广泛用于搭建个人博客（如部署到 GitHub Pages、Gitee Pages）。下面从环境准备、博客搭建、内容创作到部署上线，提供完整的分步教程。

一、前置环境准备

Hexo 依赖 Node.js 和 Git，需先安装这两个工具：

1. 安装 Node.js

下载地址：https://nodejs.org/zh-cn/（推荐下载 LTS 长期支持版本）
安装完成后，打开终端（Mac/Linux 终端、Windows Git Bash），执行以下命令验证安装：
```
node -v npm -v
```
若输出对应版本号，说明 Node.js 和 npm（包管理工具）安装成功。

2. 安装 Git

下载地址：https://git-scm.com/downloads（Windows 需安装 Git Bash，Mac/Linux 通常自带）
验证安装：
```
git --version
```
输出 Git 版本号即安装成功。

二、安装 Hexo 并初始化博客

1. 全局安装 Hexo CLI

终端执行以下命令，全局安装 Hexo 命令行工具：

npm install -g hexo-cli

验证安装：hexo -v，输出 Hexo 版本信息即安装成功。

2. 初始化 Hexo 博客

新建一个文件夹作为博客根目录（如hexo-blog），进入该文件夹：
```
# Mac/Linux/Windows Git Bash mkdir hexo-blog cd hexo-blog
```
执行初始化命令，生成 Hexo 博客基础结构：
```
hexo init
```
安装博客依赖包：
```
npm install
```

3. 查看 Hexo 博客目录结构

初始化完成后，博客根目录会生成以下核心文件 / 文件夹：

_config.yml：Hexo 全局配置文件（核心，用于配置博客标题、主题、部署信息等）；
source/：存放博客原始内容，_posts/文件夹用于存放所有博客文章（Markdown 格式）；
themes/：存放博客主题，默认主题为landscape；
public/：Hexo 生成的静态网页文件（部署时需上传该目录内容）；
scaffolds/：文章模板文件，新建文章时会基于模板生成。

三、本地预览 Hexo 博客

生成静态网页文件：
```
hexo generate # 简写：hexo g
```
启动本地服务器：
```
hexo server # 简写：hexo s
```
预览博客：打开浏览器，访问http://localhost:4000，即可看到 Hexo 默认博客页面。

停止本地服务器：终端按Ctrl+C即可。

四、创作博客文章

1. 新建博客文章

终端执行以下命令，新建一篇 Markdown 格式的博客文章：

# 新建文章，标题为「My First Hexo Blog」（可自定义） hexo new "My First Hexo Blog" # 简写：hexo n "My First Hexo Blog"

执行后，文章会生成在source/_posts/目录下，文件名格式为年-月-日-文章标题.md。

2. 编辑博客文章

用 Markdown 编辑器（如 Typora、VS Code）打开source/_posts/下的文章文件，按 Markdown 语法编辑内容：

文章头部为 Front-matter（配置区域），用于设置文章标题、日期、分类、标签等：

--- title: My First Hexo Blog # 文章标题 date: 2025-12-23 10:00:00 # 发布日期 categories: 技术笔记 # 分类 tags: [Hexo, Git] # 标签 --- # 这是一级标题 这是博客正文内容，支持 Markdown 所有语法... ## 这是二级标题 代码块示例： ```bash hexo g && hexo s

3. 重新预览文章

编辑完成后，重新生成静态文件并启动服务器，即可预览最新文章：

# 先清除旧的静态文件（可选，避免缓存问题） hexo clean # 生成新的静态文件 hexo g # 启动服务器预览 hexo s

五、更换 Hexo 主题（可选）

Hexo 默认主题较为简洁，可更换第三方主题（以热门主题Next为例）：

克隆 Next 主题到themes/目录：

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

修改全局配置文件_config.yml，指定使用 Next 主题：
```
# 找到 theme 配置项，将 landscape 改为 next theme: next
```
重新生成并预览博客，即可看到 Next 主题效果：
```
hexo clean && hexo g && hexo s
```

更多 Hexo 主题可参考：https://hexo.io/themes/

六、部署 Hexo 博客到 GitHub Pages

将 Hexo 博客部署到 GitHub Pages，实现公网访问：

1. 准备 GitHub 仓库

登录 GitHub，新建一个仓库，仓库名必须为你的GitHub用户名.github.io（如zhangsan.github.io）；
仓库创建完成后，记录仓库的 SSH 地址（如git@github.com:zhangsan/zhangsan.github.io.git）。

2. 安装 Hexo 部署插件

终端执行命令，安装hexo-deployer-git插件（用于将静态文件部署到 GitHub）：

npm install hexo-deployer-git --save

3. 配置部署信息

编辑博客根目录的_config.yml文件，找到deploy配置项，填写以下内容：

deploy: type: git repo: git@github.com:你的用户名/你的用户名.github.io.git # 你的 GitHub 仓库 SSH 地址 branch: main # 部署分支（GitHub 默认分支为 main，早期为 master，需对应仓库默认分支） message: "Deploy Hexo blog: {{ now('YYYY-MM-DD HH:mm:ss') }}" # 部署提交信息（可选）

4. 部署博客到 GitHub

终端执行部署命令，将 Hexo 生成的静态文件推送到 GitHub 仓库：

hexo clean && hexo g && hexo deploy # 简写：hexo d

首次部署需验证 SSH 连接，输入yes即可；
部署成功后，等待 1-2 分钟，访问https://你的用户名.github.io，即可公网访问你的 Hexo 博客。

七、常用 Hexo 命令总结

命令	简写	功能说明
`hexo init`	-	初始化 Hexo 博客
`hexo new "标题"`	`hexo n`	新建博客文章
`hexo generate`	`hexo g`	生成静态网页文件到`public/`目录
`hexo server`	`hexo s`	启动本地服务器，默认端口 4000
`hexo deploy`	`hexo d`	部署静态文件到远程仓库（如 GitHub Pages）
`hexo clean`	-	清除旧的静态文件和缓存
`hexo clean && hexo g && hexo d`	-	一键清除、生成、部署（常用部署命令）

八、常见问题排查

本地服务器无法访问（http://localhost:4000打不开）：
- 原因：端口 4000 被占用，或 Hexo 依赖未安装完整；
- 解决：更换端口启动（hexo s -p 5000，访问http://localhost:5000），或重新执行npm install安装依赖。
部署失败（提示 Permission denied）：
- 原因：SSH 密钥未配置到 GitHub，或仓库地址填写错误；
- 解决：参考之前的 SSH 配置教程，完成密钥配置，确认仓库地址正确。
部署后博客空白，无内容：
- 原因：_config.yml中url配置错误，或部署分支不对；
- 解决：在_config.yml中设置url: https://你的用户名.github.io，确认部署分支与仓库默认分支一致。