> For the complete documentation index, see [llms.txt](https://summerain-1.gitbook.io/summerain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://summerain-1.gitbook.io/summerain/zh-cn/fa-bu-shuo-ming/v2.0.1.md).

# V2.0.1

> 开发预发布版本。此版本从 `dev` 分支发布，后续修改可能较为频繁， 并且不会被默认的 `latest` 镜像选中。

## 概述

v2.0.1 让 V2 浏览器图片处理流水线在执行高开销的图片解码或创建上传会话之前， 以安全失败方式提前终止。处理器选择现在会实际探测 wasm-vips 和 WebP 编码器， 而不再仅依赖浏览器功能判断；同时，每次上传都会在图片处理开始前， 根据完整的服务器配方进行检查。

此版本不包含数据库迁移，也没有修改服务器上传协议。

## 变更

### 浏览器能力协商

* 新增共享且有时间限制的 wasm-vips Worker 探测，会初始化 WASM 运行时、 HEIF/AVIF 动态库以及 WebP 编码器。
* 首张图片会复用探测成功的 Worker，避免再次支付初始化开销。
* 仅当解码后的尺寸位于设备特定的 Canvas 安全预算范围内时， 才使用原生 pica/Canvas。
* wasm-vips 不可用时，会在上传前拒绝大图片。客户端绝不会把原图发送到后端， 作为隐式降级方案。
* 低内存设备不会进入 WASM 路径；对于没有 `navigator.deviceMemory` 的浏览器， 仍允许其通过真实 Worker 探测来证明支持能力。

### 图片预检

* 新增统一的预检计划，用于验证真实容器格式、扩展名与 MIME 是否一致、 是否为动图、图片尺寸、50 MP 源图片上限、协商后的服务器像素上限， 以及 WebP 单边 16,383 像素限制。
* 处理过程中会复用已检查的元数据，因此不会重复解析源文件容器。
* 继续支持静态 JPEG、JPG、PNG、BMP、WebP 和 AVIF 输入。
* V2 仍不支持 APNG、动态 WebP、动态 AVIF 及其他动图输入。

### 配方契约

* 为数值限制和四种必需变体增加严格的 Zod 验证： `master`、`gallery`、`admin` 和 `publish_source`。
* 如果尺寸、质量、适配模式、流水线版本或配方版本发生变化， 会在处理前返回稳定的客户端错误。
* API 请求使用 no-store，并在配方查询失败后使其失效， 而不是继续保留已拒绝的缓存条目。

### 上传反馈

* 为无效文件、不支持的格式、动图、尺寸限制、处理器可用性、 解码或编码失败、超时以及不支持的配方新增稳定的 `ClientImageError` 错误码。
* 新增可见的 `checking` 阶段，以及英语、简体中文和日语的行级本地化错误信息。
* 无效文件现在会作为明确的已拒绝队列项保留，不再静默消失。
* 不可重试的能力或输入错误不再显示具有误导性的重试操作， 批量选择时也不会产生大量 Toast 提示。

## 兼容性与资源行为

* 不超过协商后 50 MP 上限的图片，仅在 Worker 和 WebP 编码器通过真实探测后， 才会使用 wasm-vips。
* Canvas 降级路径仍受计算得出的 8-16 MP 安全预算限制， 具体取决于设备报告的内存大小。
* 图片处理仍然串行执行；每个 Worker 都会在请求完成后终止， 因此解码后的像素和 WASM 内存不会在队列中持续累积。
* 服务器仍只接收配方 `2.0.0` 定义的固定 WebP 衍生图片。

## 验证

* 前端 Vitest：15 个测试文件，共 110 项测试通过。
* ESLint：通过。
* TypeScript 项目构建：通过。
* Vite 生产构建：通过。
* 现有 wasm-vips 直接 eval 警告保持不变，不会导致构建失败。

## 安装

开发镜像必须显式拉取：

```bash
docker pull jaykserks/summerain:dev-v2.0.1
```

等效的精确开发标签：

```
jaykserks/summerain:dev-2.0.1
```

滚动更新的 `dev` 标签也会指向最新一次成功的开发构建。 此版本不会修改 `latest`、`main` 以及稳定的语义化版本别名。

## 已知限制

* 浏览器上传队列尚未持久化。刷新或关闭页面，或离开上传页面， 都会中断当前队列。
* 无法初始化 wasm-vips 的设备不能上传超过其 Canvas 安全预算的图片。
* 动图支持仍计划在后续版本中提供。
* 针对受支持 Chrome 和 iOS 浏览器矩阵的真实设备验收属于部署验证步骤， 不包含在 jsdom 单元测试中。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://summerain-1.gitbook.io/summerain/zh-cn/fa-bu-shuo-ming/v2.0.1.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.