图片与外部资源

源码字段与浏览器资源分开

Markdown 保存可持久资源地址，浏览器可能需要短期签名 URL、Blob 或内部资源接口。Image.configure({ resolve }) 负责把源码目标转换为 { url, release? }，不是把凭证写进图片语法。

下面是完整的同源资源接入。它只接受 /assets/<id>，需要应用自行实现 GET /api/assets/:id，本网站不会向这个演示地址发送请求。

import { Image } from "@quirekit/msfe-image";
import { StarterKit } from "@quirekit/msfe-starter-kit";
/** A same-origin asset resolver; authentication remains in the host fetch policy. */
export const PrivateImages = Image.configure({
  /** @param source - Canonical asset reference. @param signal - This image's lifetime. @returns One browser resource lease. */
  async resolve(source, signal) {
    const match = /^\/assets\/([a-zA-Z0-9_-]+)$/.exec(source);
    if (!match) throw new Error("unsupported-asset-reference");
    const response = await fetch(`/api/assets/${encodeURIComponent(match[1]!)}`, { signal, credentials: "same-origin" });
    if (!response.ok) throw new Error(`asset-http-${response.status}`);
    const blob = await response.blob();
    if (!/^image\/(png|jpeg|webp|gif)$/.test(blob.type) || blob.size > 5_000_000) throw new Error("unsupported-image");
    const url = URL.createObjectURL(blob);
    return { url, release() { URL.revokeObjectURL(url); } };
  },
});
/** Replace the preset's image owner; the host must implement GET /api/assets/:id. */
export const privateImageKit = StarterKit.configure({ image: PrivateImages });

privateImageKit 替换了 StarterKit 的 image 项，避免同名重复安装。源码中的 /assets/ 相对路径经过 host resolver 变成 Blob URL；资源释放时撤销该 URL。示例限制图片类型与 5 MB 大小，可按真实存储协议调整。

粘贴、拖入与上传

图片功能自带粘贴与拖入：剪贴板或拖放中只有图片文件时接管，存好后在落点插入 ![替代文字](<地址>)。上传期间落点由源码锚点保持，只读时不处理。图片存到哪里由 upload 决定：

import { Image, type ImageUploader } from '@quirekit/msfe-image'

const uploader: ImageUploader = {
  async upload(file, { source, name, signal }) {
    const body = new FormData()
    body.append('file', file, name ?? 'image')
    const response = await fetch('/api/assets', { method: 'POST', body, signal })
    if (!response.ok) throw new Error('upload-failed')
    return (await response.json()).url // 写入 Markdown 的持久地址
  },
}

Image.configure({ upload: uploader })

提供 upload：上传完成后写入返回的地址；某张图片失败时不写入它，提示由宿主在 upload 里给出。source 区分粘贴、拖入、对话框、Word 导入与 AI 等入口，可用于配额或命名。
省略 upload：PNG、JPEG、GIF、WebP 内联为 data: 地址，文档自包含但会变大；SVG 不内联，需要宿主上传。
upload: false：不处理粘贴与拖入，交给应用自己的扩展。

resolve 是可选的反向查询，导出 Word、PDF 时把存储地址取回为 data URI。

插入命令

const inserted = editor.commands.insertImage({
  url: '/assets/diagram_42',
  alt: '系统结构图',
  title: '架构评审',
})

命令验证字段并编码为 Markdown。自己实现上传入口（如对话框）时，先捕获目标、上传文件、取得持久地址，再执行命令；长时间等待使用映射锚点，取消或换文档后不应插入到新的光标位置。

内置 Image 在调用 resolver 之前就校验源码地址；不接受 asset: 等自定义协议。使用安全相对路径或 HTTPS 地址作为持久标识。若必须支持新协议，需要自己的字段校验和 codec，不能只换 resolver。

图片与外部资源

源码字段与浏览器资源分开

粘贴、拖入与上传

插入命令

更换图片组件

链接与外部打开策略

验证