Hexo 博客无法复制 Markdown 本地图片？我写了一个插件

不知道现在大家写博客、文章还多不多我一直在用 Obsidian Markdown 写文章然后用 Hexo 生成静态站点发布到 GitHub Pages绑定到域名 xiaoming.io。几年前我写过一篇文章分享我是怎么构建笔记和博客系统的。构建自己的笔记博客系统程序员版 | 搬砖的小明遇到问题最近我在 Obsidian 里面用了一个新插件它会把我本地的图片转成 WebP 格式保存。这样能大大节省存储空间图片画质也还不错。用了 WebP 之后我发现原先那套发博客的代码只支持JPG、PNG、GIF没有正常把 WebP 图片复制到发布目录里。我的第一反应是让 Codex 直接帮我解决这个问题它 Debug 了半天没有什么进展看来还是需要我人工参与一下。我又重新研究了一下 Hexo已经很多年没研究它了。之前它有个问题在本地写 Markdown 时如果用相对路径引用本地图片在有些情况不会把图片复制到public目录。几年前为了解决这个问题我魔改了 Markdown 的渲染器也就是hexo-renderer-markdown-it。在它解析完图片以后我会把每一张图片都复制到固定目录同时修改渲染的图片 URL 让其对应上。当时之所以这么做是因为我发现 Hexo 本身的 API 不会把每个 post 里的图片都暴露给我。为了拿到一篇 Markdown 里所有图片的路径我就不得不在渲染器里插一段自己的代码来实现这个效果。但这种实现思路非常不好耦合性太强。我改了现有渲染器以后只要渲染器一更新我又得重新改。这么多年来我一直用的都是旧版本渲染器没有更新。最近我又看了一下时隔多年Hexo 还是没有原生很好的解决这个问题。尽管它有一个post_asset_folder参数但这个参数只支持和 Markdown 文件同名的文件夹里的图片上传也就是推荐在 Hexo 里面创建 Markdown这太局限了。https://hexo.io/zh-cn/docs/asset-folders我也尝试在网上找现成插件确实有一些插件支持这个功能例如hexo-asset-image但这个项目已经无效并且不维护了。有人Fork了一个版本修复但是看起来和我想要的效果不太一样。决定重新开发第一版所以我决定让 Codex 帮我开发一个。我本来不知道这件事会不会很复杂没想到 Codex 直接帮我写了一个不到 100 行的 script放进项目里以后图片确实就能复制了比我原先的实现优雅很多。Codex 的实现思路很直接就是拿到 Markdown 源文件然后用几个正则表达式去找里面所有图片再把它们复制到目标目录。其实当年我一开始想到的也是这种方式。正则表达式比较难写担心写错识别出错误图片或者漏掉所以当时就直接走了魔改 Markdown 渲染器这条路快速把问题解决了。但在今天AI 写代码已经这么强了让 Codex 直接实现一个新的插件反而是一个更快、更简单的办法。于是我把这个插件发布到了 NPM 上也把我原来那个魔改插件去掉了重新改回原版的 Markdown 渲染器并且升级到了最新版。后来我又去 Hexo 的 GitHub 主页看了一下到现在还是一直有人提这个问题。我把这个插件网址回复在了那个 GitHub Issue 里。不知道这些提 Issue 的人现在还在不在用 Hexo 写博客还是已经迁移到别的工具上了。发现更多问题第二版当我实际用这个插件时发现它对图片的判断还是太简单了。Markdown 里引用图片有很多种情况。大概有这么几类相对路径比如当前目录、子目录或者父目录里的图片绝对路径比如以斜线开头的 Linux 路径或者 Windows 上带盘符的路径不是本地文件路径的情况比如data:这种 Base64 形式、#开头的路径或者http、https这种链接我去和 Codex 讨论它只处理了https链接等场景还有一些场景都没有处理。于是我就和 Codex 继续讨论把我想到的场景都补充进去了也写了针对这些场景的测试代码。写 test 也有一些细节。因为这是一个 Hexo 插件理论上最彻底的测试方式应该是端到端测试准备一个真实的 Hexo 环境放一些测试用的 Markdown 文件运行插件和编译过程再判断处理结果对不对。但 Codex 认为这样做会依赖 Hexo 的版本太重了比较容易出现兼容问题。所以它建议我用集成测试Mock 一个假的 Hexo 环境调用整个插件判断它是不是按照设计的方式工作有没有准确复制 Markdown 文件里引用的图片。当时我觉得 Codex 说的有道理集成测试也就够了因为主要是测试这些格式的解析逻辑。于是第二版就发出来了。更全面系统的设计第三版在我写这篇文章的时候又去网上搜了一些相关的资料包括 Hexo 官方文档我发现事情没有这么简单。例如 Hexo 里relative_link的配置选项可能会导致渲染不一样还有些用户可能会在图片文件名里有特殊字符等。我觉得有必要用更系统化的方式去实现这个工具。在之前我用 AI 做过好多个小工具说实话这个应该是真实解决现实问题当中功能最简单的一个项目。但是正因为它是最简单的一个我反而可以更清晰地学习如何用 AI 开发项目。因为它每一个步骤都相对简单我可以把重点放在思考开发流程上而不是让注意力陷入过多设计实现细节里出不来。同时它也不是简单到完全不需要思考的程度它也在解决一个有多种可能分支的现实问题有一定的研究价值。1、确定核心目标首先是理清这个项目的核心目标。核心目标的重点不只是这个项目要做什么还要关注这个项目不做什么。这个项目的名字叫hexo-relative-post-image顾名思义它的核心目标应该是只处理相对路径引用的图片文件。如果是绝对路径我们直接不处理并且在 log 里面报一个 warning通知用户自行处理。我们的设计思路是只做图片复制不去干涉 Markdown 渲染成 HTML 的过程。2、确定调研方向并调研确定了这个核心目标以后我们需要对 Markdown 有关的东西进行足够深入、系统的调研。这里面包括 CommonMark 对 Markdown 语法的规定是什么样的、支持什么样的图片引用方式。现有的 marked 和 markdown-it 这两个渲染器是怎么实现 Markdown 图片渲染的这两个渲染器在 Hexo 上又有什么样的图片相关的配置参数。目前已有的 Hexo 渲染器用户都报了什么样的 Issue能从这个 Issue 里面学习到哪些兼容性问题。我让 AI 把这些调研来源和结果都放在了 Reference 文件中。3、Spec 开发在这个调研完成以后就需要做一个详细的需求文档一般称为 Spec (Specification产品规格)。这个 Spec 里面除了有项目的核心目标还有从调研结果学来的东西有哪些语法格式需要考虑有哪些可能的兼容性问题需要处理。根据我们前面定的核心目标有些兼容问题是可以在插件里处理的而有些兼容问题则是和我们的设计目标冲突的应该不做处理而是直接报错抛给用户例如绝对路径引用图片。一开始我并没有把这个项目当成一个正经项目去做只是从一个 100 行的小脚本慢慢补全了所以前面的版本也没有 Spec。但是现在既然要更系统地实现这个项目Spec 就是必要的。一开始都是跟 AI 用几句话来描述需求但是当需求的边界条件、各种分支越来越多几句话就描述不清楚了。如果下次需要 AI 修改维护Spec 就是最重要的依据。聊天结束了上下文就没了而 Spec 是以文件形式保存在项目里的一直在。4、代码实现有了这个 Spec 以后才是写代码代码分为插件本身的实现代码和测试代码两块。实际上这个插件本身的代码量并不是很大只有一个几百行的文件。但它的文档以及它的测试代码反而比实现代码更复杂。5、测试在测试代码的实现上之前的集成测试也满足不了需求了因为现在已经明确发现了不同的渲染插件可能也会有兼容性问题。所以我让 AI 又加了真正的端到端测试直接调用 Hexo 去验证兼容性问题。6、README 文档最后还有一个精简的 README是中英双语版的为了更加国际化默认英文版。README 分为两块。1、给普通用户看的要告诉用户怎么配置这个项目支持什么场景什么是不支持的。2、给想要参与开发项目的人和 AI 看的。会介绍环境配置、开发约定、具体的发布流程。实际上我的开发和发布都是让 AI 完成的这个时候文档就非常重要了如果没有文档AI 没办法每次都按照固定的流程开发和发布项目到时候就乱了。一点思考这是一个很简单的小项目用 AI 帮忙写也很轻松。但你会发现即使是这样的小项目也还是需要人工参与而且人工参与的程度并不低。这不是我不会用 AI而是很多实际问题本身就带着一堆隐性的背景知识。比如 Markdown 引用图片这件事由于Markdown编辑器五花八门用户真的会用各种奇奇怪怪的方式去写不只是标准语法还可能有 HTML 标签、文件名有特殊字符、不同语法格式、网络图片甚至不同渲染器还有自己的扩展。这些东西本身就没有一个固定范围。AI 默认不会把这些情况全都想一遍它一般只会给你一个“常见写法”的方案而不会一上来就帮你把所有边界情况都覆盖掉。如果要让 AI 自主探索所有可能的情况复杂度可能会指数级增加。这时候人的作用就体现出来了。我会用自己的经验去引导 AI比如我会想到要看现有生态比如 CommonMark 语法规范Marked、Markdown-it 这些主流渲染库相似插件以及它们的 Issue 里别人踩过的坑。这些东西 AI 不是查不到而是如果你不说它通常不会主动意识到“这一步是必要的”也不会自己把这些上下文串起来。本质上就是有些问题需要很大的上下文才能想清楚而这些上下文很多是隐性的不是直接搜就能出来的。人能做的是主动把这些上下文补上确定问题范围AI 更擅长的是在这个范围里面把事情做快、做全。那么利用 AI 开发项目的过程就是这样的1、我会利用我的知识经验引导 AI 去做调研确定问题范围让 AI 写 Spec写完了我再核查再让它修改直到 Spec 达到我比较满意的程度。2、让 AI 根据 Spec 把代码实现出来。理论上只要 Spec 写得足够完备代码实现就已经不重要了不需要太多人工参与就能被 AI 自动完成。甚至可以把 AI 当成编译器来看待AI 把 Spec 编译成代码就像过去编译器把高级语言编译成机器码一样。3、在编译过程中如果由于 Spec 写的有硬性的逻辑问题导致编译报错或者最终运行出来的效果和设想的不一样我不会单独去干预代码而是去完善 Spec然后重新编译成代码可以是增量编译的过程不用全部重写。整个项目的维护核心从过去的代码开始转向 Spec。用 AI 的话来说Spec 是 Single Source of Truth。Spec 可能需要花很长的时间去开发并且它是人工参与程度最高的文件。之后无论是实现代码还是测试代码还是 README只要有不对的就应该从 Spec 里面找参考依据。每次修改项目的时候都应该先改 Spec然后才是代码和 README。项目链接如果你也在用 Hexo遇到类似问题没解决可以留意一下这个插件。我发现似乎还有人在用我以前开发的那个版本的 Markdown 渲染器因为我看到 NPM 上还有下载量。我把原先那个项目标记成了 Deprecated也链接到了这个新项目。如果你是单纯想了解这个项目的 Reference、Spec 和 Test 是怎么写的也可以在项目中看到。这个项目的 GitHub 主页在这里https://github.com/jzj1993/hexo-relative-post-images如果觉得文章有帮助欢迎分享转发也欢迎关注我的公众号“搬砖的小明”及时获取更新