---
title: 自动图片转换
description: >-
  在 Jamdesk 中启用 PNG 和 JPG 到 WebP 的自动转换，缩小图片体积并加快页面加载，无需手动处理。
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

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

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

## 启用功能

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

```json docs.json
{
  "images": {
    "convertToWebp": true
  }
}
```

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

## 转换哪些内容

| 源格式 | 是否转换 |
|--------|----------|
| PNG | 是 |
| JPG / JPEG | 是 |
| SVG | 否（已经是矢量格式） |
| GIF | 否（会丢失动画） |
| ICO | 否（尺寸太小，转换意义不大） |
| WebP | 否（已经过优化） |

转换后的图片会保留原文件名，并使用 `.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。即使有数百张图片，重新构建也能保持较快的速度。

## 失败处理

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

## 构建日志

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

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

| 字段 | 含义 |
|-------|---------|
| converted | 本次构建中从 PNG/JPG 转换为 WebP 的图片 |
| cached | 从上次构建中沿用的未发生变化的图片 |
| skipped | 保留原格式的图片（受保护字段、未使用文件或无需转换的格式） |
| failed | 转换失败的图片（保留原文件） |
| saved | 所有转换后的图片总共减少的字节数 |