自动图片转换

Jamdesk 可以在构建时将 PNG 和 JPG 图片转换为 WebP 格式。WebP 文件通常比原图小 60%–80%，且画质没有明显损失。无需手动处理图片，页面加载也会更快。

该功能默认关闭。请在你的 docs.json 中开启它。

启用功能

在你的 docs.json 中添加 images.convertToWebp 字段：

{
  "images": {
    "convertToWebp": true
  }
}

这是唯一的开关。仪表板的设置页面会在 Config Highlights 下显示当前状态，但它本身没有开关。docs.json 是唯一的依据。

转换哪些内容

转换后的图片保留原文件名，扩展名变为 .webp。Jamdesk 会改写 MDX、自定义 CSS、自定义 JS 和 docs.json 中的所有引用。你无需修改任何路径。

保留原格式的内容

即使开启了转换，部分图片也会保持不变。

网站图标（Favicon）。 并非所有浏览器或邮件客户端都能稳定渲染 WebP 格式的网站图标。

社交媒体图片（seo.metatags 中的 og:image 和 twitter:image）同样保持原格式。Facebook、LinkedIn、WhatsApp 以及较早版本的 Twitter/X 等社交平台的爬虫并不都支持 WebP。预览卡片显示失败比 JPG 文件稍大一些要严重得多。

未使用的图片也不会被转换。/images 目录中未被 MDX 或配置文件引用的文件，仍会以原始格式上传到 CDN。

当 WebP 输出文件比源文件更大时，Jamdesk 会保留原图。这种情况常见于已经过压缩的 JPG 以及非常小的 PNG。它们会在构建统计中显示为 skipped。

background.image 会被转换。它是由浏览器渲染的全屏背景图。

构建进度指示器

开启该功能后，仪表板的构建进度列表中会在“Building documentation”和“Uploading to CDN”之间显示一个 Optimizing images 步骤。jamdesk deploy CLI 的终端进度输出中也会显示同样的步骤。功能关闭时，该步骤不会出现。

构建缓存

Jamdesk 会在构建清单中为每个源图片存储一个哈希值。对于自上次构建以来未发生变化的文件，Jamdesk 会跳过转换，直接复用缓存的 WebP。即使有数百张图片，重新构建也能保持快速。

失败处理

当某张图片转换失败（文件损坏、内存不足、格式异常）时，Jamdesk 会保留原图，构建的其余部分继续进行。

构建日志

你的构建日志中会包含类似下面的一行：

Optimizing images... done (4 converted, 2 cached, 1 skipped, 0 failed, saved 1.2 MB)