# WebP 图片压缩工具 · 介绍文档

> 在线地址：<https://xdoc.vip/webp.html>

> 所属站点：[Xdoc.vip — 网虫No代的个人博客](https://xdoc.vip)

## 一、工具简介

**WebP 图片压缩**是 xdoc.vip 产品页下的一款免费在线小工具，用于将 JPG / PNG / GIF 等常见图片**一键转换为 WebP 格式**并压缩体积。

WebP 是 Google 推出的现代图片格式，在视觉质量相近的情况下，体积通常比 JPEG / PNG 小 25%~50%，可显著加快网页加载速度、节省存储与带宽。本工具省去了安装桌面软件或命令行的麻烦，打开网页即可完成转换。

一句话概括工作流：

```

选择 / 粘贴 / 拖入图片 → 自动转换为 WebP → 对比预览 → 可调质量重新转换 → 下载

```

## 二、功能特性

| 特性 | 说明 |

| --- | --- |

| 多种图片输入方式 | 支持点击选择文件、**Ctrl+V 直接粘贴截图**、拖拽图片到工具区域 |

| 自动转换 | 选图后无需任何操作，自动调用压缩接口生成 WebP |

| 双栏对比预览 | 左侧原图、右侧 WebP 压缩图，并排直观对比效果 |

| 质量可调 | 质量参数 1~100（默认 90），可反复调整并"重新转换" |

| 压缩率一目了然 | 实时显示压缩后大小及"占原图的百分比" |

| 结果信息完整 | 展示输出格式、quality 参数、MD5 校验值 |

| 透明通道友好 | 预览区以棋盘格衬托透明像素，透明区域不会被误渲染成黑色 |

| GIF 动图支持 | 动图不生成缩略图，保留动画效果预览 |

| 一键下载 | 下载文件自动沿用原文件名，仅更换扩展名 |

| 即用免装 | 纯网页工具，无需注册、无需安装任何软件 |

## 三、使用指南

### 1. 导入图片（三种方式任选）

- **点击选择**：点击「Choose File」按钮，从本地选择一张图片；

- **粘贴截图**：直接按 `Ctrl + V`，剪贴板中的截图会自动进入转换流程（适合 QQ / 微信截图后快速压缩）；

- **拖拽导入**：将图片文件拖到工具卡片区域内，拖入时区域会出现虚线高亮提示。

### 2. 查看对比结果

选图后页面自动分为左右两栏：

- **左栏 · 原图**：本地预览，显示原始大小与格式；

- **右栏 · WebP 压缩图**：显示转换后的大小、压缩率（如"原图的 35%"）、quality 与 MD5。

### 3. 调整质量并重新转换

左栏顶部提供「质量」输入框（1~100，默认 90）：

- 数值越小 → 体积越小、画质越低；

- 数值越大 → 画质越好、体积越大；

- 修改后点击「**重新转换**」即可按新质量重新生成；

- 若输入超出范围的值（如 0、150），会自动重置为 90 并给出提示。

### 4. 下载

点击右栏「**下载 WebP**」按钮即可保存，文件名保持原文件名（如 `photo.jpg` → `photo.webp`）。

## 四、技术实现说明

本节面向开发者，介绍页面的核心实现思路（源码见 `webp.html` 内嵌脚本）。

### 1. 整体流程

1. 通过 `FileReader` 将本地文件读取为 Data URL（Base64）；

2. `fetch` POST 提交至后端压缩接口 `/api/uploadimg`，由**服务端完成 WebP 转码**（前端不做压缩计算）；

3. 解析响应中的 Base64 图片数据、大小、MD5，渲染双栏预览；

4. 下载时用 `a[download]` 触发浏览器保存。

### 2. 请求设计的两个细节

- **Content-Type 使用 `text/plain` 而非 `application/json`**：线上接口的 OPTIONS 预检返回 404，`application/json` 会触发 CORS 预检导致 `Failed to fetch`；`text/plain` 属于 CORS 安全类型，不触发预检，后端仍按 JSON 解析请求体。

- **接口地址自适应**：本地开发环境（`127.0.0.1` / `localhost`）直连线上接口 `https://xdoc.vip/api/uploadimg`；线上页面则走同源相对路径 `/api/uploadimg`。

### 3. 兼容性与容错

- **响应字段兼容**：同时兼容 `data.imgBase64 / base64 / img`、`result.*`、顶层字段等多种 JSON 结构，以及纯文本裸 Base64 响应；

- **状态码兼容**：`200 / 0 / "200" / "0"` 及缺失 code 但含图片数据的情况均视为成功；

- **Base64 规范化**：自动剥离 Data URL 头、将 URL-safe 字母表（`-_`）转回标准（`+/`）、补齐 `=` 填充；

- **格式探测**：按 Base64 头部特征识别输出 MIME（`/9j/`→JPEG、`iVBOR`→PNG、`R0lGOD`→GIF、`UklGR`→WebP、`PHN2Zy`→SVG），探测不到时默认 WebP。

### 4. 预览优化

- 预览缩略图最长边压至 320px（与下载文件、大小统计无关，仅用于展示）；

- 生成缩略图时逐像素检测透明通道：**含透明像素改用 PNG 编码**预览，避免 JPEG 把透明区域填成黑色；预览背景使用 CSS 渐变绘制棋盘格，直观呈现透明区域；

- GIF 动图跳过缩略图步骤，直接展示动画。

### 5. 交互反馈

- 处理中、失败、压缩完成均有右上角 toast 提示（成功绿 / 失败红 / 警告橙）；

- 压缩过程中「重新转换」按钮自动禁用，防止重复提交；

- 拖拽悬停时工具区域出现主题色虚线描边，提升可感知性。

## 五、适用场景

- **博客 / 网站作者**：发文前批量压缩配图，加快页面加载；

- **日常截图分享**：截图后 `Ctrl+V` 一贴即得小体积 WebP；

- **前端 / 设计协作**：快速评估不同质量参数下的体积与画质权衡；

- **隐私敏感用户**：无需把图片交给来路不明的第三方工具，接口仅做格式转码并返回结果。

## 六、常见问题

**Q1：支持哪些输入格式？**

文件选择框接受 `image/*`，常见 JPG、PNG、GIF、BMP 等均可，最终统一转码为 WebP。

**Q2：图片会上传到服务器吗？**

转换由站点后端接口 `/api/uploadimg` 完成处理并返回结果，属于必要的在线转码流程；页面本身不落地存储图片，也不提供任何图床/外链功能。

**Q3：质量设多少合适？**

一般 80~90 是体积与画质的平衡点；截图、UI 图等对画质敏感的图片建议 90 以上；纯展示配图可降到 70~80 进一步减小体积。

**Q4：转换失败怎么办？**

右栏会显示具体错误信息（如 HTTP 状态、接口返回的 msg）。多为网络波动或接口暂时不可用，稍后点击「重新转换」重试即可。