技术文档

Hexo博客搭建指南

什么是Hexo

Hexo是一个快速、简洁且高效的博客框架，使用Node.js编写。它可以将Markdown文档渲染成静态网页，支持多种主题和插件，非常适合技术博客和个人网站。

环境准备

安装Node.js

Hexo基于Node.js，首先需要安装Node.js环境：

  1. 访问 Node.js官网 下载安装包
  2. 选择LTS版本进行安装
  3. 安装完成后验证安装：
1
2
node --version
npm --version

安装Git

Git用于版本控制和部署：

  1. 访问 Git官网 下载安装
  2. 配置Git用户信息：
1
2
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

安装Hexo

使用npm安装Hexo命令行工具：

1
2
3
4
5
# 全局安装Hexo
npm install -g hexo-cli

# 验证安装
hexo --version

创建博客项目

初始化项目

1
2
3
4
5
6
# 创建博客目录
hexo init myblog
cd myblog

# 安装依赖
npm install

项目结构说明

1
2
3
4
5
6
7
8
myblog/
├── _config.yml       # 站点配置文件
├── source/           # 源文件目录
│   ├── _posts/       # 文章目录
│   └── about/        # 关于页面
├── themes/           # 主题目录
├── public/           # 生成的静态文件
└── package.json      # 项目依赖配置

基本配置

修改站点配置

编辑 _config.yml 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# 站点信息
title: 我的博客
subtitle: 分享技术与生活
description: 一个专注于技术分享的个人博客
keywords: 技术,编程,学习
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

# URL设置
url: https://yourdomain.com
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:

# 目录设置
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code

# 文章设置
new_post_name: :title.md
default_layout: post
auto_spacing: false
titlecase: false
external_link: true
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
highlight:
  enable: true
  line_number: true
  auto_detect: false
  tab_replace: ''

创建内容

新建文章

1
2
3
4
# 创建新文章
hexo new post "文章标题"

# 文章会自动创建在 source/_posts/ 目录下

文章Front-matter

每篇文章开头需要包含Front-matter：

1
2
3
4
5
6
---
title: 文章标题
date: 2025-10-20 16:00:00
tags: [标签1, 标签2]
categories: [分类]
---

编写Markdown内容

使用标准的Markdown语法编写文章内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
## 二级标题

这是段落内容。

- 列表项1
- 列表项2

`行内代码`

```python
# 代码块
def hello():
    print("Hello Hexo!")
1
2
3
4
5
6
7
8
9
10
11
12
13
14

## 本地预览

### 启动本地服务器

```bash
# 生成静态文件并启动服务器
hexo server

# 或简写
hexo s

# 指定端口
hexo s -p 4000

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

生成静态文件

1
2
3
4
5
# 生成静态文件到public目录
hexo generate

# 或简写
hexo g

主题安装与配置

安装主题

以NexT主题为例：

1
2
# 下载主题到themes目录
git clone https://github.com/next-theme/hexo-theme-next themes/next

配置主题

在 _config.yml 中启用主题：

1
2
# 主题配置
theme: next

编辑主题配置文件 themes/next/_config.yml 进行个性化设置。

部署到GitHub Pages

创建GitHub仓库

  1. 在GitHub创建名为 用户名.github.io 的仓库
  2. 将本地代码推送到仓库

安装部署插件

1
npm install hexo-deployer-git --save

配置部署信息

在 _config.yml 中添加：

1
2
3
4
5
# 部署配置
deploy:
  type: git
  repo: https://github.com/用户名/用户名.github.io.git
  branch: main

执行部署

1
2
3
4
5
6
7
8
# 清理并重新生成
hexo clean && hexo generate

# 部署到GitHub
hexo deploy

# 或简写
hexo d

常用命令总结

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 新建文章
hexo new "文章标题"

# 本地预览
hexo server

# 生成静态文件
hexo generate

# 部署
hexo deploy

# 一键清理、生成、部署
hexo clean && hexo g && hexo d

实用插件推荐

搜索插件

1
npm install hexo-generator-search --save

RSS订阅

1
npm install hexo-generator-feed --save

站点地图

1
npm install hexo-generator-sitemap --save

常见问题解决

图片显示问题

在 _config.yml 中启用资源文件夹：

1
post_asset_folder: true

中文URL问题

安装转义插件：

1
npm install hexo-filter-slug --save

部署失败

检查Git配置和仓库权限，确保有正确的SSH密钥设置。

进阶功能

自定义页面

创建关于页面：

1
hexo new page "about"

添加评论系统

集成Gitalk、Valine等评论系统。

统计分析

添加Google Analytics或百度统计。