Hexo 博客 + Obsidian：写作组合配置

我一直在找一个既能舒适写 Markdown，又方便管理文章、图片和草稿的工具组合。最后选择了 Obsidian + 静态博客框架：Obsidian 负责写作和资料管理，Hexo 负责生成静态博客。

这套组合的关键不是“用 Obsidian 写字”这么简单，而是让写作目录、图片目录、frontmatter、预览和发布路径都能长期保持一致。

为什么选择 Obsidian

Obsidian 的优势是本地优先。文章就是 Markdown 文件，不依赖某个云服务，也更适合和 Git、Hexo、Astro 这类静态站框架一起使用。

目录设计

最重要的原则是：Obsidian vault 应该指向博客源码目录，而不是生成后的 public 目录，也不是 GitHub Pages 发布仓。

推荐结构：

blog-source/
├─ _config.yml
├─ package.json
├─ source/
│  ├─ _posts/
│  │  └─ hello-hexo.md
│  └─ images/
└─ themes/

核心规则：

• 文章写在 source/_posts。
• 图片放在 source/images 或统一图片目录。
• 发布仓只接收生成产物，不在发布仓里写 Markdown。
• 不把 Obsidian 专属语法直接发布到博客。

这样做的好处是，Obsidian、Hexo 和 Git 看到的是同一批源码文件，减少同步和复制错误。

Obsidian 设置

在 Obsidian 里打开博客源码目录后，需要重点检查“文件与链接”设置：

设置 -> 文件与链接
附件默认存放路径: source/images
新建链接格式: 尽量使用 Markdown 链接

插入图片时，最终发布文章应使用标准 Markdown：

图片说明: /images/example.png

不要在最终博客文章中留下 Obsidian 的 wiki-style 图片嵌入语法。博客发布前统一改成标准 Markdown 图片语法。

Frontmatter 规范

Hexo、Astro、Hugo 这类静态站都依赖 frontmatter 描述文章元信息。写作时建议统一字段：

---
title: 文章标题
date: 2026-01-20 19:00:00
updated: 2026-01-20 20:00:00
tags:
  - Hexo
  - Obsidian
categories:
  - 工具工作流
---

迁移到 Astro 后，可以改成：

---
title: "文章标题"
pubDatetime: 2026-01-20T19:00:00+08:00
modDatetime: 2026-01-20T20:00:00+08:00
category: "工具工作流"
tags: ["Hexo", "Obsidian"]
description: "一句话描述文章内容。"
---

重点不是字段名完全一致，而是同一个站点内部必须一致。否则归档、标签、RSS、SEO 和搜索索引都会变得不稳定。

新建文章流程

如果还在使用 Hexo，推荐用命令生成文章：

hexo new post "文章标题"

然后在 Obsidian 中编辑生成的 Markdown 文件。这样 frontmatter 更稳定，也不容易把文章放错目录。

如果使用 Astro，通常直接在 src/content/posts 下创建 Markdown 文件，并让内容 schema 校验字段。无论使用哪种框架，写作流程都可以保持一致：

创建文章
  -> 补 frontmatter
  -> 写正文
  -> 插图
  -> 本地预览
  -> 构建检查
  -> 发布

本地预览和发布

写完之后先本地预览：

hexo clean
hexo generate
hexo server

确认页面、图片、代码块和表格都正常后再发布：

hexo deploy

迁移到 Astro 后，对应命令变成：

npm run build
npm run preview

无论工具怎么变，“先本地验证，再推线上”这条规则不变。

常见问题

图片在 Obsidian 正常，博客里不显示

优先检查三件事：

1. 图片文件是否真的进入博客源码目录。
2. Markdown 里引用的是站点发布后可访问的路径。
3. 是否使用了 Obsidian 专属图片语法。

Obsidian 可以识别很多本地写作语法，但静态博客只认识最终的 HTML 和标准 Markdown。

文章在 Obsidian 正常，博客里格式错乱

常见原因包括：

• 表格前后缺空行。
• 代码块没有正确闭合。
• frontmatter 缩进错误。
• 使用了 Obsidian callout 或 wiki link，但主题没有处理。
• 文章里混入旧主题导航、上一篇下一篇、HTML 残片。

迁移旧文章时，要把它当成内容重建，而不是把生成后的 HTML 直接复制回来。

发布仓里能不能直接改文章

不建议。发布仓是生成产物，应该只保存 HTML、CSS、JS、图片和索引文件。真正的文章源码应该保存在博客源码仓里。

这次迁移后，旧发布仓继续作为 GitHub Pages 输出仓，Astro 源码工程负责长期写作和维护。

复盘

Obsidian + 静态博客的组合适合长期技术写作，但前提是目录和规则清晰。真正重要的是三件事：

• 文章源码可维护。
• 图片资产可找回。
• 发布链路可验证。

如果这三件事没做好，主题再漂亮，迁移时仍然会变成一堆难以还原的 HTML 和断图。