Hexo 博客快速入门

什么是 Hexo？

Hexo 是一个快速、简洁且强大的静态博客框架，基于 Node.js 构建。你只需要使用 Markdown 书写文章，Hexo 就能在几秒内生成漂亮的静态网站。

环境要求

依赖版本要求说明
Node.js20.19.0+ (推荐22)Hexo 8.0+ 最低要求
Git最新版本版本控制
npm9.x+包管理器

重要提示：Node.js 24 与部分 Hexo 插件不兼容，建议使用 Node.js 22。

安装 Hexo

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

# 验证安装
hexo version

初始化博客

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

# 安装依赖
npm install

初始化完成后，目录结构如下：

1
2
3
4
5
6
7
my-blog/
├── _config.yml      # 主配置文件
├── package.json     # 依赖配置
├── scaffolds/       # 模板文件夹
├── source/          # 源文件夹
│   └── _posts/      # 文章存放位置
└── themes/          # 主题文件夹

常用命令

核心命令

命令说明简写
hexo init初始化博客-
hexo new "标题"新建文章hexo n
hexo server启动本地服务器hexo s
hexo generate生成静态文件hexo g
hexo deploy部署网站hexo d
hexo clean清除缓存和生成的文件-

组合命令

1
2
3
4
5
6
7
8
# 生成并部署
hexo g -d

# 生成并启动服务器预览
hexo g && hexo s

# 清除缓存后重新生成
hexo clean && hexo g

命令详解

hexo init

1
hexo init [folder]

初始化博客网站。如果没有指定文件夹，Hexo 会在当前目录初始化。

该命令实际上是以下步骤的快捷方式：

  1. 从 GitHub 克隆 hexo-starter 模板
  2. 使用包管理器安装依赖

hexo new

1
hexo new [layout] <title>

创建新文章。如果没有指定布局(layout)，Hexo 会使用 _config.yml 中的 default_layout 设置。

选项：

  • -p, --path：自定义文章路径
  • -r, --replace：替换已存在的文章
  • -s, --slug：自定义文章的 URL

hexo server

1
hexo server

启动本地服务器，默认地址为 http://localhost:4000/

选项：

  • -p, --port：自定义端口
  • -s, --static：只提供静态文件
  • -l, --log：启用日志

hexo generate

1
hexo generate

生成静态文件到 public/ 目录。

选项：

  • -d, --deploy：生成后立即部署
  • -w, --watch：监听文件变化
  • -f, --force：强制重新生成
  • -b, --bail：生成过程中遇到错误时停止

hexo clean

1
hexo clean

清除缓存文件 (db.json) 和生成的文件 (public/)。

建议：在执行 hexo g 之前先执行 hexo clean，避免缓存导致的问题。

快速开始流程

1. 创建新文章

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

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

2. 编辑文章

打开生成的 Markdown 文件，编写内容：

1
2
3
4
5
6
7
8
9
10
11
---
title: 我的第一篇文章
date: 2026-06-19 12:00:00
tags:
  - Hexo
  - 教程
---

# 文章标题

这是文章内容...

3. 本地预览

1
hexo server

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

4. 部署上线

1
hexo clean && hexo g -d

项目结构详解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
HexoBlogDemo/
├── _config.yml          # Hexo 主配置文件
├── _config.butterfly.yml # Butterfly 主题配置
├── package.json         # 项目依赖
├── scaffolds/           # 文章模板
│   ├── draft.md         # 草稿模板
│   ├── post.md          # 文章模板
│   └── page.md          # 页面模板
├── source/              # 源文件
│   ├── _posts/          # 博客文章
│   ├── _drafts/         # 草稿
│   ├── about/           # 关于页面
│   ├── categories/      # 分类页面
│   ├── tags/            # 标签页面
│   ├── img/             # 图片资源
│   └── css/             # 自定义样式
├── themes/              # 主题目录
└── public/              # 生成的静态文件（git忽略）

Node.js 版本管理

推荐使用 nvm 管理 Node.js 版本：

1
2
3
4
5
6
7
8
9
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js 22
nvm install 22
nvm use 22

# 设置默认版本
nvm alias default 22

下一步