Claude Code 图像处理实战指南：Sharp、Canvas、WebP/AVIF 与上传验证

图像处理看起来只是一个上传功能：用户选择照片，系统生成缩略图，页面加载更快。但在真实产品里，它同时牵涉上传验证、安全文件名、EXIF元数据清理、尺寸压缩、WebP/AVIF格式选择、后台任务、隐私和测试。如果只让Claude Code“帮我优化图片”，很容易得到一个能跑Demo、却不适合上线的实现。

这里的重点不是追求最炫的压缩率，而是把边界说清楚。浏览器可以做预览和轻量缩小，服务器必须重新验证，耗CPU的派生图应交给后台任务。官方资料建议一起核对：Claude Code文档、Sharp resize API、Sharp output API、MDN File API、Canvas toBlob以及OWASP文件上传清单。如果浏览器端处理变重，可以结合站内的Claude Code Web Worker指南。

先决定处理边界

不要一上来就问“用WebP还是AVIF”。先决定每一步在哪里发生。

位置	适合做的事	不适合做的事
浏览器	预览、轻量缩小、减少上传流量	可信验证、大量AVIF转换、隐私判断
同步服务器请求	MIME和magic bytes验证、尺寸读取、EXIF清理、小缩略图	多尺寸批量生成、重AVIF编码
后台任务	商品图套装、CMS重新生成、旧图片迁移	需要马上返回的上传响应

实务中常见的安全模式是：浏览器端先让体验变好，服务器端永远重新验证，昂贵转换放到队列里。accept="image/*"和file.type只能改善用户选择文件的体验，不是安全边界。服务端才有权决定这个文件能否进入系统。

flowchart LR
  Browser["Browser preview / optional resize"]
  Upload["Upload endpoint"]
  Validate["Magic bytes, size, dimensions"]
  Store["Private raw storage"]
  Job["Background variants"]
  Public["Public WebP/JPEG/AVIF"]
  Browser --> Upload
  Upload --> Validate
  Validate --> Store
  Store --> Job
  Job --> Public

给Claude Code的提示词要直接写这些规则：服务器检查MIME和magic bytes；公开URL不能使用原始文件名；先rotate()处理手机照片方向；不要调用.withMetadata()保留元数据；AVIF是可选项，不是默认同步任务。这样生成的代码会少很多危险的省略。

真实产品场景

第一个场景是电商或二手交易平台。卖家通常直接上传手机大图，系统需要方形缩略图、列表卡片图、详情页大图和社交分享图。这里不能盲目压缩，因为买家要看材质、颜色、标签和磨损。WebP通常是稳妥起点，AVIF应该在测过真实图片和编码时间后再加入。

第二个场景是头像和团队成员照片。这里最重要的是正方形裁剪、隐私和安全文件名。alice-client-contract-final.png这种名字绝不能变成公开路径。即使浏览器已经缩小过，服务器输出也应该清理EXIF元数据。

第三个场景是博客、帮助中心和课程截图。教程截图的文字必须读得清楚。为了省几十KB把按钮文字压糊，会直接损害读者信任，也会影响付费模板或咨询CTA。和文档生成一起使用时，也可以参考Claude Code PDF生成指南。

第四个场景是SaaS内部附件，比如发票、身份验证图片、客服截图或管理后台文档。这类文件不是公开素材，不能放进public/uploads。它们需要私有存储、权限检查、删除策略和审计日志。

安装

下面示例假设Node.js 20以上。你可以把这些模块接到Next.js、Express、Hono、Astro API Route或队列worker里。

npm i sharp file-type p-limit
npm i -D tsx typescript @types/node
mkdir -p src public/uploads

把图像相关测试放进脚本，方便CI执行。

{
  "scripts": {
    "test:images": "node --import tsx --test src/**/*.test.ts"
  }
}

上传验证和安全文件名

这个模块是服务端信任边界。它不相信扩展名，而是检查magic bytes；再用Sharp读取尺寸；拒绝过大的文件；在这个上传路径里拒绝动画或多页图片。

// src/image-policy.ts
import { randomUUID } from "node:crypto";
import { fileTypeFromBuffer } from "file-type";
import sharp from "sharp";

const MAX_BYTES = 6 * 1024 * 1024;
const MAX_PIXELS = 24_000_000;

const EXTENSION_BY_MIME = {
  "image/jpeg": ".jpg",
  "image/png": ".png",
  "image/webp": ".webp",
  "image/avif": ".avif",
} as const;

export type MimeType = keyof typeof EXTENSION_BY_MIME;

export type ImageUploadInfo = {
  mime: MimeType;
  extension: string;
  width: number;
  height: number;
  bytes: number;
  originalName: string;
};

function isAllowedMime(mime: string): mime is MimeType {
  return mime in EXTENSION_BY_MIME;
}

export async function assertImageUpload(
  buffer: Buffer,
  originalName = "upload",
): Promise<ImageUploadInfo> {
  if (buffer.byteLength === 0) {
    throw new Error("Empty file");
  }

  if (buffer.byteLength > MAX_BYTES) {
    throw new Error("Image must be 6 MB or smaller");
  }

  const detected = await fileTypeFromBuffer(buffer);

  if (!detected || !isAllowedMime(detected.mime)) {
    throw new Error("Unsupported image type");
  }

  const metadata = await sharp(buffer, { failOn: "error" }).metadata();

  if (!metadata.width || !metadata.height) {
    throw new Error("Image dimensions could not be read");
  }

  if (metadata.pages && metadata.pages > 1) {
    throw new Error("Animated images are not allowed here");
  }

  const pixels = metadata.width * metadata.height;

  if (pixels > MAX_PIXELS) {
    throw new Error("Image dimensions are too large");
  }

  return {
    mime: detected.mime,
    extension: EXTENSION_BY_MIME[detected.mime],
    width: metadata.width,
    height: metadata.height,
    bytes: buffer.byteLength,
    originalName,
  };
}

export function safeImageName(mime: MimeType): string {
  return `${randomUUID()}${EXTENSION_BY_MIME[mime]}`;
}

原始文件名可以作为后台显示字段保存在数据库里，但不要放进公开URL。随机文件名还能避免中文、韩文、空格和不同操作系统的Unicode规范化问题。

用Sharp生成WebP和AVIF

Sharp适合做Node.js服务器端图像处理。这里的关键点是：先用rotate()应用EXIF方向，再输出新文件；除非确实需要保留元数据，否则不要调用.withMetadata()。公开网页图片通常应该清理元数据。

// src/optimize-image.ts
import { mkdir } from "node:fs/promises";
import path from "node:path";
import sharp from "sharp";

type Variant = {
  kind: "thumb" | "card" | "hero";
  width: number;
  height?: number;
};

const VARIANTS: Variant[] = [
  { kind: "thumb", width: 320, height: 320 },
  { kind: "card", width: 640 },
  { kind: "hero", width: 1280 },
];

export type OptimizedImage = {
  src: string;
  width: number;
  height: number;
  bytes: number;
  format: "webp" | "avif";
};

export async function optimizeImage(
  buffer: Buffer,
  outputDir: string,
  baseName: string,
  makeAvif = false,
): Promise<OptimizedImage[]> {
  await mkdir(outputDir, { recursive: true });

  const results: OptimizedImage[] = [];

  for (const variant of VARIANTS) {
    const resized = sharp(buffer)
      .rotate()
      .resize({
        width: variant.width,
        height: variant.height,
        fit: variant.height ? "cover" : "inside",
        withoutEnlargement: true,
      });

    const webpName = `${baseName}-${variant.kind}.webp`;
    const webpInfo = await resized
      .clone()
      .webp({ quality: 78, effort: 4 })
      .toFile(path.join(outputDir, webpName));

    results.push({
      src: `/uploads/${webpName}`,
      width: webpInfo.width,
      height: webpInfo.height,
      bytes: webpInfo.size,
      format: "webp",
    });

    if (makeAvif) {
      const avifName = `${baseName}-${variant.kind}.avif`;
      const avifInfo = await resized
        .clone()
        .avif({ quality: 45, effort: 4 })
        .toFile(path.join(outputDir, avifName));

      results.push({
        src: `/uploads/${avifName}`,
        width: avifInfo.width,
        height: avifInfo.height,
        bytes: avifInfo.size,
        format: "avif",
      });
    }
  }

  return results;
}

AVIF不是所有场景的默认答案。它压缩率常常很好，但编码更慢，某些内部运营工具和旧的图片链路也可能不方便处理。先上线WebP，再对真实商品图和截图测AVIF收益，通常更稳。

Next.js上传API示例

下面是App Router的最小POST接口。生产环境如果处理私有图片，请换成对象存储和授权访问。

// app/api/images/route.ts
import path from "node:path";
import { NextResponse } from "next/server";
import { assertImageUpload, safeImageName } from "@/src/image-policy";
import { optimizeImage } from "@/src/optimize-image";

export async function POST(request: Request) {
  const form = await request.formData();
  const file = form.get("image");

  if (!(file instanceof File)) {
    return NextResponse.json(
      { error: "image field is required" },
      { status: 400 },
    );
  }

  const buffer = Buffer.from(await file.arrayBuffer());
  const upload = await assertImageUpload(buffer, file.name);
  const storedName = safeImageName(upload.mime);
  const baseName = storedName.replace(/\.[^.]+$/, "");

  const variants = await optimizeImage(
    buffer,
    path.join(process.cwd(), "public", "uploads"),
    baseName,
    false,
  );

  return NextResponse.json({
    original: {
      width: upload.width,
      height: upload.height,
      bytes: upload.bytes,
    },
    variants,
  });
}

这段代码适合公开媒体素材。发票、证件、支持工单附件等私有文件必须走不同的存储和访问控制。

浏览器端轻量缩小

浏览器端缩小可以减少上传流量，也能给用户更快的预览。但它只是体验优化，不是安全措施。

// src/resize-in-browser.ts
export async function resizeInBrowser(
  file: File,
  maxSide = 1600,
): Promise<File> {
  const bitmap = await createImageBitmap(file);
  const scale = Math.min(1, maxSide / Math.max(bitmap.width, bitmap.height));
  const width = Math.round(bitmap.width * scale);
  const height = Math.round(bitmap.height * scale);

  const canvas = document.createElement("canvas");
  canvas.width = width;
  canvas.height = height;

  const context = canvas.getContext("2d");

  if (!context) {
    throw new Error("Canvas 2D context is not available");
  }

  context.drawImage(bitmap, 0, 0, width, height);
  bitmap.close();

  const blob = await new Promise<Blob>((resolve, reject) => {
    canvas.toBlob(
      (result) => {
        if (result) resolve(result);
        else reject(new Error("Canvas export failed"));
      },
      "image/webp",
      0.82,
    );
  });

  const outputName = file.name.replace(/\.[^.]+$/, ".webp");

  return new File([blob], outputName, {
    type: blob.type || "image/webp",
    lastModified: Date.now(),
  });
}

Canvas重新编码通常会丢掉很多元数据，但隐私清理仍应由服务器输出保证。浏览器端直接导出AVIF也会有环境差异，不适合作为主流程。

后台任务和性能预算

同步上传接口应尽量短：验证、保存、生成必要缩略图即可。商品详情图、OGP图、AVIF版本、旧素材迁移都适合放到后台任务中。

可以先设一个预算：头像320x320控制在80KB以内，卡片图宽640控制在120KB以内，主视觉宽1280控制在250KB以内。数字要按产品调整，但没有预算时，Claude Code很容易选择看似高质量、实际拖慢页面的参数。

// src/batch-optimize.ts
import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import pLimit from "p-limit";
import { assertImageUpload, safeImageName } from "./image-policy";
import { optimizeImage } from "./optimize-image";

export async function batchOptimize(inputDir: string, outputDir: string) {
  const files = await readdir(inputDir);
  const limit = pLimit(3);

  const jobs = files.map((file) =>
    limit(async () => {
      const sourcePath = path.join(inputDir, file);
      const buffer = await readFile(sourcePath);
      const upload = await assertImageUpload(buffer, file);
      const baseName = safeImageName(upload.mime).replace(/\.[^.]+$/, "");
      const variants = await optimizeImage(buffer, outputDir, baseName, true);

      return {
        file,
        variants: variants.length,
      };
    }),
  );

  return Promise.allSettled(jobs);
}

如果使用真实队列，要记录job ID、源图片ID、variant类型、失败原因、重试次数和输出路径。否则迟早会出现“文件还在，数据库却不知道它是谁”的问题。

常见失败模式

最常见的失败是只看file.type。第二个失败是公开原始文件名。第三个失败是没有处理手机照片方向，导致图片横倒。第四个失败是复制了带.withMetadata()的片段，把EXIF继续带到公开图片里。第五个失败是在请求同步路径里给每张图生成AVIF，导致上传超时。

还有一种产品层面的失败：图像变小了，但转化路径变差了。课程截图如果看不清，读者不会相信后面的付费模板。商品图如果生成太慢，购买按钮出现了，用户却还没看清商品。需要一起看图片加载、CTA点击和购买路径时，可以参考Claude Code分析实现指南。

测试行为

测试不要只依赖手工上传的样例图。用Sharp在测试里生成图像，可以让CI稳定复现。

// src/image-policy.test.ts
import test from "node:test";
import assert from "node:assert/strict";
import { mkdtemp } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import sharp from "sharp";
import { assertImageUpload, safeImageName } from "./image-policy";
import { optimizeImage } from "./optimize-image";

test("validates and optimizes a generated image", async () => {
  const input = await sharp({
    create: {
      width: 1200,
      height: 800,
      channels: 3,
      background: "#38bdf8",
    },
  })
    .jpeg()
    .toBuffer();

  const info = await assertImageUpload(input, "masa-profile.jpg");
  assert.equal(info.mime, "image/jpeg");
  assert.equal(info.width, 1200);

  const safeName = safeImageName(info.mime);
  assert.match(safeName, /^[a-f0-9-]+\.jpg$/);

  const outDir = await mkdtemp(path.join(tmpdir(), "images-"));
  const baseName = safeName.replace(/\.[^.]+$/, "");
  const variants = await optimizeImage(input, outDir, baseName, false);

  assert.equal(variants.length, 3);
  assert.ok(variants.every((item) => item.bytes > 0));

  const thumb = await sharp(
    path.join(outDir, `${baseName}-thumb.webp`),
  ).metadata();

  assert.equal(thumb.width, 320);
  assert.equal(thumb.height, 320);
  assert.equal(thumb.exif, undefined);
});

手动检查还要覆盖移动端宽度、慢网络、损坏文件、巨大图片、竖拍手机照片、透明PNG和小字截图。最后可以让Claude Code只做一次图像处理审查，重点看验证、文件名、元数据、CPU、回退格式和测试缺口。

变现CTA与实测记录

图像处理不仅是速度优化。商品图加载快、教程截图清晰、头像不泄露隐私、OGP图片不崩，这些都会影响下一次点击。个人学习可以从免费Claude Code清单开始；需要可复用提示词和CLAUDE.md模板时看ClaudeCodeLab产品；团队要把上传规则、审核门禁和验证脚本放进真实仓库时，可以看培训与咨询。

2026年6月2日，Masa在一个小型Next.js验证项目中试了这套流程。效果最好的一次，是先告诉Claude Code：浏览器缩小只是辅助，服务器验证必须保留，AVIF可选，原始文件名不能公开。模糊地说“做一个图片上传”时，生成结果更容易出现file.type验证、公开原始文件名、忽略方向和同步AVIF转换。先给预算和失败例，才是提升图像处理质量的关键。