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，确认部署分支与仓库默认分支一致。

总结

Hexo 依赖 Node.js 和 Git，需先完成前置环境安装；
核心流程：hexo init 初始化 → hexo n 新建文章 → hexo g 生成静态文件 → hexo s 本地预览 → hexo d 部署上线；
部署到 GitHub Pages 时，仓库名必须为 用户名.github.io，且需安装 hexo-deployer-git 插件；
常用快捷命令：hexo clean && hexo g && hexo d 一键部署博客。