Hexo 添加文章完整教学
前言
Hexo 是一款基于 Node.js 的静态博客框架，写好 Markdown 文章后，一条命令就能生成漂亮的静态网页。本文面向刚接触 Hexo 的朋友，把”怎么添加一篇文章”这件事讲透——包括新建文章、Front-matter 配置、标签、分类、封面、图片引用、本地预览与部署，全程配示例。
本文以你当前使用的 Butterfly 主题为例，命令对其它主题同样适用。
两种新建文章的方式
方式 1：使用命令自动生成（推荐）
在项目根目录打开终端，执行：
1 | hexo new "我的第一篇文章" |
执行后会在 source/_posts/ 下生成 我的第一篇文章.md，并自动带上基础 Front-matter：
1 | --- |
你还可以指定布局（layout），Hexo 默认有 post（文章）、page（页面）、draft（草稿）：
1 | hexo new post "文章标题" # 普通文章（默认） |
草稿写好想发布时，用 hexo publish 草稿标题 移到 _posts。
方式 2：手动新建 Markdown 文件
直接在 source/_posts/ 目录里新建任意 .md 文件，自己补全 Front-matter 即可。文件名的日期前缀可选，Hexo 会以 Front-matter 里的 date 为准。
小技巧：文件名建议用英文或拼音，避免某些环境下中文路径出问题；标题用 Front-matter 的
title显示中文即可。
Front-matter 完整字段详解
文件最上方的 --- 包裹区域叫 Front-matter，是文章的”元数据”。常用字段如下：
| 字段 | 说明 | 示例 |
|---|---|---|
title |
文章标题（必填） | Hexo 添加文章完整教学 |
date |
创建时间（必填） | 2026-07-15 10:00:00 |
updated |
更新时间（可选） | 2026-07-16 09:00:00 |
tags |
标签，可多个 | [Hexo, 教程] 或换行写法 |
categories |
分类，可多级 | 教程 或 [技术, 前端] |
cover |
文章封面图 | /images/xxx/cover.webp 或图片 URL |
description |
文章摘要/描述 | 从零讲清楚如何添加文章 |
top |
置顶（数字越大越靠前） | 10 |
comments |
是否开启评论 | true / false |
toc |
是否显示目录 | true / false |
sticky |
类似 top 的置顶 | 10 |
标签的两种写法都合法：
1 | # 写法一：行内数组（推荐，简洁） |
标签（tags）的使用
标签是扁平、自由的关键词，用来横向标记文章主题，一篇文章可以打多个标签。
1 | tags: [Hexo, 教程] |
要点：
- 标签之间没有层级关系，都是并列的。
- 打过的标签会自动在标签页（
/tags/）聚合，点击可看同标签所有文章。 - 标签名一旦确定尽量保持一致（如统一用
教程而非混用教学），否则会分散成多个标签。 - 不想让某篇文章出现在标签云里，直接不写
tags即可。
分类（categories）的使用与层级
分类是有层级、有从属的结构，用来把文章归到树状目录里。
1 | # 单级分类 |
关键区别（新手最容易混淆）：
| 对比 | 标签 tags | 分类 categories |
|---|---|---|
| 结构 | 扁平、并列 | 树状、有层级 |
| 示例 | [Hexo, 教程] |
[技术, 前端] 表示 技术/前端 |
| 用途 | 横向打关键词 | 纵向归档栏目 |
| 页面 | /tags/Hexo/ |
/categories/技术/前端/ |
注意：分类里的多行写法不是多个并列分类，而是”父级 / 子级”的嵌套路径。例如
categories: [技术, 前端]会生成「技术」下挂「前端」的分类结构。
封面与摘要
封面 cover
1 | cover: /images/Hexo添加文章教学/cover.webp |
- 填本地路径（推荐）：图片放到
source/images/文章名/下，Hexo 生成时会自动复制到images/目录。 - 填网络 URL：直接贴图床/外链地址（如
https://.../xxx.webp）。 - 设为
false可强制不显示封面：cover: false。
摘要 description
1 | description: 从零讲清楚如何在 Hexo 添加文章、配置标签与分类。 |
摘要会显示在首页文章卡片和 SEO 描述里。若省略，Butterfly 会自动截取正文前若干字。
文章资源文件夹与图片引用
开启资源文件夹（推荐）
在 _config.yml 中设置：
1 | post_asset_folder: true |
开启后，每次 hexo new 会同时生成一个同名文件夹，专门放这篇文章的图片：
1 | source/_posts/ |
在文章中引用图片
资源文件夹开启后，用相对路径引用即可：
1 |  |
若未开启资源文件夹，图片放在 source/images/ 下，则用绝对路径：
1 |  |
建议开启
post_asset_folder，这样每篇文章的图片独立管理，搬家/删除文章时不会留垃圾文件。
写作与本地预览
文章用标准 Markdown 语法书写（标题、列表、代码块、表格、引用等）。写完后本地预览：
1 | hexo clean # 清空旧的公用缓存（public + db.json），排错利器 |
- 预览时修改文件会自动刷新，边写边看。
- 如果改了配置或主题没生效，先
hexo clean再hexo server。 - 也可用你项目里的封装脚本：
npm run preview（等价于 clean + generate + server）。
常用写作快捷键提醒：标题用 #~`######，代码块用三个反引号并注明语言，表格用 |` 分隔。
生成与部署
确认无误后，生成静态文件并部署：
1 | hexo generate # 生成静态网页到 public/ 目录，可简写 hexo g |
一条命令同时生成并部署：
1 | hexo g -d # generate + deploy |
部署目标在 _config.yml 的 deploy 字段配置（如 git 仓库地址）。首次部署前请确保已配好对应插件与仓库权限。
常用命令速查表
| 命令 | 作用 |
|---|---|
hexo new "标题" |
新建文章 |
hexo new page "标题" |
新建页面 |
hexo new draft "标题" |
新建草稿 |
hexo publish 标题 |
发布草稿 |
hexo clean |
清除缓存与旧产物 |
hexo server / hexo s |
本地预览 |
hexo generate / hexo g |
生成静态文件 |
hexo deploy / hexo d |
部署 |
hexo g -d |
生成并部署 |
hexo list |
列出文章/页面/标签/分类 |
新手常见问题
Q1：文章写了但首页看不到？
先确认文件在 source/_posts/ 下且 Front-matter 格式正确；改了配置就 hexo clean 再重新 server / generate。
Q2：标签和分类到底填数组还是字符串？
标签 tags 用数组（多个）或单值都行；分类 categories 多行写法表示层级，不是多个并列分类。
Q3：封面图不显示？
检查 cover 路径是否正确、图片是否真实存在/可访问；网络图注意防盗链。
Q4：中文文件名乱码或部署失败？
尽量让文件名用英文/拼音，标题中文放在 title 字段里。
Q5：本地能看，部署后样式没了？
多半是 _config.yml 里 url / root 配置不对，导致资源路径 404。
小结
添加一篇 Hexo 文章的核心流程就是：hexo new 新建 → 填好 Front-matter（标题/标签/分类/封面）→ 写 Markdown 正文与插图 → hexo s 预览 → hexo g -d 发布。把标签当”关键词”、分类当”栏目树”，文章结构就会清晰好维护。
祝你写作愉快！🎉
