Hexo 博客发布笔记完整教程

本篇记录从新建文章到部署上线的完整流程，方便以后查阅。

一、新建文章

1	hexo new "文章标题"

执行后会在 source/_posts/ 下生成 文章标题.md。如果 _config.yml 里开启了 post_asset_folder: true，还会同时生成一个同名文件夹 文章标题/，用来放图片等资源；本站当前没有开启，所以只有 .md 文件。

二、文章结构（Front-matter）

文章开头 --- 之间是 front-matter，用于配置文章元信息：

---
title: 文章标题
date: 2026-08-06 10:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类名
cover: /img/xxx.png
description: 文章摘要
---

常用字段说明：

字段	作用	必填
title	文章标题	是
date	发布时间	是
tags	标签（列表）	否
categories	分类（列表）	否
cover	封面图路径	否
description	摘要（首页显示）	否

三、写作与图片处理

用 Typora 或任意 Markdown 编辑器打开 .md 文件写作即可。

图片存放规则

本站目前的文章图片都放在图床上（GitHub 仓库 + jsDelivr，搭建方法见《图床搭建》），文章里直接引用完整的图片 URL，_config.yml 里的 post_asset_folder 保持 false。

如果想把图片和文章放在一起，需要先在 _config.yml 里把 post_asset_folder 改成 true。之后图片放在文章同名文件夹里，例如文章 我的笔记.md，图片就放在 我的笔记/ 文件夹下。下面两节说的都是这种本地图片的写法。

图片引用方式

文章里用裸文件名引用图片：

1	![图片说明](图片名.png)

注意：必须用裸文件名（不带文件夹前缀），例如 ![](photo.png) 而不是 ![](我的笔记/photo.png)。否则部署后图片会 404。

Typora 配置建议

如果用 Typora 写作，推荐这样配置：

偏好设置 → 图片 → “插入图片时” 选 “复制到指定路径”
路径填：./${filename}/（Typora 变量，自动替换成文章名）
勾选 “对相对路径使用 ./” 和 “应用上述规则到所有插入的图片”

这样图片会自动存到文章同名文件夹。但 Typora 生成的引用会带文件夹前缀，需要手动改成裸文件名，或安装 hexo-image-link 插件自动转换。

四、本地预览

1	hexo server

访问 http://localhost:4000/ 预览效果。修改文章内容保存后刷新浏览器即可看到，无需重启服务。

预览草稿：

1	hexo server --draft

按 Ctrl+C 停止服务。

修改 _config.yml 或主题配置后必须重启 hexo server 才生效；只改文章内容不用重启。

五、部署到 GitHub Pages

写完满意后，一键部署：

1	hexo clean && hexo generate && hexo deploy

简写形式：

1	hexo clean && hexo g && hexo d

各步骤作用：

命令	作用
hexo clean	清理缓存（删 `db.json` 和 `public/`）
hexo generate	生成静态文件到 `public/`
hexo deploy	把 `public/` 推送到 GitHub 仓库

部署后约 30 秒到 2 分钟，GitHub Pages 自动构建完成即可访问。

六、访问博客

部署完成后访问主页：

1	https://zenty-me.github.io/

文章地址格式（_config.yml 里的 permalink: posts/:abbrlink/，abbrlink 见《文章分类、置顶与短链配置》）：

1	https://zenty-me.github.io/posts/abbrlink值/

GitHub Pages 有 CDN 缓存，部署后如果看到的还是旧内容，Ctrl+F5 强刷或等 1-2 分钟。

七、草稿机制

不想发布的文章放在 source/_drafts/ 目录，不会被生成和部署。

新建草稿：

1	hexo new draft "草稿标题"

把草稿转为正式文章（从 _drafts/ 移到 _posts/）：

1	hexo publish "草稿标题"

发布后记得执行部署命令。

八、常用命令速查

命令	作用
`hexo new "标题"`	新建文章
`hexo new draft "标题"`	新建草稿
`hexo publish "标题"`	草稿转正式
`hexo server`	本地预览
`hexo server --draft`	预览含草稿
`hexo clean`	清理缓存
`hexo generate`	生成静态文件
`hexo deploy`	部署到远程
`hexo clean && hexo g && hexo d`	一键发布
`hexo list post`	列出所有文章
`hexo version`	查看版本

简写：g = generate，s = server，d = deploy，c = clean

九、常见问题

1. 修改配置后预览没变化？

改了 _config.yml 或主题配置文件需要重启 hexo server。只改文章内容不用重启。

2. 图片显示不出来？

按顺序检查：

如果用的是图床，先在浏览器里直接打开图片 URL，确认能访问。用本地图片时再按下面检查：

确认图片放在文章同名文件夹里（不是 assets/ 或其他目录）
确认引用是裸文件名 ![](图片.png)，不带文件夹前缀
确认 _config.yml 里 post_asset_folder: true 已开启
确认 marked 配置了 postAsset: true

3. 部署后看不到更新？

GitHub Pages 有缓存，等 1-2 分钟或 Ctrl+F5 强刷。也可以去 GitHub 仓库的 Actions 页面查看部署状态。

4. 草稿为什么没部署上去？

_drafts/ 下的草稿默认不生成、不部署。用 hexo publish "标题" 转为正式文章后再部署。