Hexo 静态博客搭建完整教程

目录

Hexo 简介

Hexo 是一个快速、简洁且高效的博客框架，使用 Node.js 开发。它可以将 Markdown 文档渲染成静态网页，支持多种主题和插件。

优点：

  • 速度快，生成静态页面
  • 支持 Markdown 语法
  • 丰富的主题和插件
  • 一键部署到 GitHub Pages、Netlify 等平台

环境准备

1. 安装 Node.js

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

Windows/Mac 用户：

  • 访问 Node.js 官网
  • 下载 LTS（长期支持）版本并安装
  • 安装完成后验证：
    1
    2
    node -v
    npm -v

Linux 用户：

1
2
3
4
5
6
7
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install nodejs

2. 安装 Git

用于版本控制和部署。

Windows：

Mac：

1
2
# 使用 Homebrew
brew install git

Linux：

1
2
3
4
5
# Ubuntu/Debian
sudo apt install git

# CentOS/RHEL
sudo yum install git

安装 Hexo

安装完 Node.js 后，使用 npm 安装 Hexo：

1
npm install -g hexo-cli

验证安装：

1
hexo version

创建博客项目

1. 初始化项目

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

# 安装依赖
npm install

2. 目录结构说明

1
2
3
4
5
6
7
8
myblog/
├── _config.yml       # 站点配置文件
├── package.json      # 依赖配置
├── scaffolds/        # 模板文件夹
├── source/           # 资源文件夹
│   ├── _posts/       # 文章目录
│   └── _drafts/      # 草稿目录
└── themes/           # 主题目录

3. 本地预览

1
2
3
4
# 生成静态文件并启动服务器
hexo server
# 或简写
hexo s

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

基础配置

编辑 _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
40
41
42
43
44
45
46
47
48
49
# Site 站点信息
title: 我的博客
subtitle: 欢迎来到我的博客
description: 这是一个使用Hexo搭建的博客
keywords: hexo,博客,技术
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

# URL 设置
url: https://yourname.github.io
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:

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

# Writing 写作设置
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

# Server 服务器设置
port: 4000
server_ip: localhost

# Date/Time format
date_format: YYYY-MM-DD
time_format: HH:mm:ss

# Pagination 分页设置
per_page: 10
pagination_dir: page

# Extensions 扩展设置
theme: landscape  # 默认主题

写作与发布

1. 创建新文章

1
hexo new "我的第一篇文章"

这会在 source/_posts/ 目录下创建 我的第一篇文章.md 文件。

2. 文章 Front-matter

在文章开头添加 YAML 格式的配置：

1
2
3
4
5
6
7
---
title: 我的第一篇文章
date: 2024-01-01 12:00:00
tags: [Hexo, 教程]
categories: [技术]
cover: /images/cover.jpg  # 文章封面
---

3. 写作示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
title: Hexo 搭建教程
date: 2024-01-01 12:00:00
tags: [Hexo, 博客, 教程]
categories: [技术]
---

## 什么是 Hexo？

Hexo 是一个基于 Node.js 的静态博客框架...

## 安装步骤

### 1. 安装 Node.js

```bash
npm install -g hexo-cli

2. 创建博客

1
2
3
hexo init myblog
cd myblog
npm install

总结

通过本文，你学会了如何…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

### 4. 常用命令
```bash
# 创建新文章
hexo new "文章标题"

# 创建草稿
hexo new draft "草稿标题"

# 发布草稿
hexo publish draft "草稿标题"

# 生成静态文件
hexo generate
# 或简写
hexo g

# 启动本地服务器
hexo server
# 或简写
hexo s

# 清理缓存
hexo clean

主题配置

1. 安装主题

以流行的 Next 主题为例：

1
2
cd myblog
git clone https://github.com/next-theme/hexo-theme-next themes/next

2. 启用主题

修改 _config.yml：

1
theme: next

3. 主题配置

Next 主题有独立的配置文件 themes/next/_config.yml，可以根据需要进行个性化设置。

部署到 GitHub Pages

1. 创建 GitHub 仓库

  • 仓库名格式：用户名.github.io
  • 设置为公开仓库

2. 安装部署插件

1
npm install hexo-deployer-git --save

3. 配置部署信息

修改 _config.yml：

1
2
3
4
5
deploy:
  type: git
  repo: https://github.com/用户名/用户名.github.io.git
  branch: main
  message: "Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}"

4. 部署到 GitHub

1
2
3
4
5
6
7
# 生成静态文件
hexo clean && hexo generate

# 部署
hexo deploy
# 或简写
hexo d

5. 访问博客

打开 https://用户名.github.io 查看部署的博客。

高级功能

1. 图片管理

安装资源文件夹插件：

1
npm install https://github.com/CodeFalling/hexo-asset-image --save

修改 _config.yml：

1
post_asset_folder: true

使用方式：

1
![图片描述](图片文件名.jpg)

2. 搜索功能

安装搜索插件：

1
npm install hexo-generator-searchdb --save

配置：

1
2
3
4
5
search:
  path: search.xml
  field: post
  format: html
  limit: 10000

3. 评论系统

安装 Valine 评论：

1
npm install hexo-next-valine --save

4. 网站统计

安装不蒜子统计：
在主题配置文件中添加：

1
2
3
4
5
6
7
8
busuanzi_count:
  enable: true
  total_visitors: true
  total_visitors_icon: fa fa-user
  total_views: true
  total_views_icon: fa fa-eye
  post_views: true
  post_views_icon: fa fa-eye

常见问题

1. 部署后页面空白

1
2
# 清理缓存重新生成
hexo clean && hexo g && hexo d

2. 图片无法显示

  • 确保 post_asset_folder: true
  • 图片路径正确
  • 使用相对路径

3. 主题样式异常

1
2
3
# 更新主题
cd themes/next
git pull

4. 部署失败

  • 检查 GitHub 仓库地址是否正确
  • 确认有写入权限
  • 检查网络连接

5. 插件冲突

如果安装多个插件出现冲突，可以：

1
2
3
# 删除 node_modules 重新安装
rm -rf node_modules
npm install

实用技巧

1. 自动化脚本

创建 deploy.sh 脚本：

1
2
3
4
5
6
7
#!/bin/bash
hexo clean
hexo generate
hexo deploy
git add .
git commit -m "更新博客"
git push origin main

2. 备份源文件

将整个博客目录推送到另一个 GitHub 仓库进行备份。

3. 自定义域名

在 source 目录创建 CNAME 文件，内容为你的域名：

1
yourdomain.com

总结

通过本教程，你已经学会了：

  • Hexo 环境的搭建和配置
  • 博客的创建和文章写作
  • 主题的安装和个性化
  • 部署到 GitHub Pages
  • 各种实用插件的使用

Hexo 是一个功能强大且灵活的静态博客框架，通过不断探索和实践，你可以打造出独一无二的个人博客。

Happy Blogging! 🎉