Hexo 博客框架快速入门指南

Hexo 是一个基于 Node.js 的快速、简洁且高效的静态博客框架。本文介绍 Hexo 的常用操作和最佳实践。

一、Hexo 简介

1.1 特性

特性 说明
超快速度 生成静态文件，秒级渲染
支持 Markdown 使用 Markdown 编写文章
一键部署 配合 Git 实现一键部署
丰富插件 海量主题和插件支持
开源免费 MIT 许可证，完全免费

1.2 环境要求

1
2
3
4
5
6
7
8
9
10
11
┌─────────────────────────────────────────────────────────────────────────┐
│                         Hexo 环境依赖                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐              ┌─────────────┐              ┌─────────────┐  │
│  │   Node.js   │              │     Git     │              │   编辑器     │  │
│  │  (>= 10.x)  │              │    (可选)   │              │  (VSCode等) │  │
│  │  npm/cnpm   │              │  用于部署   │              │  编写Markdown│  │
│  └─────────────┘              └─────────────┘              └─────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

二、安装与初始化

2.1 安装 Hexo

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

# 验证安装
hexo version

2.2 初始化博客

1
2
3
4
5
6
7
8
9
10
# 创建博客目录
hexo init my-blog
cd my-blog

# 安装依赖
npm install

# 本地预览
hexo server
# 访问 http://localhost:4000

2.3 目录结构

1
2
3
4
5
6
7
8
9
my-blog/
├── _config.yml          # 全局配置文件
├── package.json         # 依赖管理
├── scaffolds/           # 文章模板
├── source/              # 源文件目录
│   ├── _posts/         # Markdown 文章存放处
│   └── _drafts/        # 草稿存放处
├── themes/              # 主题目录
└── public/              # 生成的静态文件（不需要手动管理）

三、常用命令

3.1 命令速查表

命令 简写 说明
hexo init [folder] - 初始化博客
hexo new [layout] <title> - 创建新文章
hexo server hexo s 启动本地服务器
hexo generate hexo g 生成静态文件
hexo deploy hexo d 部署到远程
hexo clean - 清除缓存文件
hexo list <type> - 列出所有路径

3.2 常用组合命令

1
2
3
4
5
6
7
# 清除缓存 + 重新生成
hexo clean && hexo generate

# 生成 + 部署（一步到位）
hexo generate --deploy
# 或
hexo deploy --generate

四、文章管理

4.1 创建文章

1
2
3
4
5
6
7
8
# 创建新文章（保存在 source/_posts/）
hexo new "我的第一篇文章"

# 创建草稿（保存在 source/_drafts/）
hexo new draft "未完成的草稿"

# 创建页面（如关于页）
hexo new page "about"

4.2 发布草稿

1
2
3
4
5
# 发布草稿到 _posts
hexo publish "未完成的草稿"

# 或在启动服务器时预览草稿
hexo server --draft

4.3 Front Matter 格式

每篇文章开头的 YAML 区域称为 Front Matter：

1
2
3
4
5
6
7
8
---
title: 文章标题
date: 2020-05-08 14:30:00
categories: [技术文章, 编程]
tags: [Hexo, Node.js, 博客]
---

文章内容...
字段 说明
title 文章标题
date 发布日期
categories 分类（有层级关系）
tags 标签（无层级关系）
layout 使用的布局
photos 文章封面图

五、本地预览

5.1 启动服务器

1
2
3
4
5
6
7
8
9
10
11
# 默认启动（端口 4000）
hexo server

# 指定端口
hexo server -p 5000

# 草稿模式（显示草稿文章）
hexo server --draft

# 静态模式（不监视文件变化）
hexo server --static

5.2 浏览器访问

启动后访问 http://localhost:4000 即可预览博客效果。

💡 提示：文件修改后会自动刷新，无需重启服务器。

六、生成与部署

6.1 生成静态文件

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

# 显示详细日志
hexo generate --debug

# 压缩静态文件（需要安装 hexo-neat）
hexo generate --neat

6.2 配置 Git 部署

首先安装 Git 部署插件：

1
npm install hexo-deployer-git --save

然后在 _config.yml 中配置：

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

6.3 执行部署

1
2
3
4
5
6
# 方式一：先生成再部署
hexo generate
hexo deploy

# 方式二：一步完成
hexo deploy --generate

七、主题安装

7.1 安装主题

1
2
3
# Git Clone 方式
cd themes
git clone https://github.com/theme-author/theme-name.git

7.2 启用主题

修改 _config.yml：

1
2
# 指定主题名称（themes/ 下的文件夹名）
theme: theme-name

7.3 主题配置

大多数主题有自己的 _config.yml：

1
2
3
4
5
themes/
└── theme-name/
    ├── _config.yml      # 主题专属配置
    ├── source/          # 主题源文件
    └── layout/          # 布局模板

八、常用插件

8.1 推荐插件

插件名称 用途 安装命令
hexo-deployer-git Git 部署 npm install hexo-deployer-git --save
hexo-generator-search 本地搜索 npm install hexo-generator-search --save
hexo-generator-sitemap 站点地图 npm install hexo-generator-sitemap --save
hexo-generator-feed RSS 订阅 npm install hexo-generator-feed --save
hexo-neat 代码压缩 npm install hexo-neat --save

8.2 安装插件

1
2
3
4
5
# 安装插件
npm install <plugin-name> --save

# 卸载插件
npm uninstall <plugin-name> --save

九、常见问题

9.1 端口被占用

1
2
3
4
5
6
7
# Windows
netstat -ano | findstr :4000
taskkill /PID <PID> /F

# macOS/Linux
lsof -i :4000
kill -9 <PID>

9.2 清除缓存

1
2
3
4
5
# 清除缓存和静态文件
hexo clean

# 然后重新生成
hexo generate

9.3 部署失败

1
2
3
4
5
6
7
# 检查 Git 配置
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 手动删除 .deploy_git 文件夹后重试
rm -rf .deploy_git
hexo deploy --generate

十、命令速查表

10.1 核心命令

操作 命令
初始化 hexo init [folder]
新建文章 hexo new "title"
新建草稿 hexo new draft "title"
发布草稿 hexo publish "title"
启动服务 hexo server
生成静态 hexo generate
部署 hexo deploy
清除缓存 hexo clean

10.2 快捷键

快捷写法 完整命令
hexo s hexo server
hexo g hexo generate
hexo d hexo deploy
hexo g -d hexo generate --deploy

十一、最佳实践

11.1 写作工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
┌─────────────────────────────────────────────────────────────────────────┐
│                         Hexo 写作工作流                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  1. 创建文章          2. 编写内容          3. 本地预览                  │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                │
│  │ hexo new    │───>│  Markdown   │───>│  hexo s     │                │
│  │ "文章标题"  │    │  编辑器     │    │  localhost: │                │
│  └─────────────┘    └─────────────┘    │  4000       │                │
│                                         └─────────────┘                │
│                                                   │                     │
│                                                   ▼                     │
│  4. 生成部署          5. 在线访问                                         │
│  ┌─────────────┐    ┌─────────────┐                                    │
│  │ hexo d -g   │───>│  访问博客   │                                    │
│  └─────────────┘    └─────────────┘                                    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

11.2 建议配置

1
2
3
4
5
6
7
8
9
10
11
12
13
# _config.yml 建议配置
url: https://yourusername.github.io
root: /
permalink: :year/:month/:day/:title/
post_asset_folder: true  # 启用资源文件夹

# 写作设置
default_layout: post
titlecase: false
external_link:
  enable: true
  field: site
  exclude: ''

💡 学习建议：

  • 熟练掌握 hexo new、hexo server、hexo g -d 三个核心命令
  • 选择一款喜欢的主题，阅读其文档进行配置
  • 使用 Markdown 编辑器（如 VSCode）提升写作体验
  • 定期备份 source/ 目录和 _config.yml 配置文件

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 1487842110@qq.com