3.1 前端：只转换 JPG/PNG#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 beforeUpload(file) 方法。
实际修改文件：scripts/patch-webp-upload.mjs，部署时修改对应的 frontend-dist/js/923.*.js bundle。

原上传逻辑只排除了 WebP、GIF 和 SVG，其他图片格式都会尝试转换：

1
const canConvertToWebp = this.convertToWebp
2
  && file.type.includes('image')
3
  && !file.type.includes('webp')
4
  && !file.type.includes('gif')
5
  && !file.type.includes('svg');
6
const canConvertToWebp = this.convertToWebp
7
  && ['image/jpeg', 'image/png'].includes(file.type);

这样 BMP、GIF、SVG、ICO 等格式不会进入该转换分支。

3.2 前端：把 WebP 质量从 92% 调整为 85%#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 convertImageToWebp(file) 方法。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，替换上传 bundle 中 Canvas toBlob 的 WebP 质量参数。

原来的 Canvas 编码参数为 0.92：

1
canvas.toBlob(blob => {
2
  // 将 Blob 包装为 File
3
}, 'image/webp', 0.92);
4
}, 'image/webp', 0.85);

转换成功后保留原来的宽高，只改变编码格式和文件名：

1
const originalName = file.name;
2
const lastDotIndex = originalName.lastIndexOf('.');
3
const newName = lastDotIndex > 0
4
  ? `${originalName.substring(0, lastDotIndex)}.webp`
5
  : `${originalName}.webp`;
6

7
const webpFile = new File([blob], newName, {
8
  type: 'image/webp',
9
});
10
webpFile.uid = file.uid;

3.3 前端：强制初始化 WebP 开关#

源码语义位置：前端 src/views/UploadHome.vue 的 mounted() 初始化逻辑。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，替换上传页面 bundle 中 this.convertToWebp 的初始化表达式。

原项目会优先读取 Vuex 持久化设置。旧浏览器如果曾保存过 convertToWebp=false，即使系统默认值改成 true，也仍然不会转换：

1
this.convertToWebp = this.compressConfig.convertToWebp
2
  ?? this.parseBoolean(this.userConfig?.defaultConvertToWebp, false);
3
this.convertToWebp = true;

这样页面每次初始化时都会启用 JPG/PNG 转 WebP。

3.4 前端：阻止 WebP 二次压缩#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 beforeUpload(file) 方法，在 needCustomCompress 判断处。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，修改 bundle 中 customerCompress 的条件表达式。

原项目在 WebP 转换之后，还会执行 imageConversion.compressAccurately：

1
const needCustomCompress = processedFile.type.includes('image')
2
  && this.customerCompress
3
  && processedFile.size / 1024 / 1024 > this.compressBar;

但当前 image-conversion 版本只正确支持 PNG、JPEG 和 GIF 输出。把 WebP 再交给它，可能重新编码成 JPEG/PNG，或者造成文件名与 MIME 不一致。

修改为：本次进入 WebP 转换分支时，不再执行旧客户端压缩。

1
const needCustomCompress = processedFile.type.includes('image')
2
const needCustomCompress = !canConvertToWebp
3
  && processedFile.type.includes('image')
4
  && this.customerCompress
5
  && processedFile.size / 1024 / 1024 > this.compressBar;

85% WebP 编码本身已经完成压缩，不需要再编码一次。

3.5 前端：WebP 关闭 Telegram 服务端压缩#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 beforeUpload(file) 方法，在 pushFileToQueue() 写入 fileList 时。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，修改 bundle 中 serverCompress 字段。

上传队列原本直接保存计算出的 serverCompress：

1
this.fileList.push({
2
  uid: file.uid,
3
  name: file.name,
4
  serverCompress,
5
  serverCompress: canConvertToWebp ? false : serverCompress,
6
  retryCount: 0,
7
});

最终 WebP 请求会变成：

1
POST /upload?serverCompress=false&uploadChannel=telegram&...

如果 Network 中仍看到 serverCompress=true，说明当前页面没有执行到新 WebP 分支，通常是自定义域仍访问旧 Worker。

3.6 实际落地：部署前修改编译 bundle#

新增文件：scripts/patch-webp-upload.mjs。
读取目录：frontend-dist/js。
运行时修改：当前版本的上传 chunk frontend-dist/js/923.*.js 及对应 .js.gz；上游更新后 chunk 哈希可能变化，因此脚本通过内容锚点查找，不依赖固定文件名。

由于当前仓库只有编译后的前端，本方案新增一个 Node.js 补丁脚本。脚本在 frontend-dist/js 中寻找上传 bundle，并修改以下锚点：

1
const ORIGINAL_CONDITION = /this\.convertToWebp&&([A-Za-z_$][\w$]*)\.type\.includes\("image"\)&&!\1\.type\.includes\("webp"\)&&!\1\.type\.includes\("gif"\)&&!\1\.type\.includes\("svg"\)/g;
2

3
const PATCHED_CONDITION = /this\.convertToWebp&&\["image\/jpeg","image\/png"\]\.includes\(([A-Za-z_$][\w$]*)\.type\)/g;
4

5
const ORIGINAL_QUALITY = /"image\/webp",\.92/g;
6
const PATCHED_QUALITY = /"image\/webp",\.85/g;
7

8
const ORIGINAL_CLIENT_COMPRESSION = /const i=a\.type\.includes\("image"\)&&this\.customerCompress&&a\.size\/1024\/1024>this\.compressBar/g;
9
const PATCHED_CLIENT_COMPRESSION = /const i=!s&&a\.type\.includes\("image"\)&&this\.customerCompress&&a\.size\/1024\/1024>this\.compressBar/g;
10

11
const ORIGINAL_SERVER_COMPRESSION = /serverCompress:o,retryCount:0/g;
12
const PATCHED_SERVER_COMPRESSION = /serverCompress:o&&!s,retryCount:0/g;

核心替换代码如下：

1
if (originalConditionCount === 1) {
2
  patched = patched.replace(
3
    ORIGINAL_CONDITION,
4
    (original, fileVariable) => {
5
      const replacement =
6
        `this.convertToWebp&&["image/jpeg","image/png"].includes(${fileVariable}.type)`;
7

8
      // 保持长度，尽量避免破坏原 source map 的后续列位置。
9
      return replacement.padEnd(original.length, ' ');
10
    },
11
  );
12
}
13

14
if (originalQualityCount === 1) {
15
  patched = patched.replace(
16
    ORIGINAL_QUALITY,
17
    '"image/webp",.85',
18
  );
19
}
20

21
if (originalClientCompressionCount === 1) {
22
  patched = patched.replace(
23
    ORIGINAL_CLIENT_COMPRESSION,
24
    'const i=!s&&a.type.includes("image")&&this.customerCompress&&a.size/1024/1024>this.compressBar',
25
  );
26
}
27

28
if (originalServerCompressionCount === 1) {
29
  patched = patched.replace(
30
    ORIGINAL_SERVER_COMPRESSION,
31
    'serverCompress:o&&!s,retryCount:0',
32
  );
33
}

补丁写入 JavaScript 后，同步重新生成 .gz：

1
writeFileSync(candidate.jsPath, candidate.content);
2
writeFileSync(
3
  `${candidate.jsPath}.gz`,
4
  gzipSync(Buffer.from(candidate.content)),
5
);

脚本还会验证每个原始或已修改锚点只出现一次。如果匹配不到，直接抛出错误：

1
throw new Error(
2
  'No compatible WebP upload bundle was found; the upstream frontend may have changed.',
3
);

这可以避免上游更新前端后，GitHub Actions 看似部署成功，但 WebP 功能已经静默失效。

3.7 增加 npm 命令#

修改文件：package.json。
修改位置：顶层 scripts 对象。

在 package.json 的 scripts 中增加：

1
{
2
  "scripts": {
3
    "patch:webp": "node scripts/patch-webp-upload.mjs frontend-dist"
4
  }
5
}

本地可以执行：

1
npm run patch:webp

3.8 修改 GitHub Actions 顺序#

修改文件：.github/workflows/deploy-worker.yml。
新增位置：jobs.deploy.steps 中，位于 Install dependencies 和 Generate worker routes 之间。

在 Worker 部署工作流中，把 WebP 补丁放在 Wrangler 收集静态资源之前：

1
- name: Install dependencies
2
  if: steps.check.outputs.skip != 'true'
3
  run: npm ci --omit=dev --omit=optional
4

5
- name: Apply WebP upload customization
6
  if: steps.check.outputs.skip != 'true'
7
  run: npm run patch:webp
8

9
- name: Generate worker routes
10
  if: steps.check.outputs.skip != 'true'
11
  run: node deploy/worker/generate-routes.js
12

13
- name: Generate wrangler config
14
  if: steps.check.outputs.skip != 'true'
15
  run: node deploy/worker/generate-toml.js
16

17
- name: Deploy to Cloudflare Workers
18
  if: steps.check.outputs.skip != 'true'
19
  uses: cloudflare/wrangler-action@v3
20
  with:
21
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
22
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
23
    wranglerVersion: '4'
24
    command: deploy --config deploy/worker/wrangler.toml

最终顺序是：

1
安装依赖
2
→ 修改前端 bundle
3
→ 生成 Worker 路由
4
→ 生成 Wrangler 配置
5
→ 部署代码与静态资源

3.9 后端：删除 WebP 改名为 JPEG 的逻辑#

删除位置：functions/upload/index.js。
所属函数：uploadFileToTelegram(context, fullId, metadata, fileExt, fileName, fileType, returnLink)。

原 Telegram 上传代码为了规避 animation 行为，会把 WebP 文件名改成 .jpeg：

1
if (fileExt === 'gif') {
2
  const newFileName = fileName.replace(/\.gif$/, '.jpeg');
3
  const newFile = new File([formdata.get('file')], newFileName, {
4
    type: fileType,
5
  });
6
  formdata.set('file', newFile);
7
} else if (fileExt === 'webp') {
8
  const newFileName = fileName.replace(/\.webp$/, '.jpeg');
9
  const newFile = new File([formdata.get('file')], newFileName, {
10
    type: fileType,
11
  });
12
  formdata.set('file', newFile);
13
}

修改后只保留 GIF 兼容处理，WebP 文件名保持 photo.webp。

实际代码把文件名规则抽成函数：

1
export function getTelegramStoredFileName(fileName, fileExt) {
2
  if ((fileExt || '').toLowerCase() === 'gif') {
3
    return fileName.replace(/\.gif$/i, '.jpeg');
4
  }
5
  return fileName;
6
}

上传前应用该规则：

1
const telegramFileName = getTelegramStoredFileName(
2
  fileName,
3
  fileExt,
4
);
5

6
if (telegramFileName !== fileName) {
7
  const renamedFile = new File(
8
    [formdata.get('file')],
9
    telegramFileName,
10
    { type: fileType },
11
  );
12
  formdata.set('file', renamedFile);
13
}

对于 WebP，函数直接返回原文件名，因此不会发生重命名。

3.10 后端：WebP 改用 sendDocument#

删除位置：functions/upload/index.js 的 uploadFileToTelegram()，原 fileTypeMap 和 GIF/WebP 特殊接口判断区域。
新增文件：functions/upload/telegramUploadPolicy.js，新增 selectTelegramSendFunction()。
调用位置：functions/upload/index.js 的 uploadFileToTelegram()，在调用 telegramAPI.sendFile() 之前。

原策略把 WebP 发送为 animation：

1
if (
2
  fileType === 'image/gif'
3
  || fileType === 'image/webp'
4
  || fileExt === 'gif'
5
  || fileExt === 'webp'
6
) {
7
  sendFunction = {
8
    url: 'sendAnimation',
9
    type: 'animation',
10
  };
11
}

改造后的策略如下：

1
const DOCUMENT = {
2
  url: 'sendDocument',
3
  type: 'document',
4
};
5

6
export function selectTelegramSendFunction(
7
  fileType = '',
8
  fileExt = '',
9
  serverCompress = true,
10
) {
11
  const normalizedType = fileType.toLowerCase();
12
  const normalizedExt = fileExt.toLowerCase();
13

14
  // WebP 永远作为原始 document 保存。
15
  if (
16
    !serverCompress
17
    || normalizedType === 'image/webp'
18
    || normalizedExt === 'webp'
19
  ) {
20
    return { ...DOCUMENT };
21
  }
22

23
  if (
24
    normalizedType === 'image/gif'
25
    || normalizedExt === 'gif'
26
  ) {
27
    return {
28
      url: 'sendAnimation',
29
      type: 'animation',
30
    };
31
  }
32

33
  if (normalizedType.startsWith('image/')) {
34
    return {
35
      url: 'sendPhoto',
36
      type: 'photo',
37
    };
38
  }
39

40
  return { ...DOCUMENT };
41
}

Worker 上传区域调用：

1
const serverCompress =
2
  url.searchParams.get('serverCompress') !== 'false';
3

4
const sendFunction = selectTelegramSendFunction(
5
  fileType,
6
  fileExt,
7
  serverCompress,
8
);
9

10
const response = await telegramAPI.sendFile(
11
  formdata.get('file'),
12
  tgChatId,
13
  sendFunction.url,
14
  sendFunction.type,
15
);

3.11 Telegram API：关闭内容类型自动识别#

修改文件：functions/utils/storage/telegramAPI.js。
所属方法：TelegramAPI.sendFile(file, chatId, functionName, functionType, caption, fileName)。
新增位置：构造完 FormData、调用 fetch() 之前。

构造 Telegram multipart 请求时，为 sendDocument 增加：

1
if (functionName === 'sendDocument') {
2
  formData.append(
3
    'disable_content_type_detection',
4
    'true',
5
  );
6
}

完整关键部分：

1
const formData = new FormData();
2
formData.append('chat_id', chatId);
3
formData.append(functionType, file);
4

5
if (caption) {
6
  formData.append('caption', caption);
7
}
8

9
if (functionName === 'sendDocument') {
10
  formData.append(
11
    'disable_content_type_detection',
12
    'true',
13
  );
14
}
15

16
const response = await fetch(
17
  `${this.baseURL}/${functionName}`,
18
  {
19
    method: 'POST',
20
    headers: this.defaultHeaders,
21
    body: formData,
22
  },
23
);

这保证 Telegram 收到：

1
字段名：document
2
文件名：photo.webp
3
MIME：image/webp
4
disable_content_type_detection：true

3.12 Telegram API：返回真实错误#

修改文件一：functions/utils/storage/telegramAPI.js 的 TelegramAPI.sendFile()，删除只使用 response.statusText 的错误处理，改为解析 JSON description。
修改文件二：functions/upload/index.js 的 uploadFileToTelegram() catch 分支，删除固定通用错误，改为调用格式化函数。
新增位置：functions/upload/telegramUploadPolicy.js 中增加 formatTelegramUploadError()。

原代码只使用 HTTP statusText：

1
if (!response.ok) {
2
  throw new Error(
3
    `Telegram API error: ${response.statusText}`,
4
  );
5
}

修改后先解析 JSON，再读取 Bot API 的 description：

1
let responseData = null;
2

3
try {
4
  responseData = await response.json();
5
} catch (error) {
6
  if (response.ok) {
7
    throw new Error(
8
      `Telegram API returned invalid JSON: ${error.message}`,
9
    );
10
  }
11
}
12

13
if (!response.ok || responseData?.ok === false) {
14
  const description = responseData?.description
15
    || response.statusText
16
    || `HTTP ${response.status}`;
17

18
  throw new Error(
19
    `Telegram API error: ${description}`,
20
  );
21
}

上传入口不再把异常替换成固定字符串，而是保留真实错误：

1
} catch (error) {
2
  res = createResponse(
3
    'upload error, check your environment params about telegram channel!',
4
    { status: 400 },
5
  );
6
  res = createResponse(
7
    `upload error: ${error.message}`,
8
    { status: 502 },
9
  );
10
}

3.13 Worker 静态资源：启用 Worker-first#

修改文件一：deploy/worker/wrangler.toml 的 [assets] 段。
修改文件二：deploy/worker/generate-toml.js 中生成 [assets] 的模板字符串。
必须同时修改两处，因为 GitHub Actions 部署时会重新生成 wrangler.toml。

在 Wrangler 的 [assets] 中增加：

1
[assets]
2
directory = "../../frontend-dist"
3
binding = "ASSETS"
4
not_found_handling = "single-page-application"
5
run_worker_first = true

因为 GitHub Actions 会动态生成 wrangler.toml，不仅要改本地 TOML，还要在生成脚本模板中加入同一行：

1
let toml = `
2
[assets]
3
directory = "../../frontend-dist"
4
binding = "ASSETS"
5
not_found_handling = "single-page-application"
6
run_worker_first = true
7
`;

3.14 Worker 静态资源：HTML 不缓存#

修改源文件：deploy/worker/generate-routes.js 的 Worker 输出模板。
新增函数：fetchWorkerAsset(request, env)。
替换位置：生成模板中 if (!matched) 的 env.ASSETS.fetch(request) 回退。
生成文件：运行脚本后同步更新 deploy/worker/index.js；该文件是生成结果，不应只手工修改它。

在 Worker 的静态资源回退处新增：

1
async function fetchWorkerAsset(request, env) {
2
  const response = await env.ASSETS.fetch(request);
3
  const contentType =
4
    response.headers.get('Content-Type') || '';
5

6
  // JS/CSS/图片等带哈希资源继续正常缓存。
7
  if (!contentType.toLowerCase().includes('text/html')) {
8
    return response;
9
  }
10

11
  const headers = new Headers(response.headers);
12
  headers.set(
13
    'Cache-Control',
14
    'no-store, no-cache, must-revalidate',
15
  );
16
  headers.set('CDN-Cache-Control', 'no-store');
17
  headers.set(
18
    'Cloudflare-CDN-Cache-Control',
19
    'no-store',
20
  );
21
  headers.set(
22
    'X-ImgBed-Asset-Policy',
23
    'worker-first-no-store',
24
  );
25
  headers.delete('ETag');
26

27
  return new Response(response.body, {
28
    status: response.status,
29
    statusText: response.statusText,
30
    headers,
31
  });
32
}

原来的资产回退：

1
if (!matched) {
2
  if (env.ASSETS) {
3
    return env.ASSETS.fetch(request);
4
    return fetchWorkerAsset(request, env);
5
  }
6
  return new Response('Not Found', {
7
    status: 404,
8
  });
9
}

这样 HTML 每次从当前部署的 ASSETS binding 获取，而带哈希的静态资源仍保留缓存性能。

3.15 Cloudflare 控制台：删除旧 Workers Route#

非仓库文件修改：Cloudflare Dashboard → 域名 → Workers 路由。
删除对象：仍指向旧 Worker 的 tu.example.com/* Route。
不要删除旧 Worker 服务本身，只删除它对当前图床域名的路由占用。

代码部署成功后，还必须检查 Cloudflare 的“Workers 路由”。如果存在：

1
tu.example.com/* → old-image-worker

即使新 Worker 已配置 Custom Domain，该旧 Route 仍可能接管请求。删除旧 Route，只保留：

1
tu.example.com → cloudflare-imgbed

这是本次实际排查中导致自定义域一直加载旧前端的根因。它不是代码 Bug，而是旧路由仍指向旧 Worker。

3.16 对应的回归测试#

新增或修改的测试文件：

• test/webp-upload-patcher.test.js：前端 bundle 补丁、85% 质量、二次压缩和 serverCompress。
• test/telegram-upload-policy.test.js：WebP 文件名和 Telegram 发送策略。
• test/telegram-api.test.js：sendDocument 参数及真实错误描述。
• test/worker-asset-cache.test.js：Worker-first 和 HTML no-store。

至少应覆盖以下断言：

1
assert.ok(
2
  patched.includes(
3
    '["image/jpeg","image/png"].includes(',
4
  ),
5
);
6
assert.ok(patched.includes('"image/webp",.85'));
7
assert.ok(
8
  patched.includes(
9
    'serverCompress:o&&!s,retryCount:0',
10
  ),
11
);

Telegram 策略测试：

1
assert.equal(
2
  getTelegramStoredFileName('photo.webp', 'webp'),
3
  'photo.webp',
4
);
5

6
assert.deepEqual(
7
  selectTelegramSendFunction(
8
    'image/webp',
9
    'webp',
10
    true,
11
  ),
12
  {
13
    url: 'sendDocument',
14
    type: 'document',
15
  },
16
);

Worker 静态资源测试：

1
assert.match(
2
  wranglerConfig,
3
  /run_worker_first\s*=\s*true/,
4
);
5

6
assert.match(
7
  generatedWorker,
8
  /worker-first-no-store/,
9
);

完整测试命令：

1
npm test

3.17 增删改文件汇总#

4.1 为什么必须跳过二次客户端压缩#

项目原有的 image-conversion 版本只正确支持 PNG、JPEG 和 GIF 输出，不支持 WebP 输出。如果先转换 WebP，再把 WebP 交给该库，可能发生：

• 再次解码和编码，导致上传前处理明显变慢；
• 输出变回 JPEG/PNG；
• 文件扩展名和真实二进制 MIME 不一致。

因此 WebP 转换成功后必须绕过旧客户端压缩逻辑。85% WebP 编码本身已经完成了有损压缩，不需要再压缩一次。

5.1 使用 sendDocument#

Telegram Bot API 对图片提供 sendPhoto、sendAnimation 和 sendDocument 等接口。要保留 WebP 原始内容，必须使用：

1
sendDocument

不能使用 sendPhoto，否则 Telegram 可能重新压缩图片；也不应把静态 WebP 当作 animation。

5.2 保留文件名和 MIME#

上传到 Telegram 的 multipart 字段应保持：

1
filename="photo.webp"
2
Content-Type: image/webp

同时为 sendDocument 添加：

1
disable_content_type_detection=true

这可以避免 Telegram 根据文件内容自动改变 document 类型。

5.3 Telegram 错误透传#

Telegram API 失败时，后端会读取响应 JSON 中的 description。前端最终可以看到类似：

1
upload error: Telegram API error: Bad Request: ...

而不是没有诊断价值的通用错误：

1
upload error, check your environment params about telegram channel!

6.1 必需的 GitHub Secrets#

进入：

1
GitHub 仓库
2
→ Settings
3
→ Secrets and variables
4
→ Actions

至少配置：

可选：

不要把 Bot Token、API Token 或其他密钥直接写进仓库文件。

6.2 手动部署#

GitHub 仓库的 Actions 页面选择：

1
Deploy to Cloudflare Workers
2
→ Run workflow
3
→ Branch: main

如需覆盖 Worker 名称，可在 worker_name 中填写实际服务名称。

7.1 删除旧 CNAME#

如果添加域名时报错：

1
Hostname already has externally managed DNS records

说明该子域名已经存在 A 或 CNAME。例如：

1
tu.example.com CNAME example.com

需要先删除这条旧记录，再通过 Worker 的“添加域名”功能创建 Custom Domain。删除子域名记录不会删除根域名网站。

7.2 必须检查旧 Workers Route#

Custom Domain 配置正确后，还要检查：

1
Cloudflare → 域名 → Workers 路由

旧部署可能存在：

1
tu.example.com/* → old-image-worker

该 Route 会抢先接管请求，使 Custom Domain 虽然显示绑定新 Worker，实际仍访问旧 Worker。推荐删除旧路由，只保留：

1
tu.example.com → cloudflare-imgbed Custom Domain

本项目排查时的实际根因就是一条旧路由仍指向旧图床 Worker。

10.1 先验证 workers.dev#

先访问 Worker 原始地址：

1
https://cloudflare-imgbed.<account-subdomain>.workers.dev

开发者工具 Network 中，HTML Document 响应应包含：

1
X-ImgBed-Asset-Policy: worker-first-no-store

10.2 再验证自定义域名#

访问：

1
https://tu.example.com

它必须加载与 workers.dev 相同的前端资源。若两个域名加载的 app.*.js 哈希不同，通常不是浏览器缓存问题，而是：

• 旧 Workers Route 仍指向旧服务；
• 自定义域名绑定到了错误 Worker；
• DNS 仍是旧 CNAME；
• 请求被其他重定向、源站或配置规则接管。

10.3 验证上传请求#

上传新的 JPG/PNG，在 Network 中检查 /upload：

1
serverCompress=false
2
uploadChannel=telegram

如果仍是：

1
serverCompress=true

说明当前页面没有执行 WebP 转换。优先检查浏览器加载的上传 bundle 是否为新版本，以及自定义域是否仍指向旧 Worker。

10.4 验证最终文件#

确认以下项目：

• 返回 URL 以 .webp 结尾；
• 管理面板显示 image/webp；
• Telegram 消息类型为 Document；
• Telegram 文件名以 .webp 结尾；
• 下载后的文件可被 WebP 解码器正常识别。

Q1：为什么上传解析变慢，但文件还是 PNG？#

常见原因是 WebP 转换开关被浏览器持久化配置覆盖，或者转换后又进入旧客户端压缩库。本方案强制初始化 WebP，并阻止转换后的文件二次压缩。

Q2：为什么请求一直是 serverCompress=true？#

说明该文件没有进入成功的 WebP 分支，或者页面仍是旧前端。检查：

1. 原文件 MIME 是否为 image/jpeg 或 image/png；
2. 自定义域和 workers.dev 是否加载同一版前端；
3. 是否存在旧 Workers Route；
4. 上传 bundle 中是否包含 85% WebP 补丁。

Q3：为什么 cf-cache-status 仍显示 HIT？#

带哈希的 JS、CSS 和图片命中 Workers Static Assets 缓存是正常现象。判断 HTML 是否经过新 Worker，应检查 Document 响应中的：

1
X-ImgBed-Asset-Policy: worker-first-no-store

不要只查看旧 app.<hash>.js 的响应头。

Q4：为什么 Telegram 上传失败后所有备用渠道也报错？#

项目开启自动重试后，会依次尝试配置的存储渠道。未配置 R2、S3、HuggingFace、WebDAV 或 Discord 时，这些备用渠道会各自报告“未配置”。应优先查看 TelegramNew 的第一条真实错误描述。

Q5：PicGo 或 API 上传也会自动转 WebP 吗？#

不会。本方案是浏览器前端转换。直接调用 /upload 的客户端必须在客户端自行转换，或另行实现服务端编码。

Q6：上游前端更新后怎么办？#

部署补丁会验证前端 bundle 的结构。如果上游修改导致锚点不匹配，GitHub Actions 会在 Apply WebP upload customization 阶段失败。此时应更新 scripts/patch-webp-upload.mjs 和对应测试，不要简单忽略失败继续部署。