IMA 笔记中 Markdown 图片引用的两条隐含规则

赵裕(vimerzhao)
系统与工具
本文约 1800 字，阅读需 4 分钟。

write by ai

起因：一篇明明有图却一张也显示不出来的笔记

我在 IMA 的“外部阅读”知识库中保存了一篇带有大量配图的 Markdown 笔记。原始文件的目录结构很简单：Markdown 文件和 assets/ 文件夹位于同一目录，图片通过标准的相对路径引用：

图片引用：`assets/image-001.webp`
图片引用：`assets/image-002.webp`

从文件系统的角度看，文件和引用都没有问题。但把这组文件导入 IMA 后，笔记中的图片一张也没有显示出来。

这件事引出了一个问题：IMA 导入 Markdown 时，究竟如何处理图片引用？

排查过程

确认图片确实存在

首先通过知识库的文件管理接口逐级查看目录，确认 assets/ 目录中的图片都存在，文件名也与 Markdown 中的引用一致。

因此，问题不是图片文件缺失，也不是引用中的文件名拼写错误。

查看导出后的 Markdown

将笔记从 IMA 导出为 Markdown 后，原来的相对路径被改写成了类似下面的形式：

导出后的图片引用：`笔记名称.assets/image-001.webp`

这说明 IMA 在导入或导出过程中确实会处理图片引用，但目录中的图片并没有因此自动成为笔记正文可以访问的资源。仅仅让 Markdown 文件和 assets/ 文件夹处于同一目录，并不足以让 IMA 渲染图片。

尝试使用 Base64 内嵌图片

随后把图片编码为 Base64，直接写入 Markdown：

图片引用：`data:image/webp;base64,UklGRthNAABXRUJQVlA4...`

通过 push_note 上传后，图片可以正常显示。再次导出笔记时，Base64 内容已经不见了，引用变成了类似下面的 URL：

图片引用：`https://ima-notebook-prod.image.myqcloud.com/.../file_manager/019f60c0d5d2...webp?q-sign-algorithm=sha1&...`

从这个结果可以确认，IMA 会识别 Markdown 中的 Base64 图片，将图片提取并上传到自己的对象存储，然后把原来的内嵌内容替换为图片 URL。

两条隐含规则

规则一：相对路径不会自动关联同目录资源

即使图片位于 Markdown 文件旁边的 assets/ 子目录中，IMA 也不会像本地 Markdown 编辑器那样，根据相对路径自动读取并关联图片。

换句话说，下面这种组织方式在本地文件系统中是完整的，但不一定能在 IMA 中正常显示：

note.md
assets/
  image-001.webp
  image-002.webp

将 Markdown 文件和 assets/ 文件夹一起导入，也不能据此推断图片会被自动上传。

规则二：可直接获取的图片会被转换为 IMA 资源

如果图片内容以 IMA 能够直接获取的形式提供，例如：

  • 以 Base64 形式内嵌在 Markdown 中；
  • 使用无需额外登录或鉴权的公网 URL；

IMA 就可以读取图片内容，并将其上传到自己的图片存储，再替换 Markdown 中的原始引用。

这解释了为什么 Base64 方案能够正常工作：对 IMA 来说，图片已经包含在提交的 Markdown 内容中，不需要再推断本地文件和笔记之间的关系。

需要注意的是，导出结果中的 URL 带有签名参数。它能否长期有效、是否会因为权限或签名过期而失效，应该以 IMA 的实际存储策略为准，不能仅凭 URL 形式把它称为永久链接。

为什么会采用这种处理方式

从笔记系统的角度看，这种设计是可以理解的。

相对路径依赖原始文件系统。Markdown 文件一旦脱离原来的目录，assets/image-001.webp 就失去了明确的解析上下文。外部 URL 依赖源站，源站下线、权限变化或网络环境变化，都可能导致图片无法显示。内网 URL 则还会受到访问环境的限制。

而在导入时把图片转换为 IMA 自己管理的资源，可以让笔记不再依赖原始本地目录结构。它的思路类似于浏览器保存完整网页时，把网页依赖的图片一并下载下来，只是这个过程发生在云端。

实践建议

如果需要向 IMA 导入带图片的 Markdown，可以按下面的优先级选择方案：

图片引用方式 结果 说明
本地 assets/ 相对路径 不可靠 IMA 不会自动解析同目录资源
Base64 内嵌 已验证可用 IMA 可以直接读取并转换为自己的图片 URL
公网图片 URL 通常可用 需要保证导入时无需登录即可访问
内网或需要登录的 URL 不建议 IMA 可能无法获取图片内容

对于少量图片，Base64 是最直接的解决方案。图片较多或体积较大时，Base64 会显著增加 Markdown 内容体积，此时更适合先将图片放到稳定、可公开访问的存储服务，再引用公网 URL。

小结

这次排查得到的核心结论是：IMA 不会根据 Markdown 的相对路径自动搬运本地图片，但能够处理它实际可以获取到的图片内容。

因此，导入带图 Markdown 时，不要只把 assets/ 文件夹和 Markdown 文件放在一起就认为资源关系已经建立。应该使用 IMA 能直接读取的图片形式，并在导入后通过预览或导出结果确认图片是否已经被转换为 IMA 管理的资源。

总阅读量次。