blog/source/_posts/Hexo添加文章完整教学.md

title, date, tags, categories, cover, description

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

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

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

一、准备工作

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

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

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

node -v
npm -v
hexo -v

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

source/_posts

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

二、创建一篇新文章

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

hexo new "我的第一篇文章"

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

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

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

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

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

hexo-add-post.md

三、认识 Front-matter

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

---
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 编写正文：

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

## 文章小标题

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

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

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

五、设置标签和分类

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

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

下面两种写法也都可以：

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

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

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

1. 使用图床或外部地址

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

正文中直接引用：

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

2. 使用博客本地图片

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

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

然后在文章中使用：

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

正文图片写法：

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

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

post_asset_folder: true

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

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

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

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

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

七、使用草稿功能

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

hexo new draft "未完成的文章"

草稿默认保存在：

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

预览草稿：

hexo server --draft

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

hexo publish "未完成的文章"

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

八、本地预览文章

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

hexo clean
hexo generate
hexo server

然后在浏览器访问：

http://localhost:4000

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

hexo clean && hexo server

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

九、生成静态文件

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

hexo clean
hexo generate

生成结果默认位于：

public

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

hexo generate --path hexo-add-post/

十、部署到远程服务器

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

hexo deploy

常见的完整发布流程是：

hexo clean
hexo generate
hexo deploy

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

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 中指定英文链接：

permalink: hexo-add-post/

3. 标签或分类没有出现

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

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

4. 图片无法显示

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

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

清理缓存并重新生成：

hexo clean
hexo generate

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

十二、推荐的完整工作流

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

# 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 文件即可。