删除Digital Ocean Spaces文件时触发S3ServiceException: UnknownError问题

使用Digital Ocean Spaces，通过AWS SDK实现文件上传与删除操作，代码此前稳定运行许久，近两周开始抛出XAmzContentSHA256Mismatch错误。

相关代码 #

文件删除逻辑 #

const listResponse = await this.getDirectoryListing(directory, prefix)
const files = listResponse.Contents ? listResponse.Contents!.map((item) => item.Key!) : []

if (files.length > 0) {
  await this.s3.delete({
    bucket: this.config.env.S3_PUBLIC_BUCKET,
    keys: files,
  })
  this.logger.debug('Old files deleted', { files })
}

S3 delete方法实现 #

async delete(options: IS3Delete): Promise<DeleteObjectsCommandOutput> {
  const deleteObjectsCommand = {
    Bucket: options.bucket,
    Delete: {
      Objects: options.keys.map((item) => ({ Key: item })),
    },
  }

  return this.client.send(new DeleteObjectsCommand(deleteObjectsCommand))
}

错误信息 #

"type": "S3ServiceException",
"message": "UnknownError",
"stack":
   XAmzContentSHA256Mismatch: UnknownError

1. 调整SDK客户端签名配置 #

Digital Ocean Spaces近期可能调整了签名校验规则，AWS SDK v3默认的SHA-256校验逻辑在部分场景下会出现不匹配：

• 确保使用最新稳定版的AWS SDK，避免旧版本的签名bug
• 初始化S3客户端时显式配置签名版本，并针对DeleteObjects操作跳过请求体签名：

const client = new S3Client({
  region: '你的Spaces区域', // 例如nyc3
  endpoint: 'https://nyc3.digitaloceanspaces.com',
  credentials: {
    accessKeyId: '你的Access Key',
    secretAccessKey: '你的Secret Key'
  },
  signingEscapePath: true,
  signatureVersion: 'v4',
  // 添加中间件跳过DeleteObjects的请求体SHA256校验
  middlewareStack: (stack) => {
    stack.add(next => async (args) => {
      if (args.commandName === 'DeleteObjects') {
        args.request.headers['X-Amz-Content-SHA256'] = 'UNSIGNED-PAYLOAD';
      }
      return next(args);
    }, {
      step: 'build',
      name: 'skipDeleteObjectsSha256'
    });
  }
});

2. 检查文件Key的编码一致性 #

如果文件Key包含特殊字符（中文、空格、特殊符号），编码不一致会导致SHA256计算错误：

• 确保从listResponse.Contents获取的Key未被额外转义或解码
• 尝试对Key进行URI编码后再传入删除请求：

// 修改delete方法中的Key处理逻辑
Objects: options.keys.map((item) => ({ Key: encodeURIComponent(item) }))

3. 排查网络中间件干扰 #

如果服务器使用了代理、防火墙或API网关，可能会修改请求体或头部，导致SHA256校验不匹配：

• 直接发起绕过代理的请求，验证是否是中间件导致的问题
• 检查是否有自动添加的HTTP头部（如Content-Length）与实际请求体不匹配

4. 联系Digital Ocean官方支持 #

若以上方法均无效，可能是Spaces服务端的配置变更或临时问题，提交工单说明错误类型和请求详情，获取官方技术支持。

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