接口实现流程#

1
import { z } from "zod";
2
import { router, checkedSessionProcedure } from "@/utils/trpc";
3
import dayjs from "dayjs";
4
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
5
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
6

7
// COS 配置
8
const REGION = "xx"; // COS 存储桶地域
9
const ENDPOINT = "xx"; // COS 服务端点
10
const COS_SECRET_ID = "xx"; // 访问密钥 ID
11
const COS_SECRET_KEY = "xx"; // 访问密钥 Secret
12
const BUCKET = "xx"; // 存储桶名称
13

14
/**
15
 * 文件上传路由
16
 * 提供文件上传相关的 API 接口
17
 */
18
export const fileRouter = router({
19
  /**
20
   * 创建预签名 URL
21
   * 用于客户端直传文件到云存储，避免通过服务器中转
22
   *
23
   * 工作流程：
24
   * 1. 客户端请求预签名 URL（包含文件名、类型、大小）
25
   * 2. 服务端生成带签名的临时上传 URL
26
   * 3. 客户端使用该 URL 直接上传文件到云存储
27
   *
28
   * @param filename - 原始文件名
29
   * @param contentType - 文件 MIME 类型
30
   * @param size - 文件大小（字节）
31
   * @returns 预签名 URL 和 HTTP 方法
32
   */
33
  createPresignedUrl: procedure
34
    .input(
35
      // 通过 zod 控制接口输入类型
36
      z.object({
37
        filename: z.string(),
38
        contentType: z.string(),
39
        size: z.number(),
40
      })
41
    )
42
    .mutation(async ({ input }) => {
43
      // 按日期创建文件夹结构，便于管理
44
      const dateString = dayjs().format("YYYY-MM-DD");
45

46
      // 创建 S3 客户端实例
47
      const s3Client = new S3Client({
48
        region: REGION,
49
        endpoint: ENDPOINT,
50
        credentials: {
51
          accessKeyId: COS_SECRET_ID,
52
          secretAccessKey: COS_SECRET_KEY,
53
        },
54
      });
55

56
      // 创建上传命令
57
      const command = new PutObjectCommand({
58
        Bucket: BUCKET, // 目标存储桶
59
        Key: `${dateString}/${input.filename}`, // 文件在云存储中的完整路径
60
        ContentType: input.contentType, // 设置正确的 MIME 类型
61
        ContentLength: input.size, // 设置文件大小
62
        // 可选：添加更多元数据
63
        // Metadata: {
64
        //   'original-name': input.filename,
65
        //   'upload-date': dateString,
66
        // }
67
      });
68

69
      // 生成预签名 URL
70
      const url = await getSignedUrl(s3Client, command, {
71
        expiresIn: 60, // URL 有效期（秒）
72
      });
73

74
      // 返回预签名 URL 给客户端
75
      return {
76
        url, // 客户端用于上传的完整 URL
77
        method: "PUT" as const, // HTTP 方法必须为 PUT
78
      };
79
    }),
80
});

getSignedUrl 作用#

核心作用#

getSignedUrl的作用是为一个原本需要权限才能访问的私有资源（如云存储中的文件），生成一个有时效性的、带签名的临时访问链接。

任何拥有这个链接的人，在链接有效期内，都可以直接访问该资源，而无需拥有云服务账户的正式身份认证凭证（如 Access Key、用户名密码等），以及无需经过的服务器中转 。

为什么需要它？#

假如我们开发了一个社交App，用户上传的图片都私密地存放在腾讯云OSS或AWS S3的Bucket里。

问题1（安全性）：我们不能直接把文件在存储桶里的永久URL（例如 https://my-bucket.s3.amazonaws.com/user-123/avatar.jpg）给客户端。因为这个URL指向的是私有文件，如果没有正确的身份认证信息，访问它会直接被拒绝（返回403错误）。
问题2（成本与性能）：我们也不能让客户端每次都通过应用服务器来下载文件。这会占用服务器的带宽和线程（服务器需要先从云存储下载文件，再提供到客户端），导致速度慢且成本高。

getSignedUrl 解决了这个问题

安全：文件本身是私有的，普通用户无法访问其他人的文件URL。
高效：生成的签名URL是临时的（例如，有效期为5分钟、1小时等）。一旦生成，客户端可以直接使用这个URL从云存储下载或上传文件，getSignedUrl，减轻了服务器负担，速度也更快。
灵活控制：我们可以精确控制这个临时链接的权限（读或写）和有效期。

简单来说， getSignedUrl 就是给客户端一个临时”通行证” ，让它能安全地直接把文件上传到云存储。几乎所有主流的云存储服务（AWS S3，Google Cloud Storage，Azure Blob Storage，阿里云 OSS，腾讯云 COS 等）都提供了这个核心功能。

前端上传流程#

1
"use client";
2
import Uppy from "@uppy/core";
3
import AwsS3 from "@uppy/aws-s3";
4
import { useState } from "react";
5
import { Input } from "@/components/ui/input";
6
import { useUppyState } from "@uppy/react";
7
import { trpcClient } from "@/utils/api";
8
import { Button } from "@/components/ui/button";
9

10
export default function Home() {
11
  // 创建 Uppy 实例配置
12
  const [uppy] = useState(() => {
13
    const uppy = new Uppy({
14
      // 调试模式：开发时可开启查看更多日志
15
      debug: true,
16
      // 限制配置（可选）
17
      restrictions: {
18
        maxFileSize: 10 * 1024 * 1024, // 10MB 限制
19
        allowedFileTypes: ['image/*', 'video/*', 'application/pdf'], // 允许的文件类型
20
      },
21
    });
22

23
    /**
24
     * 配置 AWS S3 插件
25
     * 用于直传文件到腾讯云 COS
26
     */
27
    uppy.use(AwsS3, {
28
       // 禁用分片上传，适合小文件
29
      shouldUseMultipart: false,
30
      // 获取上传参数 - 从服务端获取预签名 URL
31
      getUploadParameters(file) {
32
        if (file.data instanceof File) {
33
          // 调用 tRPC 服务端获取预签名 URL
34
          return trpcClient.fileRouter.createPresignedUrl.mutate({
35
            filename: file.name || "unkonw", // 文件名（带默认值）
36
            contentType: file.data.type || "", // 文件 MIME 类型
37
            size: file.data.size || 0, // 文件大小（字节）
38
          });
39
        } else {
40
          // 处理无效文件类型的情况
41
          return {
42
            url: "",
43
          };
44
        }
45
      },
46
    });
47
    return uppy;
48
  });
49

50
  // 获取当前选择的文件列表
51
  const files = useUppyState(uppy, (state) => Object.values(state.files));
52

53
  // 获取总上传进度
54
  const progress = useUppyState(uppy, (state) => state.totalProgress);
55

56
  return (
57
    <div className="h-screen flex items-center justify-center">
58
      {/* 文件选择表单 */}
59
      <form className="w-full max-w-md flex flex-col" action="">
60
        <Input
61
          type="file"
62
          multiple // 允许多文件选择
63
          onChange={(e) => {
64
            if (e.target.files) {
65
              // 遍历所有选择的文件并添加到 Uppy state
66
              Array.from(e.target.files).forEach((file) => {
67
                uppy.addFile({
68
                  name: file.name, // 文件名
69
                  data: file, // 文件数据（这里添加注释）
70
                });
71
              });
72
            }
73
          }}
74
        />
75
      </form>
76

77
      {/* 文件预览区域 */}
78
      <div className="w-full max-w-md flex flex-col">
79
        {files?.map((file) => {
80
          // 创建本地预览 URL
81
          const url = URL.createObjectURL(file.data);
82
          return <img key={file.id} src={url} alt={file.name} />;
83
        })}
84
      </div>
85

86
      {/* 手动上传按钮 */}
87
      <Button
88
        onClick={() => {
89
          // 手动触发上传
90
          uppy.upload();
91
        }}
92
      >
93
        upload
94
      </Button>
95

96
      {/* 进度显示 */}
97
      <div>{progress}</div>
98
    </div>
99
  );
100
}