obsidian-image-converter

在 Obsidian 里重造一条图像流水线：obsidian-image-converter 技术拆解

项目背景与痛点

知识库写作有一个隐藏的技术债：图片资产的管理。Obsidian 采用本地 Markdown 加文件系统的架构，用户把截图、设计稿、手机照片直接拖进 Vault，于是很快就会出现一个混乱的 assets/ 目录，里面混杂着 4MB 的 PNG 截图、HEIC 原图、TIFF 扫描件，以及一堆 Pasted image 20240101xxxxxx.png。

这些文件在笔记里往往以 ![[img|300]] 的形式出现，只靠渲染层来约束显示尺寸；但磁盘上的字节数从没有减少过。同步到移动端、备份到 Git，动辄涨到几个 G。

主流做法是离开 Obsidian：用 TinyPNG 在线压缩，用 ImageOptim 离线压，用 iLoveIMG 转格式，再手动拖回来改链接。每多做一次往返，文件名和引用链接就多一层断裂风险。

obsidian-image-converter 的定位很明确：把"转换/压缩/缩放/标注/裁剪/重排"这整条图像流水线搬进编辑器上下文菜单。真正有价值的地方在于，它试图在不破坏 Obsidian 链接语义的前提下完成有损操作，这既是工程难点，也是它区别于普通图片工具的核心。

核心技术揭秘

先看约束条件。Obsidian 插件本质上是运行在 Electron 渲染进程里的 TypeScript 模块，能拿到 Node.js 运行时与文件系统 API，但在移动端（Capacitor 容器）上这些能力会被剥离。插件描述里点名支持 HEIC 和 TIF，这两种格式浏览器端的 Canvas 编解码器根本不认，所以它不可能走纯 HTMLCanvasElement.toBlob() 这条路，必然依赖原生图像库（sharp/libvips 一类，或等价的 Node 侧解码器）来打通格式矩阵。

这就解释了它为什么是一个 desktop-only 插件：用跨端能力换格式覆盖度，是一个清醒的取舍。

从调用链推断，它的数据流大致是这样一个漏斗：

我认为架构上有三个值得单独拿出来说的设计。

第一，参数解析层被抽象成一套"命名变量"模板引擎。 {filename}、{date}、{width}、{height} 这些占位符在批量转换时会被逐文件求值，生成目标文件名。这看起来是一个小功能，但它解决了批处理场景下最麻烦的一环——你无法用固定的输出名去处理一百张图。代价是需要配套的重名消解策略（后缀递增或覆盖确认），否则并发写入会直接撞车。

第二，图像管线与 Vault 写入是解耦的两段式。 解码、缩放、重编码在一个独立的作用域里完成（原生库调用通常跑在线程池，不阻塞渲染主线程），产物落到临时路径或内存 buffer，再进入 Vault 的写入流程。这个顺序很关键：如果先写后转，一旦编码失败就会留下半成品文件，污染目录。

第三，链接重写是这条流水线里最容易被低估的部分。 Obsidian 的图片引用有两种语法（![[wiki]] 与 ![](md)），还带可选的嵌入尺寸、别名、块引用锚点。转换后文件名变了，若不遍历 Vault 里的 Markdown 做引用替换，笔记就会集体变成断链。这类操作要么依赖 metadataCache 的解析结果精准定位，要么全库正则扫描——前者快但需要等待索引就绪，后者稳但开销大。插件选择了哪条路径不得而知，但这是所有"会改文件名"的 Obsidian 插件必须正面回答的问题。

另外一个精巧的分层：拖拽缩放改的是 Markdown 语法里的尺寸参数，而不是真的重采样图片。 非破坏性编辑与真正的压缩（改字节）被明确拆成两个动作，用户想清楚自己要哪一种。把"显示尺寸"和"文件体积"混为一谈的工具，最后都会把用户坑一遍。

功能亮点与差异

横向对比，同类插件（如 Image Toolkit、Local Images 等）大多只覆盖一两项：要么只做压缩，要么只做查看增强。这个项目的差异化在于把"批处理"当成一等公民：多选文件 → 一次性指定目标格式与质量 → 变量命名 → 全部落盘并重链。这在迁移旧库、把手机相册导入知识库时非常有用。

第二个亮点是格式覆盖面。WEBP/AVIF 这类现代格式的转出能力，配合 HEIC/TIF 的读入能力，让它成为少数能直接处理 iPhone 原图与扫描件的 Obsidian 工具。对摄影师、研究者、扫描归档类用户，这是刚需。

第三个是标注与绘制能力内嵌。裁剪、旋转、翻转、对齐、手绘批注这些操作如果放在外部工具里，会形成"图片-编辑器-图片"的往返开销；内嵌之后，流程变成单向的，创作心流不会被打断。

应用场景与落地建议

适合的场景很具体：长期维护的本地知识库、需要随 Vault 一起 Git 同步的团队仓库、大量截图沉淀的技术文档、以及素材体量已经影响到移动端加载速度的个人库。

落地时有几件事必须提前想清楚：

• 先备份，再批量转。 格式转换与压缩是破坏性操作，尤其"覆盖原文件"模式下没有后悔药。在 Vault 上开 Git 或做目录级快照，是成本最低的保险。
• 统一资产策略。 建议固定一个 attachments/ 或 assets/YYYY/MM/ 目录，配合命名变量把文件名规整化，避免后续同步时不同步大小写敏感问题。
• 留意桌面/移动的不对称。 转换只能在桌面端跑，移动端只能消费结果。跨设备协作的团队要明确"谁负责入库整理"。
• 慎用高压缩比。 WEBP 质量压到 60 以下，在文字截图上会出现明显的振铃噪点，反而是把可读性做没了。截图类建议 PNG 或高质 WEBP，照片类才适合激进压缩。
• 关注引用重写的完整性。 批量转换后抽几篇有代表性的笔记做抽查，确认嵌入尺寸、别名、块引用都没被破坏。

综合评价

优点： 痛点选得准，把散落在多个外部工具里的动作收敛到一次右键；批处理加变量命名是真做了工程；格式矩阵覆盖到 HEIC/TIF，实用性远超同类；非破坏性缩放与破坏性压缩的分层思路很克制。

不足： 桌面端独占这个架构选择会长期存在，移动用户只能被动接受结果；底层依赖原生二进制，插件体积与跨平台打包复杂度都不低，升级 Electron 时容易踩 ABI 兼容问题；破坏性操作的风险提示与回滚机制，从项目宣传上看不突出，这对新手不够友好；功能密度高也意味着 UI 认知负担不低。

一句话判断： 它不是那种"装上就忘"的轻量插件，而是需要你为图片资产定一套规范、然后让它去执行的重型工具。如果你的 Vault 里图片数量已经上千、体积已经失控，它值得进你的必装清单；如果你只是偶尔贴两张截图，Obsidian 自带的粘贴附件管理就够了。