oss-s3

Aliyun OSS API 兼容层，用于将依赖 ali-oss 的项目迁移到 AWS S3/STS，尽量保持代码不变。

特性

• OSS 模式直连 ali-oss，S3 模式包装 AWS SDK v3
• API 与类型签名对齐 Aliyun OSS（以 @types/ali-oss 为准）
• 支持 Bun/Node 服务端与 Browser（Webpack 5）
• 支持 AWS 默认凭证链（EKS Pod Identity/EC2/ECS 角色/环境变量）

安装

bun add oss-s3
# or
npm install oss-s3

快速使用

OSS 模式（Aliyun OSS）

import OSSCompat from "oss-s3";

const client = new OSSCompat({
  mode: "oss",
  region: "oss-cn-hangzhou",
  accessKeyId: "<accessKeyId>",
  accessKeySecret: "<accessKeySecret>",
  bucket: "<bucket-name>",
});

S3 模式（AWS S3）

import OSSCompat from "oss-s3";

const client = new OSSCompat({
  mode: "s3",
  region: "us-west-2",
  bucket: "my-bucket",
});

全局默认配置（迁移开关）

import { configure, getDefaults } from "oss-s3";

configure({
  mode: "s3",
  region: "us-west-2",
  s3: { requestChecksumCalculation: "WHEN_REQUIRED", upload: { auto: true } },
});

const defaults = getDefaults();
console.log(defaults.mode, defaults.region);

说明：

• createClient / createSts 未显式传入 mode 时会使用默认值
• S3 模式未显式传入 region 时会使用默认 region
• 请在创建客户端之前调用 configure

配置说明

顶层字段（OSS/S3 共用）：

• mode: "oss" | "s3"
• region, endpoint
• accessKeyId, accessKeySecret, stsToken
• bucket, secure, timeout, cname 等 OSS 配置字段

S3 专用配置（s3 字段）：

• requestChecksumCalculation: "WHEN_SUPPORTED" | "WHEN_REQUIRED"
• requestStreamBufferSize
• forcePathStyle
• upload: { enabled?, auto?, partSize?, queueSize?, leavePartsOnError? }

S3 认证方式

• 支持显式提供 accessKeyId/accessKeySecret
• 支持 AWS 默认凭证链（EKS Pod Identity/EC2/ECS 角色/环境变量）
• 使用默认凭证链时，建议用 asyncSignatureUrl 生成签名 URL（同步 signatureUrl 需要显式 AK）
• 建议明确 region，或使用 AWS_REGION / AWS_DEFAULT_REGION

S3 上传提示

• requestChecksumCalculation 控制上传校验和计算：默认 WHEN_SUPPORTED
• 流式 Body 出现校验和报错时，可设置 requestStreamBufferSize 或将 Body 转为 ReadableStream/Uint8Array
• 若出现 “unknown length” 警告或网络协商问题，可启用 s3.upload
  • enabled: true 强制所有 put 走 Upload
  • auto: true 仅在无法推断 ContentLength 时启用 Upload

S3 模式能力覆盖

已实现：

• put / get / getStream / head / delete
• list / listV2
• copy / putMeta / deleteMulti
• getObjectUrl / generateObjectUrl
• signatureUrl / asyncSignatureUrl / signatureUrlV4

暂不支持：

• putStream
• append
• 桶级操作（listBuckets/putBucket 等）
• ACL/Policy/Logging/Website/Lifecycle/CORS 等桶配置
• multipart 相关能力（initMultipartUpload/uploadPart/complete 等）
• restore/object-tagging/rtmp/image 等扩展能力

STS 兼容性

• OSS 模式：OSS.STS（ali-oss 原生）
• S3 模式：createSts / AwsStsCompat（assumeRole 结构对齐）

构建与测试

bun run build
bun test