技术博客搭建完整指南：Hexo + NexT + Nginx 实战

发表于 post.tags , , , , 阅读次数：

摘要

本文记录了使用 Hexo + NexT 主题 + Nginx 搭建个人技术博客的完整过程，涵盖技术栈选型、原理分析、搭建步骤、文件结构以及常见问题的解决方案。

一、技术栈选型

1.1 核心框架

技术 版本 用途
Hexo 最新 静态博客生成器
NexT 8.27.0 Hexo 主题
Node.js 18+ Hexo 运行环境
Nginx 系统包 Web 服务器

1.2 选型理由

为什么选择 Hexo？

  • 纯静态生成，访问速度快
  • Markdown 写作，体验好
  • 主题丰富，生态成熟
  • 部署简单，支持多种部署方式

为什么选择 NexT？

  • 简洁美观，专注于阅读体验
  • 配置灵活，功能丰富
  • 中文文档完善
  • 社区活跃，持续维护

为什么选择 Nginx？

  • 性能高效，资源占用低
  • 配置灵活，支持反向代理
  • 静态文件托管效果好

二、技术原理

2.1 Hexo 工作原理

1
2
3
4
5
6
7
┌─────────────────────────────────────────────────────────┐
│                      Hexo 工作流程                        │
├─────────────────────────────────────────────────────────┤
│   Markdown 文件 ──→ Hexo 解析 ──→ HTML 静态文件        │
│        ↑                                    ↓           │
│        └────────── 配置 + 主题 ───────────┘            │
└─────────────────────────────────────────────────────────┘

核心流程：

  1. 解析：Hexo 读取 source/_posts/ 下的 Markdown 文件
  2. 处理：使用主题模板渲染，生成 HTML
  3. 输出：静态文件输出到 public/ 目录
  4. 部署：将 public/ 部署到服务器

2.2 NexT 主题原理

NexT 是 Hexo 最流行的主题之一，采用 Nunjucks 模板引擎：

1
2
3
4
5
6
7
8
9
10
themes/next/
├── layout/           # 模板目录
│   ├── _macro/      # 宏定义
│   ├── _partials/    # 局部模板
│   ├── index.njk     # 首页模板
│   ├── post.njk     # 文章页模板
├── source/          # 静态资源
│   ├── css/         # 样式文件
│   ├── js/          # JavaScript 文件
└── _config.yml     # 主题配置

2.3 Front Matter 机制

Front Matter 是 Markdown 文件头部的 YAML 块：

1
2
3
4
5
6
7
8
---
title: 文章标题
date: 2026-03-12
tags: [标签1, 标签2]
description: 摘要内容
---

正文...

关键字段：

  • title：文章标题
  • date：发布日期
  • tags：标签（数组）
  • description：摘要（用于首页显示）

2.4 <!-- more --> 截断符

Hexo 使用 <!-- more --> 标记控制首页文章预览位置：

1
2
3
4
5
正文第一段...

<!-- more -->

正文第二段（首页不显示）...

显示规则：

  • 首页：显示 <!-- more --> 之前的内容
  • 文章页：显示完整正文

三、搭建过程

3.1 环境准备

1
2
3
4
5
6
7
8
# 1. 安装 Node.js（已在服务器预装）
node -v  # v22.x

# 2. 安装 pnpm（包管理器）
npm install -g pnpm

# 3. 安装 Hexo CLI
pnpm add -g hexo

3.2 初始化博客

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 创建博客目录
mkdir /root/my-blog
cd /root/my-blog

# 2. 初始化 Hexo
npx hexo init

# 3. 安装依赖
pnpm install

# 4. 安装部署插件
pnpm add hexo-deployer-git

3.3 安装主题

1
2
3
4
5
6
7
# 方式一：克隆 NexT 主题
cd /root/my-blog/themes
git clone https://github.com/next-theme/hexo-theme-next.git next

# 方式二：npm 安装（推荐）
cd /root/my-blog
pnpm add hexo-theme-next

3.4 配置博客

站点配置（_config.yml）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Site
title: 你的博客名
subtitle: ''
description: 技术博客
author: 你的名字
language: zh-CN
timezone: ''

# URL
url: https://你的域名.com

# Deployment
deploy:
  type: git
  repo: https://gitee.com/你的用户名/你的仓库.git
  branch: master

主题配置（themes/next/_config.yml）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 菜单
menu:
  首页: /
  归档: /archives
  标签: /tags
  关于: /about

# 文章元信息
post_meta:
  created_at: true
  updated_at:
    enable: true
    another_day: true
  categories: true
  tags: true  # 关键：显示标签

# 摘要配置
excerpt_description: true  # 首页显示摘要

3.5 部署流程

1
2
3
4
5
# 简化的部署命令
cd /root/my-blog
npx hexo clean
npx hexo generate
cp -r public/* /var/www/html/

或者部署到 Gitee Pages：

1
npx hexo deploy

3.6 Nginx 配置

1
2
3
4
5
6
7
8
9
10
11
# 1. 启动 Nginx
systemctl start nginx
systemctl enable nginx

# 2. 配置（/etc/nginx/sites-available/default）
server {
    listen 80;
    server_name 你的域名;
    root /var/www/html;
    index index.html;
}

四、文件结构

4.1 完整目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
/root/my-blog/
├── _config.yml           # 站点配置文件
├── package.json          # 项目依赖
├── scaffolds/            # 文章模板
├── source/               # 源文件目录
│   └── _posts/           # 文章目录
│       ├── 文章1.md
│       └── ...
├── themes/               # 主题目录
│   └── next/             # NexT 主题
│       ├── _config.yml   # 主题配置
│       └── layout/        # 模板文件
└── public/               # 生成的静态文件

4.2 文章文件格式

1
2
3
4
5
6
7
8
9
10
---
title: 文章标题
date: 2026-03-12
tags: [标签1, 标签2]
description: 摘要内容（150-200字）
---

<!-- more -->

正文内容...

五、常见问题与解决方案

5.1 摘要显示问题

问题：首页显示全文而非摘要

解决：

  1. 在文章中添加 description 字段
  2. 在摘要结束位置添加 <!-- more --> 标记
  3. 主题配置设置 excerpt_description: true
1
2
# 主题配置
excerpt_description: true

问题：文章页显示摘要

解决：
修改模板文件 themes/next/layout/_macro/post.njk，找到：

1
2
3
{%- if post.description and (not theme.excerpt_description or not is_index) %}
  <div class="post-description">{{ post.description }}</div>
{%- endif %}

修改为：

1
2
3
{%- if post.description and not is_index %}
  {# 不在文章页显示摘要 #}
{%- endif %}

5.2 标签不显示问题

问题：文章页不显示标签

解决：

  1. 确保主题配置启用：
1
2
post_meta:
  tags: true
  1. 检查模板是否正确渲染

5.3 Git 推送失败

解决：

  1. 配置 Git 用户信息：
1
2
git config user.name "yourname"
git config user.email "your@email.com"
  1. 使用 Gitee Token 或 SSH 密钥认证

5.4 Nginx 无法访问

解决：

  1. 检查 Nginx 状态：systemctl status nginx
  2. 检查防火墙：firewall-cmd --list-ports
  3. 检查文件权限：chmod -R 755 /var/www/html/

5.5 样式问题

问题：CSS/JS 未加载

解决：

  1. 清理缓存：hexo clean
  2. 重新生成：hexo g
  3. 检查 public/ 目录是否完整

六、显示规则（已固定）

页面 摘要(description) 标签
首页 ✅ 显示 -
文章页 ❌ 不显示 ✅ 显示

七、常用命令

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 + NexT + Nginx 博客搭建的全过程，包括：

  • 技术栈选型及理由
  • 核心工作原理
  • 完整搭建步骤
  • 文件结构说明
  • 常见问题解决方案

通过这套方案，可以快速搭建一个高性能、易维护的个人技术博客。