我一直将Obsidian作为日常写作的主要工具，并想要能够将双链笔记一键转换为独立博客，因此采用了 Obsidian + Hexo + GitHub Pages 的组合方案。从零开始搭建到最终稳定上线，过程中遇到了诸多挑战——链接失效、图片异常、缓存不更新、访问速度慢、路径错乱等问题层出不穷。
这篇文章完整记录从搭建到极致优化的全过程，把所有遇到的问题、解决方案、优化技巧全部整理好，既是个人复盘，也给同样走这条路的朋友一份避坑指南。
整体技术栈与搭建思路
我的目标很简单：
- 在 Obsidian 里无感写作，支持双链、相对路径、本地图片；
- 一键发布到线上博客，不用手动复制粘贴、改格式；
- 博客托管免费、稳定，即 GitHub Pages；
- 速度快、体验好、SEO 友好、无冗余 bug。
最终定型方案：
Obsidian（写作） → Hexo（生成静态站） → GitHub Pages（托管） → uniCloud/CDN（加速）
搭建阶段：核心问题与解决方案
刚把框架搭起来时，博客根本没法直接用 ——Obsidian 原生格式和 Hexo 不兼容，各种链接、图片、路径全炸了。
Obsidian 博客发布自动化
Obsidian笔记发布博客自动化：全程无需手动修改
解决方案：✅从零到一键发布：Obsidian + Hexo + GitHub Pages 个人博客搭建指南
双链 / 相对路径无法在 Hexo 识别
Obsidian 习惯用 [[文件名]] 和相对路径图片，直接放到 Hexo 会全部 404。
解决方案：✅ Hexo 插件：自动转换 Markdown 相对路径链接
链接不规范
默认链接带日期、中文、乱码，既不美观也不利于搜索引擎。
解决方案：✅Hexo永久链接最佳实践：终极方案与优化指南
永久链接导致搜索失效
url设置永久链接后导致搜索跳转失效 404
解决方案：✅Hexo 搜索跳转失效？一招解决链接域名丢失问题
标注语法失效
Obsidian中的标注语法，无法正常展示
解决方案：✅Hexo插件：Obsidian标注语法兼容
tabs语法失效
Obsidian中的tabs语法失效，无法正常展示
解决方案：✅Hexo插件：Obsidian tabs语法兼容
图片默认 alt 属性冗余、影响美观
Hexo 会自动生成图片 alt 文本，样式突兀、影响阅读体验。
解决方案：✅Hexo插件：移除图片默认 alt 属性
一键去掉默认 alt，保持界面清爽。
图片体积大、加载慢、耗流量
直接上传 Obsidian 原图，页面打开又卡又慢。
解决方案：✅图片压缩与格式优化指南
批量压缩、WebP 格式替换、自适应图片，速度提升数倍。
发布与加速
CDN
CDN 缓存顽固，清缓存无效，更新博客样式看不到最新版。
解决方案：✅jsDelivr 缓存刷新与版本控制
掌握强制刷新策略，实现发布即生效。
GitHub Pages 在国内访问慢、不稳定
作为国外托管服务，大陆访问延迟高、偶尔打不开。
终极优化方案：✅uniCloud加速GitHub Pages博客访问
免费、高速、国内节点加速，访问速度直线飙升。
最终成果
现在我的博客实现了：
- Obsidian 写完即发布，无需任何格式调整；
- 链接规范、图片轻量化、页面加载极快；
- 国内访问速度快、稳定不掉线；
- 无 bug、无失效链接、无冗余代码；
- 全自动工作流，真正意义上一键部署。
全流程文章索引（建议收藏）
从零到一键发布：Obsidian + Hexo + GitHub Pages 个人博客搭建指南
Hexo 插件：自动转换 Markdown 相对路径链接
Hexo永久链接最佳实践：终极方案与优化指南
Hexo 搜索跳转失效？一招解决链接域名丢失问题
Hexo插件：移除图片默认 alt 属性
Hexo插件：Obsidian标注语法兼容
Hexo插件：Obsidian tabs语法兼容
图片压缩与格式优化指南
jsDelivr 缓存刷新与版本控制
uniCloud加速GitHub Pages博客访问
