如何使用TypeScript正确处理AWS S3中的NoSuchKey等错误码

核心逻辑说明 #

• AWS SDK v3 不会为每个S3错误码单独导出专属类型（比如你要找的NoSuchKeyError），所有S3服务端返回的错误都继承自统一导出的S3ServiceException基类，通过name字段标识具体错误码，这是SDK的正常设计。
• TypeScript 4.0+ 中catch块捕获的错误默认类型为unknown，直接标any、用as强转类型都不是安全写法，需要通过运行时检查完成类型收窄，同时获得完整的类型提示。

完整实现代码 #

先从SDK导入需要的类和类型：

import { S3Client, GetObjectCommand, GetObjectCommandOutput, S3ServiceException } from "@aws-sdk/client-s3";

业务代码：

const client = new S3Client({ /* 你的S3客户端配置 */ });
const command = new GetObjectCommand({ Bucket: "你的桶名", Key: "你的对象键" });

let response: GetObjectCommandOutput;
try {
  response = await client.send(command);
} catch (error) {
  // 运行时校验错误类型，TS会自动完成类型收窄
  if (error instanceof S3ServiceException) {
    // 此处可直接访问错误的name、message、$metadata、httpStatusCode等属性，有完整类型提示
    if (error.name === "NoSuchKey") {
      // NoSuchKey场景的业务处理逻辑
      console.log("指定对象不存在，请求ID：", error.$metadata.requestId);
      return;
    }
    // 其余S3服务错误按需处理，不需要则直接抛出
    throw error;
  }
  // 非S3服务错误（如网络中断、本地参数校验失败等）按需处理后抛出
  throw error;
}

实践注意点 #

• 错误码判断优先用error.name，不要用error.code：3.x版本SDK中name是错误实例初始化时写入的固定字段，值与S3返回的错误码完全一致，IDE还会自动补全所有合法的S3错误码，避免拼写错误；code是兼容v2版本的冗余字段，部分场景可能缺失。
• 禁止用as关键字强制转换错误类型：通过instanceof做运行时校验的同时，TS会自动完成类型推导，既符合类型系统要求，也能避免错误类型不符合预期时的运行时报错。
• 多错误场景可以直接在S3ServiceException分支内用switch匹配error.name，分别处理不同错误，示例代码如下：

if (error instanceof S3ServiceException) {
  switch (error.name) {
    case "NoSuchKey":
      // 处理对象不存在
      break;
    case "AccessDenied":
      // 处理权限不足
      break;
    case "SlowDown":
      // 处理请求限流
      break;
    default:
      throw error;
  }
}

内容的提问来源于stack exchange，提问作者hikarunoryoma