自动图片转换

Jamdesk 可以在构建期间将 PNG 和 JPG 图片转换为 WebP 格式。WebP 文件通常比原文件小 60%–80%，且不会出现明显的质量损失，因此页面加载速度更快，无需手动处理图片。

此功能默认处于关闭状态。在 docs.json 中启用它。

启用功能

将 images.convertToWebp 字段添加到 docs.json：

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

这就是唯一需要设置的开关。仪表板中的 Settings 页面会在 Config Highlights 下显示当前状态，但不会提供单独的切换开关。docs.json 是唯一可信来源。

转换哪些内容

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

保留原格式的内容

即使启用了转换，某些图片也会保持不变。

网站图标。 并非所有浏览器或电子邮件客户端都能可靠地渲染 WebP 网站图标。

社交媒体图片（seo.metatags 中的 og:image 和 twitter:image）也会保留原格式。Facebook、LinkedIn、WhatsApp 以及较旧版本的 Twitter/X 等社交爬虫并不都支持 WebP，而预览卡片显示异常比 JPG 文件稍大更糟糕。

未使用的图片也会被跳过。如果某个文件位于 /images 目录中，但 MDX 或配置中没有引用它，原文件仍会上传到 CDN，但不会进行转换。没有必要为没有任何链接指向的内容消耗 CPU。

不会从转换中受益的图片会保留原格式。如果 WebP 输出文件会比源文件更大（已压缩的 JPG 和非常小的 PNG 中经常出现这种情况），Jamdesk 会保留原文件。这些图片会在构建统计信息中显示为 skipped。

有一项内容确实会被转换：background.image。它是由浏览器渲染的全屏背景，因此与其他图片一样可以从 WebP 中受益。

构建进度指示器

启用此功能后，仪表板的构建进度列表中会显示 Optimizing images 步骤，位于 "Building documentation" 和 "Uploading to CDN" 之间。jamdesk deploy CLI 的终端进度输出中也会显示相同步骤。关闭此功能后，该步骤完全不会出现。

构建缓存

Jamdesk 会在构建清单中存储每个源图片的哈希值。如果文件自上次构建以来没有变化，系统会跳过转换并重新使用缓存的 WebP。即使有数百张图片，重新构建也能保持较快的速度。

失败处理

如果任何单张图片的转换失败（文件损坏、内存不足或格式异常），系统会保留原文件，并继续其余构建流程。你的文档不会因图片转换错误而无法正常运行。

构建日志

除了仪表板中的指示器外，构建日志还会包含类似以下内容的一行：

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