---
title: Hexo 添加文章完整教学
date: 2026-07-26 09:00:00
tags: [Hexo, 博客, 教程]
categories: 教程
cover: /images/Hexo 添加文章完整教学/efd8105608be4a03ba9d1ef67ce41b6f-blackwhite.png
description: 从创建文章到发布上线，完整介绍 Hexo 添加文章的流程、Front-matter 配置、图片管理和常见问题。
---

Hexo 是一个基于 Node.js 的静态博客框架。写文章时，我们只需要准备 Markdown 文件，Hexo 就会把它转换成 HTML 页面。

本文以一个已经安装好的 Hexo 博客为例，介绍从创建文章到发布上线的完整流程。

## 一、准备工作

开始之前，请确认已经安装：

- Node.js；
- npm；
- Hexo CLI；
- Git（如果需要部署到远程仓库）。

在博客根目录执行以下命令，确认环境正常：

```bash
node -v
npm -v
hexo -v
```

Hexo 博客的文章默认保存在：

```text
source/_posts
```

本文中的命令都应在 Hexo 项目根目录执行，也就是能看到 `_config.yml` 和 `package.json` 的目录。

## 二、创建一篇新文章

最推荐使用 Hexo 命令创建文章：

```bash
hexo new "我的第一篇文章"
```

执行成功后，Hexo 会在 `source/_posts` 目录生成一个 Markdown 文件，例如：

```text
source/_posts/我的第一篇文章.md
```

也可以直接使用 npm 脚本（如果项目已经配置）：

```bash
npx hexo new "我的第一篇文章"
```

文件名可以使用中文、英文或数字。为了兼容不同系统和部署环境，建议使用简洁的英文或拼音，例如：

```text
hexo-add-post.md
```

## 三、认识 Front-matter

新文章顶部由一对 `---` 包围的内容叫 Front-matter，它用于设置文章的标题、日期、标签等信息。

```yaml
---
title: 我的第一篇文章
date: 2026-07-26 09:00:00
tags: [Hexo, 教程]
categories: 博客
description: 这是文章摘要。
---
```

常用字段说明如下：

| 字段 | 作用 | 示例 |
| --- | --- | --- |
| `title` | 文章标题 | `title: Hexo 入门` |
| `date` | 发布时间 | `date: 2026-07-26 09:00:00` |
| `updated` | 修改时间 | `updated: 2026-07-26 10:00:00` |
| `tags` | 文章标签 | `tags: [Hexo, 教程]` |
| `categories` | 文章分类 | `categories: 博客` |
| `cover` | 封面图片 | `cover: /images/hexo/cover.jpg` |
| `description` | 摘要或描述 | `description: Hexo 使用教程` |
| `comments` | 是否开启评论 | `comments: true` |
| `toc` | 是否显示目录 | `toc: true` |
| `mathjax` | 是否启用数学公式 | `mathjax: true` |
| `permalink` | 自定义文章链接 | `permalink: hexo-add-post/` |
| `published` | 是否发布 | `published: false` |

其中 `title` 是必填项。其他字段是否生效，取决于当前主题是否支持。例如 Butterfly 主题支持封面、目录和评论等配置。

## 四、编辑文章正文

Front-matter 结束后，在下面使用 Markdown 编写正文：

~~~markdown
---
title: 我的第一篇文章
date: 2026-07-26 09:00:00
tags: [Hexo, 教程]
categories: 博客
---

## 文章小标题

这里是正文内容，可以使用 **粗体**、*斜体* 和 [链接](https://hexo.io/)。

```javascript
console.log('Hello Hexo!');
```
~~~

建议使用二级标题 `##` 作为正文的章节标题，不要在正文中重复写文章标题，因为主题通常会自动显示 `title`。

## 五、设置标签和分类

一篇文章可以有多个标签，但通常只设置一个主分类：

```yaml
tags:
  - Hexo
  - Markdown
  - 博客搭建
categories: 技术教程
```

下面两种写法也都可以：

```yaml
tags: [Hexo, Markdown]
categories: 技术教程
```

分类表示文章所属的栏目，标签表示文章涉及的主题。比如：分类可以是“教程”，标签可以是“Hexo”和“部署”。

## 六、添加文章封面和正文图片

### 1. 使用图床或外部地址

```yaml
cover: https://example.com/images/cover.jpg
```

正文中直接引用：

```markdown
![图片说明](https://example.com/images/example.jpg)
```

### 2. 使用博客本地图片

在 `source` 目录下创建图片目录：

```text
source/images/hexo-add-post/cover.jpg
```

然后在文章中使用：

```yaml
cover: /images/hexo-add-post/cover.jpg
```

正文图片写法：

```markdown
![Hexo 添加文章流程](/images/hexo-add-post/create-post.png)
```

如果希望图片和 Markdown 文件放在同一个目录，可以在 `_config.yml` 中启用：

```yaml
post_asset_folder: true
```

之后创建文章时，Hexo 会生成同名资源目录：

```text
source/_posts/我的第一篇文章.md
source/_posts/我的第一篇文章/
```

将图片放入该目录，并使用资源路径：

```markdown
{% asset_img example.jpg 图片说明 %}
```

不同主题对资源标签的支持情况可能不同。若显示异常，使用 `source/images` 加绝对路径通常更稳定。

## 七、使用草稿功能

如果文章还没有写完，可以创建草稿：

```bash
hexo new draft "未完成的文章"
```

草稿默认保存在：

```text
source/_drafts/未完成的文章.md
```

预览草稿：

```bash
hexo server --draft
```

写完后，将草稿发布到文章目录：

```bash
hexo publish "未完成的文章"
```

发布后文件会从 `source/_drafts` 移动到 `source/_posts`。

## 八、本地预览文章

保存文章后，启动本地服务器：

```bash
hexo clean
hexo generate
hexo server
```

然后在浏览器访问：

```text
http://localhost:4000
```

开发时可以使用简写命令：

```bash
hexo clean && hexo server
```

`hexo server` 通常会自动生成页面。若修改后浏览器没有更新，可以先执行 `Ctrl+C` 停止服务，再重新运行 `hexo clean && hexo server`。

## 九、生成静态文件

确认文章内容无误后，生成最终的静态页面：

```bash
hexo clean
hexo generate
```

生成结果默认位于：

```text
public
```

如果只想生成某一篇文章，可以使用：

```bash
hexo generate --path hexo-add-post/
```

## 十、部署到远程服务器

如果项目已经配置好部署参数，可以直接执行：

```bash
hexo deploy
```

常见的完整发布流程是：

```bash
hexo clean
hexo generate
hexo deploy
```

如果博客源码本身也使用 Git 管理，还需要提交并推送源码：

```bash
git add source/_posts/Hexo添加文章完整教学.md
git commit -m "docs: add Hexo post tutorial"
git push origin main
```

具体的部署命令取决于博客使用的 GitHub Pages、服务器、Vercel 或其他平台。不要把密码、令牌和私钥直接写入文章或提交到仓库。

## 十一、常见问题

### 1. 文章没有显示

依次检查：

1. 文件是否位于 `source/_posts`；
2. Front-matter 是否以 `---` 开始和结束；
3. `title` 和 `date` 是否正确；
4. 是否误设置了 `published: false`；
5. 是否执行过 `hexo clean`；
6. 文章日期是否晚于当前时间。

### 2. 中文文件名导致链接异常

部分服务器或主题对中文 URL 的处理不一致。可以在 Front-matter 中指定英文链接：

```yaml
permalink: hexo-add-post/
```

### 3. 标签或分类没有出现

确认字段格式正确，并检查主题是否开启了标签页和分类页。推荐使用：

```yaml
tags: [Hexo, 教程]
categories: 教程
```

### 4. 图片无法显示

检查图片是否位于 `source` 目录内、路径大小写是否一致，以及引用路径是否以 `/` 开头。部署到 Linux 服务器时，`Cover.jpg` 和 `cover.jpg` 会被视为两个不同文件。

### 5. 修改文章后页面仍是旧内容

清理缓存并重新生成：

```bash
hexo clean
hexo generate
```

同时清理浏览器缓存，或使用无痕窗口检查。

## 十二、推荐的完整工作流

以后每次添加文章，可以按照下面的顺序操作：

```bash
# 1. 创建文章
hexo new "文章标题"

# 2. 编辑 source/_posts/文章标题.md

# 3. 本地预览
hexo clean
hexo server

# 4. 确认无误后生成
hexo clean
hexo generate

# 5. 部署上线
hexo deploy

# 6. 如果源码使用 Git，则提交源码
git add .
git commit -m "docs: add new post"
git push
```

## 总结

Hexo 添加文章的核心流程只有四步：

1. 使用 `hexo new` 创建 Markdown 文件；
2. 编辑 Front-matter 和正文；
3. 使用 `hexo server` 本地预览；
4. 使用 `hexo generate` 和 `hexo deploy` 生成并发布。

掌握这套流程后，日常写作只需要专注于 `source/_posts` 目录中的 Markdown 文件即可。