feat: add Hexo article and refresh blog visuals

2026-07-26 09:19:47 +08:00
parent 7d3f8b078b
commit 806a85752f
7 changed files with 387 additions and 8 deletions
@@ -0,0 +1,377 @@
+---
+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 文件即可。