第一篇博客：Hexo 写作、预览与发布完整教程

教程
, ,

这篇文章记录本站从写一篇 Markdown 到发布到 GitHub Pages 的完整流程。先分清三件事：文章写在 source 中，hexo generate 生成网页，hexo deploy 上传生成结果。修改本机文件不会自动更新线上网站。

一、先认识博客目录

文件或目录 用途 日常需要修改吗
_config.yml 网站地址、标题、主题和部署配置 改网站设置时修改
package.json Hexo、插件依赖和运行命令 安装插件时更新
source/_posts/ 已发表文章的 Markdown 文件 经常修改
source/_drafts/ 尚未发表的草稿 按需修改
source/images/ 图片资源 按需添加
source/about/index.md 关于页面 按需修改
themes/LIFANULTRA/ 本站主题的模板、样式和脚本 修改外观时使用
scaffolds/ 新文章和新页面的初始模板 需要统一模板时修改
public/ 生成的网站文件 不直接编辑
.deploy_git/ Git 部署插件使用的目录 不直接编辑

public 是生成结果。直接改其中的 HTML，下次重新生成时会被覆盖。需要保留的文章、图片和样式，应修改对应的源文件。

二、准备环境并进入博客目录

本站使用 Node.js、Git 和 Hexo。打开终端后可以检查：

1
2
3
node --version
git --version
hexo --version

如果提示找不到 hexo，安装全局命令行入口：

1
npm install -g hexo-cli

随后进入包含 _config.yml 和 package.json 的博客根目录。以下路径只是写法示例，需要换成自己的实际目录：

1
cd "C:\你的博客目录\blog"

首次配置项目，或从其他电脑复制源码后，安装项目依赖：

1
npm install

全局 hexo-cli 负责提供终端命令，项目里的 hexo 和插件负责运行网站。如果只安装了项目依赖，也可以在该目录中使用 npx hexo server；本站已配置全局入口，日常直接使用 hexo 即可。

三、新建文章与填写文章信息

新建一篇文章

1
hexo new post "我的实验记录"

Hexo 会根据模板，在 source/_posts/ 中创建文章文件。用文本编辑器打开这个 .md 文件即可写作。

文章顶部的 front-matter

文件开头两条 --- 之间是 YAML 文章信息，正文写在第二条 --- 下面。例如：

1
2
3
4
5
6
7
8
9
10
---
title: 我的实验记录
date: 2026-10-14 09:00:00
updated: 2026-10-14 10:30:00
categories:
  - 实验记录
tags:
  - 电化学
  - 数据处理
---
字段 用途 注意事项
title 网页显示的文章标题 含英文冒号等特殊字符时，建议用引号包住
date 文章发表时间 使用明确的日期和时间
updated 最后修改时间 修订后可以同步更新
categories 分类 多项列表可以表示分类层级
tags 标签 一篇文章可以有多个标签
description 文章简短描述 可选，适合写简洁摘要

YAML 缩进使用空格，不使用 Tab。sticky 等置顶设置是否有效，取决于主题或插件支持，不能仅加一个字段就默认会置顶。

摘要截断

在想结束首页摘要的位置加入：

1
<!-- more -->

本站首页主要显示文章列表；截断标记也便于以后使用摘要式列表或其他支持摘要的页面。

四、Markdown 的常用写法

标题层级

文章主标题由 front-matter 的 title 提供，正文通常从二级 Markdown 标题开始：

1
2
3
## 一级内容标题
### 二级内容标题
#### 三级内容标题

本站将正文中的 ##、###、#### 分别对应黑体、楷体和仿宋标题。不要为了改变字号跳过层级，层级同时影响文章目录和阅读结构。

粗体、斜体与组合强调

下面先给语法，再给实际显示效果：

1
2
3
**加粗中文 Bold 123**
*斜体中文 Italic 123*
***加粗且斜体 Bold Italic 123***

加粗示例：加粗中文 Bold 123。

斜体示例：斜体中文 Italic 123。

组合示例：加粗且斜体 Bold Italic 123。

反引号中的 **加粗语法** 只是代码展示，不会变成粗体。强调内容要放在代码块或反引号之外。某些中文字体没有原生粗体、斜体字形，浏览器会合成相应效果；西文优先使用 Times New Roman 的对应字形。

段落与列表

不同段落之间空一行。普通换行不一定会产生新的段落。无序列表使用 -，有序列表使用数字加英文句点：

1
2
3
4
5
6
7
- 检查原始数据
- 记录测试条件
- 保存处理结果

1. 新建文章
2. 本地预览
3. 生成并发布

链接

1
[Hexo 官方文档](https://hexo.io/docs/)

实际效果：Hexo 官方文档。本站用绿色区分链接，正文文字则随黑白模式切换。

引用说明

1
> 这里写引用或需要单独提示的说明。

本地预览正常，只说明本机页面可以显示。发布后仍需要检查线上文章和资源链接。

表格

1
2
3
4
| 项目 | 数值 | 单位 |
| --- | --- | --- |
| 测试温度 | 25 | °C |
| 静置时间 | 30 | min |

表格适合整理并列信息。内容过多时，拆成几个短表，比在手机上挤进一个大表更容易阅读。

行内代码与代码块

短命令用单个反引号，例如 hexo generate。多行代码使用三个反引号包围，并在开头标明语言：

1
2
3
4
```python
def hello():
    print("Hello, Hexo")
```

实际效果：

1
2
def hello():
    print("Hello, Hexo")

五、插入图片与附件

使用全站图片目录

本站当前未启用每篇文章独立的资源目录，日常可以把图片放在 source/images/ 下。例如文件位置是：

1
source/images/demo.png

文章中使用：

1
![图片说明](/images/demo.png)

上面的图片名称是示例，实际使用前必须放入对应文件。网页链接使用 /，不使用 Windows 路径中的 \；不要写 C:\... 这样的本机文件路径。

本站当前发布在域名根路径，/images/... 可以直接使用。如果以后迁移到带子目录的网站地址，需要重新核对资源路径。

附件

把附件放在 source/downloads/，例如 source/downloads/example.pdf，再引用：

1
[下载附件](/downloads/example.pdf)

附件和图片一样，上传后会成为网站可访问的文件。发布前检查文件内容，不要把未准备公开的原始记录当作测试附件。

六、输入数学公式

本站已启用 MathJax。行内公式使用一对美元符号：

1
$E = mc^2$

显示为 $E = mc^2$。

独立公式可以使用两对美元符号。为减少当前 Markdown 渲染器与公式语法之间的干扰，下面使用单行写法：

1
$$\Delta G = -nFE$$

$$\Delta G = -nFE$$

上下标和正体化学符号示例：

1
2
3
$\mathrm{V_2CT_x}$
$I_3^{-}$
$i_p = a v^b$

实际显示：$\mathrm{V_2CT_x}$、$I_3^{-}$、$i_p = a v^b$。

MathJax 从 CDN 加载。网络受限或脚本尚未加载时，可能暂时看到原始公式文本。普通正文里的英文和数字使用 Times New Roman，公式则由数学排版引擎绘制。

七、先在本地预览

在博客根目录启动：

1
hexo server

默认打开 http://localhost:4000/。预览时保持终端运行，结束后在终端按 Ctrl+C 停止服务。

如果端口已被其他程序占用，可以换一个端口：

1
hexo server --port 4001

修改文章后通常可以刷新预览页面。修改 _config.yml 后建议重启预览服务；修改主题样式但没有看到结果时，可以停止服务，再清理和重新生成。

发布前至少检查文章标题、日期、目录、粗体和斜体、图片、公式、链接，以及手机宽度下的排版。也要切换一次黑白模式，确认字体、字号和位置一致。

八、生成并发布到 GitHub Pages

本站地址为 https://blog.lifan.icu/，完整源码保存在 main 分支。推送后，Vercel 和 GitHub Actions 分别构建并发布生产网站。部署配置的核心部分为：

1
2
3
4
url: https://blog.lifan.icu

deploy:
  type: production

本站使用自定义生产部署脚本，发布前先提交源码：

1
2
git add .
git commit -m "Update blog"

GitHub 账号必须有仓库写入权限，本机 Git 需要完成登录。

日常更新

文章检查完毕后，运行：

1
hexo generate --deploy

简写是 hexo g -d。这条命令先在本地生成网站，再推送已提交的 main 分支；线上平台会从源码重新构建。

主题或缓存出现问题时

1
2
3
hexo clean
hexo generate
hexo deploy

hexo clean 删除生成缓存和 public，不删除 source/_posts/ 中的文章。hexo deploy 只推送已提交的源码，因此发布前必须先提交修改。

上传成功之后

Git 推送成功后，GitHub Pages 和 Vercel 还需要完成构建和发布。确认 Actions 流程成功、Vercel 生产部署就绪，再打开线上网站检查。本站只使用 main 分支，不生成预览部署。

本站地址：https://blog.lifan.icu/。

九、草稿与独立页面

草稿

1
2
hexo new draft "待完善的记录"
hexo server --draft

草稿放在 source/_drafts/。完成后，将对应草稿发布为文章：

1
2
hexo publish "待完善的记录"
hexo generate --deploy

hexo publish 将草稿转为文章；上传到 GitHub 仍需要后面的生成与部署命令。

独立页面

1
hexo new page "notes"

它会创建页面目录及 index.md。独立页面适合关于、说明或固定资料页；生成页面后，还需要按实际需求把对应地址加入主题导航。

十、常见问题

现象 优先检查
找不到 hexo 命令 全局 hexo-cli 是否安装，终端是否能找到 npm 命令目录
提示不是 Hexo 项目 是否进入包含 _config.yml 的博客根目录
配置解析失败 YAML 缩进、冒号、引号和 Tab 是否有误
线上内容没有更新 是否重新生成，Git 推送和 Pages 发布是否都成功
图片打不开 文件是否存在，大小写、路径和后缀是否一致
字体暂时不同 本地字体是否安装，CDN 字体切片是否成功加载
粗体或斜体没有变化 是否把语法放进反引号或代码块，强调标记是否完整
公式只显示源码 MathJax 是否加载，公式定界符是否成对，Markdown 是否改写了公式
主题修改后仍显示旧样式 停止预览，清理并重新生成，随后刷新浏览器缓存

本站优先使用本机字体，缺少时先显示系统字体，再加载对应的切片 CDN。Times New Roman 不存在时，西文 CDN 使用 Tinos 兼容回退；这不代表它就是 Times New Roman 原版。切换黑白模式不改变文字的字号与排版。

十一、一次完整的更新流程

  1. 在博客根目录新建文章，或编辑已有 .md 文件。
  2. 填写文章信息，整理正文、图片和附件。
  3. 启动本地预览，检查内容和手机排版。
  4. 运行 hexo generate --deploy。
  5. 确认 GitHub Pages 发布成功，再检查线上页面。

日常写作只需要记住两个常用命令：预览用 hexo server，更新网站用 hexo generate --deploy。遇到主题缓存问题，再使用清理、生成、部署三步流程。

官方参考：命令、写作、资源目录、Git 部署。