前言

一直想搭建一个个人博客，记录自己的技术成长和思考（主要是想有个地方记录踩过的坑，免得下次又忘了 😂）。经过一番调研，最终选择了 Hexo + Butterfly 主题。这篇文章记录一下搭建过程和一些踩坑经历（真的踩了好多坑…）。

为什么选择 Hexo？

1. 静态站点生成器

Hexo 是一个快速、简洁且高效的博客框架，使用 Markdown 编写文章，然后生成静态 HTML 文件。

优点：

  • 速度快：静态文件，访问速度快
  • SEO友好：静态HTML，搜索引擎容易索引
  • 免费托管：可以部署到 GitHub Pages、Netlify 等免费平台
  • 版本控制：文章用 Markdown 编写，可以用 Git 管理

2. 丰富的主题

Hexo 有丰富的主题生态，我选择了 Butterfly 主题，因为：

  • 界面美观：现代化的设计风格
  • 功能丰富：支持代码高亮、搜索、评论等
  • 文档完善：中文文档详细，配置简单
  • 持续更新：社区活跃，问题能及时解决

搭建过程

1. 环境准备

1
2
3
4
5
6
# 安装 Node.js（需要 12.0 以上版本）
node -v
npm -v

# 安装 Hexo
npm install -g hexo-cli

2. 初始化项目

1
2
3
4
5
6
# 创建博客目录
hexo init ahzlll.github.io
cd ahzlll.github.io

# 安装依赖
npm install

3. 安装 Butterfly 主题

1
2
3
4
5
# 安装主题
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

# 安装主题依赖
npm install hexo-renderer-pug hexo-renderer-stylus --save

4. 配置主题

修改 _config.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 站点配置
title: Ahzlll's Blog
subtitle: '后端开发思考'
description: '用代码编织梦想，用文字记录成长，偶尔记录下踩过的坑和收获'
author: Ahz Hong
language: zh-CN
timezone: 'Asia/Shanghai'

# 主题配置
theme: butterfly

# URL配置
url: https://ahzlll.github.io
permalink: :year/:month/:day/:title/

5. 本地预览

1
2
3
4
# 启动本地服务器
hexo server

# 访问 http://localhost:4000

踩坑经历

1. 中文路径问题

问题：文章标题包含中文时，生成的URL包含中文，可能导致404。

解决：在 _config.yml 中配置：

1
2
3
4
5
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:
  trailing_index: true
  trailing_html: true

或者使用英文标题，在文章中使用 title 字段。

2. 图片路径问题

问题：Markdown 中的图片路径不正确。

解决：使用 Hexo 的资源文件夹功能：

1
post_asset_folder: true

然后在文章中：

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

3. 代码高亮问题

问题：代码高亮不生效。

解决：安装代码高亮插件：

1
npm install hexo-prism-plugin --save

在 _config.yml 中配置：

1
2
3
4
prism_plugin:
  mode: 'preprocess'
  line_number: true
  custom_css:

4. 搜索功能

问题：本地搜索不工作。

解决：安装搜索插件：

1
npm install hexo-generator-searchdb --save

配置：

1
2
3
4
5
search:
  path: search.xml
  field: post
  content: true
  format: xml

5. 部署到 GitHub Pages

问题：部署后样式丢失。

解决：检查 _config.yml 中的 url 配置，确保与 GitHub Pages 地址一致。

1
2
url: https://ahzlll.github.io
root: /

博客配置

1. 添加友链

创建 source/_data/link.yml：

1
2
3
4
5
6
7
- class_name: 技术博客
  class_desc: 分享技术心得和开发经验的优秀博客
  link_list:
    - name: Hexo
      link: https://hexo.io/
      avatar: https://hexo.io/favicon.ico
      descr: 快速、简洁且高效的博客框架

2. 自定义样式

创建 source/css/custom-green-theme.css：

1
2
3
4
/* 自定义样式 */
:root {
  --theme-color: #49b1f5;
}

在主题配置中引入：

1
2
3
inject:
  head:
    - <link rel="stylesheet" href="/css/custom-green-theme.css">

3. 添加统计

使用不蒜子统计：

1
2
3
4
5
busuanzi:
  enable: true
  site_uv: true
  site_pv: true
  page_pv: true

写作体验

1. Markdown 编写

使用 Markdown 编写文章，简单高效：

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: 文章标题
date: 2024-11-21 20:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类
---

## 标题

正文内容...

2. 代码高亮

支持多种语言的代码高亮：

1
2
3
4
5
6
7
```java
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}
```

3. 数学公式

支持 LaTeX 数学公式：

1
2
3
$$
E = mc^2
$$

部署流程

1. 生成静态文件

1
hexo generate

2. 部署到 GitHub Pages

1
2
3
4
5
6
7
8
9
10
11
# 安装部署插件
npm install hexo-deployer-git --save

# 配置
deploy:
  type: git
  repo: https://github.com/ahzlll/ahzlll.github.io.git
  branch: main

# 部署
hexo deploy

3. 自动化部署

可以使用 GitHub Actions 实现自动化部署：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
name: Deploy Blog

on:
  push:
    branches:
      - source

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install
      - run: hexo generate
      - run: hexo deploy

使用体验

优点

  1. 写作简单：Markdown 语法，专注内容
  2. 部署方便：一键部署到 GitHub Pages
  3. 主题丰富：Butterfly 主题功能完善
  4. 性能优秀：静态站点，访问速度快
  5. SEO友好：搜索引擎容易索引

缺点

  1. 需要本地环境：需要安装 Node.js
  2. 更新需要重新生成：每次更新需要重新生成静态文件
  3. 评论功能：需要第三方服务（如 Valine、Gitalk）

未来计划

  1. 内容优化：持续输出高质量的技术文章
  2. 功能完善：添加评论、搜索等功能
  3. 性能优化：优化加载速度，提升用户体验
  4. SEO优化：提升搜索引擎排名

总结

搭建个人博客是一个很好的学习过程，不仅能记录技术成长，还能锻炼写作能力。Hexo + Butterfly 是一个很好的选择，简单易用，功能丰富。

如果你也想搭建个人博客，可以参考我的配置：

写在最后

博客搭建只是第一步，更重要的是持续输出有价值的内容（虽然不知道能坚持多久 😅）。希望自己能坚持下去，记录技术成长，分享开发经验。如果文章有错误，欢迎指正！