geek
378 lines
8.3 KiB
Markdown
378 lines
8.3 KiB
Markdown
---
|
||
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
|
||
|
||
```
|
||
|
||
### 2. 使用博客本地图片
|
||
|
||
在 `source` 目录下创建图片目录：
|
||
|
||
```text
|
||
source/images/hexo-add-post/cover.jpg
|
||
```
|
||
|
||
然后在文章中使用：
|
||
|
||
```yaml
|
||
cover: /images/hexo-add-post/cover.jpg
|
||
```
|
||
|
||
正文图片写法：
|
||
|
||
```markdown
|
||
|
||
```
|
||
|
||
如果希望图片和 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 文件即可。
|