aws-sdk-js-v3-usage

此技能启用时，禁止在任何代码、注释或输出中使用表情符号。

AWS SDK for JavaScript v3

包结构

• @aws-sdk/client-* — 每个服务对应一个包，由 smithy-typescript 生成；与 AWS 服务和操作一一对应
• @aws-sdk/lib-* — 更高层级的辅助工具（例如 lib-dynamodb、lib-storage）
• @aws-sdk/*（无前缀）— 实用工具包（大多为内部使用；请勿导入深层路径）

始终从包根路径导入：

import { S3Client } from "@aws-sdk/client-s3"; // correct
// NOT: import { S3Client } from "@aws-sdk/client-s3/dist-cjs/S3Client"

两种客户端风格

精简风格（首选 — 打包体积更小）：

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "us-east-1" });
const output = await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));

聚合风格（类似 v2 的风格，但并非 v2，打包体积更大）：

import { S3 } from "@aws-sdk/client-s3";
const client = new S3({ region: "us-east-1" });
const output = await client.getObject({ Bucket: "b", Key: "k" });

客户端配置

v3 中没有全局配置 — 将配置传递给每个客户端。始终需要 region；请显式设置，或通过 AWS_REGION 环境变量设置。

const config = { region: "us-east-1", maxAttempts: 5 };
const s3 = new S3Client(config);
const dynamo = new DynamoDBClient(config);

实例化后请勿读取或修改 client.config — 它是解析后的形式（例如，region 会变成异步函数）。请参阅 references/effective-practices.md。

关于 HTTP 处理程序（来自 @smithy/node-http-handler 的 NodeHttpHandler）、重试策略、终端节点详情、日志记录、FIPS、双栈、协议选择和 S3 专属选项 → 请参阅 references/clients.md。

凭证

所有凭证提供程序均来自 @aws-sdk/credential-providers。凭证按需加载，并在每个客户端中缓存，直至到期前约 5 分钟。

// Default chain (env → ini → IMDS/ECS) — use in most Node.js apps
const client = new S3Client({ credentials: fromNodeProviderChain() });

// Assume role (NOTE: fromTemporaryCredentials is correct for STS AssumeRole)
const client = new S3Client({
  credentials: fromTemporaryCredentials({ params: { RoleArn: "arn:aws:iam::123456789012:role/MyRole" } }),
});

// Named profile
const client = new S3Client({ profile: "my-profile" });

在多区域客户端之间共享凭证和套接字池：

const east = new S3Client({ region: "us-east-1" });
const { credentials, requestHandler } = east.config;
const west = new S3Client({ region: "us-west-2", credentials, requestHandler });

关于所有提供程序（Cognito、SSO、Web 身份、定制链、STS 区域优先级）→ 请参阅 references/credentials.md。

流（例如 S3 GetObject Body）

始终读取或丢弃流式响应 — 未读取的流会使套接字保持打开状态（可能耗尽套接字）：

const { Body } = await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
const str = await Body.transformToString();       // read as string
const bytes = await Body.transformToByteArray();  // read as Uint8Array
// or discard:
await (Body.destroy?.() ?? Body.cancel?.());

流只能读取一次。

分页器

使用 paginate* 函数，而不要手动处理令牌：

import { DynamoDBClient, paginateListTables } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});

const tableNames = [];
for await (const page of paginateListTables({ client }, {})) {
  // page contains a single paginated output.
  tableNames.push(...page.TableNames);
}

DynamoDB DocumentClient

使用 @aws-sdk/lib-dynamodb 处理原生 JS 类型，而不是 AttributeValues：

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
await client.send(new PutCommand({ TableName: "T", Item: { id: "1", name: "Alice" } }));
const { Item } = await client.send(new GetCommand({ TableName: "T", Key: { id: "1" } }));

关于 marshall 选项、大数值（NumberValue）、分页和聚合客户端 → 请参阅 references/dynamodb.md。

S3：预签名 URL、分段上传、等待器

// Presigned GET URL
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
const url = await getSignedUrl(client, new GetObjectCommand({ Bucket: "b", Key: "k" }), { expiresIn: 3600 });

// Multipart upload (large files / streams)
import { Upload } from "@aws-sdk/lib-storage";
const upload = new Upload({ client, params: { Bucket: "b", Key: "k", Body: stream } });
await upload.done();

// Waiters
import { waitUntilObjectExists } from "@aws-sdk/client-s3";
await waitUntilObjectExists({ client, maxWaitTime: 120 }, { Bucket: "b", Key: "k" });

关于预签名 POST、签名标头和等待器选项 → 请参阅 references/s3.md。

错误处理

import { S3ServiceException } from "@aws-sdk/client-s3";

try {
  await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
} catch (e) {
  if (e?.$metadata) {
    // SDK service error — has $metadata.httpStatusCode, e.name, e.$response
    console.error(e.name, e.$metadata.httpStatusCode);
  }
}

针对特定错误类型，请检查 e.name 或使用 instanceof。完整模式请参阅 references/error-handling.md。

关于 jsv3 中的运行时验证、序列化为非默认格式，或架构的相关问题 → 请参阅 references/schemas.md。

性能：并行工作负载

// Configure maxSockets to match your parallel batch size
const client = new S3Client({
  requestHandler: { httpsAgent: { maxSockets: 50 } },
  cacheMiddleware: true, // skip if using custom middleware
});

流式死锁警告：套接字数量有限时，不要分别 await 请求和流式正文 — 请将它们串联起来。请参阅 references/performance.md。

中间件

为客户端上的所有命令添加自定义逻辑：

client.middlewareStack.add(
  (next, context) => async (args) => {
    console.log(context.commandName, args.input);
    const result = await next(args);
    return result;
  },
  { name: "MyMiddleware", step: "build", override: true }
);

步骤（按顺序）：initialize → serialize → build → finalizeRequest → deserialize

Abort Controller

const { AbortController } = require("@aws-sdk/abort-controller");
const { S3Client, CreateBucketCommand } = require("@aws-sdk/client-s3");

const abortController = new AbortController();
const client = new S3Client(clientParams);

const requestPromise = client.send(new CreateBucketCommand(commandParams), {
  abortSignal: abortController.signal,
});

// The request will not be created if abortSignal is already aborted.
// The request will be destroyed if abortSignal is aborted before response is returned.
abortController.abort();

// This will fail with "AbortError" as abortSignal is aborted.
await requestPromise;

Lambda 最佳实践

在处理程序外部初始化客户端（复用容器），在内部发起 API 调用。对于一次性异步设置，请在处理程序中使用惰性初始化标志：

import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({}); // outside — reused across invocations

let ready = false;
export const handler = async (event) => {
  if (!ready) { await prepare(); ready = true; } // lazy one-time setup inside handler
  // ... API calls here
};

Lambda 层和版本控制请参阅 references/lambda.md。

Node.js 版本要求

• v3.968.0+ 要求 Node.js >= 20
• v3.723.0+ 要求 Node.js >= 18

TypeScript

默认情况下，响应字段的类型为 T | undefined。使用 @smithy/types 中的 AssertiveClient 移除 | undefined，或使用 NodeJsClient / BrowserClient 收窄流式 blob 类型。请参阅 references/typescript.md。

SigV4a（S3 多区域接入点）

S3 MRAP 和某些其他功能需要 SigV4a。必须安装并通过副作用导入以下其中一个，且只能导入一个：

• @aws-sdk/signature-v4-crt — 仅限 Node.js，性能更佳
• @aws-sdk/signature-v4a — 支持 Node.js 和浏览器，纯 JS 实现

import "@aws-sdk/signature-v4a"; // side-effect only — no exported values needed

完整详情和 MRAP ARN 格式请参阅 references/sigv4a.md。