从aws-sdk v2迁移到v3时遇NotImplemented错误求助

问题原因 #

你遇到的NotImplemented: A header you provided implies functionality that is not implemented错误，是因为AWS SDK v3（从3.200.0左右版本开始）默认启用了**灵活校验和（Flexible Checksums）**功能。该功能会自动向请求添加x-amz-checksum-algorithm等头部，但部分S3兼容存储服务（如MinIO、旧版私有存储）或特定AWS配置不支持这个特性，从而触发报错。更新@aws-sdk/smithy-client无法解决问题，因为根源在@aws-sdk/client-s3自带的中间件。

解决方案 #

方案1：全局禁用灵活校验和中间件 #

在初始化S3Client时，移除自动添加的flexible checksums中间件：

const { S3Client, PutObjectCommand, DeleteObjectCommand, HeadObjectCommand, HeadBucketCommand, GetObjectCommand } = require('@aws-sdk/client-s3');
const { flexibleChecksumsMiddleware } = require('@aws-sdk/middleware-flexible-checksums');

class S3Storage {
  constructor(config, log) {
    this.bucket = config.s3_bucket;
    this.log = log;
    const cfg = {
      region: config.aws_bucket_region,
      credentials: {
        accessKeyId: config.aws_access_key,
        secretAccessKey: config.aws_secret_access_key
      },
    };
    this.s3 = new S3Client(cfg);
    // 移除flexible checksums中间件，避免自动添加不支持的请求头部
    this.s3.middlewareStack.remove(flexibleChecksumsMiddleware, "before signing");
  }

  async length(id) {
    const result = await this.s3.send(new HeadObjectCommand({ Bucket: this.bucket, Key: id }));
    return Number(result.ContentLength);
  }

  getStream(id) {
    return this.s3.send(new GetObjectCommand({ Bucket: this.bucket, Key: id }));
  }

  set(id, file) {
    const command = new PutObjectCommand({
      Bucket: this.bucket,
      Key: id,
      Body: file
    });
    return this.s3.send(command);
  }

  del(id) {
    const command = new DeleteObjectCommand({ Bucket: this.bucket, Key: id });
    return this.s3.send(command);
  }

  ping() {
    const command = new HeadBucketCommand({ Bucket: this.bucket });
    return this.s3.send(command);
  }
}

module.exports = S3Storage;

方案2：单个命令禁用校验和 #

如果只需要针对PutObjectCommand禁用该功能，可以在命令参数中显式设置ChecksumAlgorithm为undefined：

set(id, file) {
  const command = new PutObjectCommand({
    Bucket: this.bucket,
    Key: id,
    Body: file,
    ChecksumAlgorithm: undefined // 阻止SDK自动添加校验和头部
  });
  return this.s3.send(command);
}

额外排查点 #

• 如果你使用的是AWS官方S3服务，确认存储桶所在区域是否支持校验和功能（大部分最新区域都支持，但极少数旧区域可能存在限制）。
• 如果你使用的是第三方S3兼容存储，查看其官方文档是否支持x-amz-checksum-algorithm头部，若不支持则必须使用上述方案禁用该功能。

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