S3文件上传处理器Skill s3-upload-handler

---

name: s3-上传处理器 description: 处理S3文件上传，包括UI组件、客户端逻辑和服务器端处理 tools: 读取, 写入, 编辑 model: 继承

S3 上传处理器技能

此技能提供使用预构建UI组件、自定义客户端逻辑或服务器端处理将文件上传到AWS S3的方法。

功能

1. UI组件：开箱即用的 S3Uploader，支持拖放或按钮上传。
2. 客户端SDK：ClientS3Uploader 类，用于自定义上传界面。
3. 服务器工具：uploadFromServer，用于后端文件处理和上传。

使用模式

1. 标准UI组件（推荐）

对于大多数面向用户的上传需求，使用 S3Uploader 组件。

import { S3Uploader } from "@/components/ui/s3-uploader/s3-uploader";

// 在表单或页面中使用
<S3Uploader
  presignedRouteProvider="/api/app/your-upload-route" // 用于获取签名URL的API路由
  variant="dropzone" // 或 "button"
  maxFiles={5}
  accept="image/*" // 或特定扩展名，如 ".pdf,.doc"
  onUpload={async (fileUrls) => {
    console.log("文件已上传:", fileUrls);
    // 处理成功（例如，更新表单状态）
  }}
/>

2. 自定义客户端上传

当您需要完全控制UI时（例如，隐藏输入、自定义按钮），使用 ClientS3Uploader。

import { ClientS3Uploader } from "@/lib/s3/clientS3Uploader";

// 初始化
const uploader = new ClientS3Uploader({
  presignedRouteProvider: "/api/app/your-upload-route"
});

// 上传文件
const url = await uploader.uploadFile(fileObject);

3. 服务器端上传

在API路由或服务器操作中使用 uploadFromServer，以便在存储前处理文件（调整大小、生成PDF等）。

import uploadFromServer from "@/lib/s3/uploadFromServer";

// 在服务器上下文中（API路由/操作）
const url = await uploadFromServer({
  file: base64String, // 文件内容为base64格式
  path: "uploads/users/avatar.jpg", // 存储桶中的目标路径
  contentType: "image/jpeg" // MIME类型
});

环境配置

确保 .env.local 中包含必要的AWS凭据：

AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"
AWS_REGION="us-east-1"
AWS_S3_BUCKET_NAME="your-bucket-name"

API路由示例（用于预签名URL）

通常需要一个API路由来为客户端上传器生成预签名URL。

// src/app/api/app/upload-input-images/route.ts
import { createPresignedPost } from "@aws-sdk/s3-presigned-post";
import { S3Client } from "@aws-sdk/client-s3";
import { v4 as uuidv4 } from "uuid";

export async function POST(request: Request) {
  const { fileName, fileType } = await request.json();
  const client = new S3Client({ region: process.env.AWS_REGION });

  const { url, fields } = await createPresignedPost(client, {
    Bucket: process.env.AWS_S3_BUCKET_NAME!,
    Key: `uploads/${uuidv4()}-${fileName}`,
    Conditions: [
      ["content-length-range", 0, 10485760], // 最大10 MB
      ["starts-with", "$Content-Type", fileType],
    ],
    Fields: {
      acl: "public-read",
      "Content-Type": fileType,
    },
    Expires: 600, // 预签名POST过期前的秒数。默认为3600。
  });

  return Response.json({ url, fields });
}

更多详细信息请参阅 reference.md。