AWS SDK .NET上传S3含非ASCII字符自定义元数据报错

我之前也踩过这个坑！核心问题在于S3对自定义元数据的编码规则不是HtmlEncode那套，而是严格遵循RFC 2616的要求：元数据的键和值必须是ISO-8859-1编码的可打印ASCII字符，或者对非ASCII内容使用Base64编码。你用HttpUtility.HtmlEncode转义法语字符（比如把é转成é），S3根本不识别这种HTML实体编码，自然会抛出和未转义时一样的异常。

下面给你两种可行的解决方案：

方案一：用ISO-8859-1编码直接处理（适合法语这类在ISO-8859-1中有对应字符的场景） #

法语的特殊字符（é、à、ç等）刚好在ISO-8859-1编码的覆盖范围内，直接转成该编码的字符串即可：

var putRequest = new PutObjectRequest
{
    BucketName = "你的存储桶名称",
    Key = "对象键名",
    FilePath = "本地文件路径",
    Metadata = new Dictionary<string, string>()
};

// 处理法语元数据值
string frenchMetaValue = "Café au lait";
// 先转成ISO-8859-1字节，再转回字符串
byte[] isoBytes = Encoding.GetEncoding("ISO-8859-1").GetBytes(frenchMetaValue);
string encodedMetaValue = Encoding.GetEncoding("ISO-8859-1").GetString(isoBytes);

// 添加自定义元数据（键建议只用ASCII字符）
putRequest.Metadata.Add("x-amz-meta-french-label", encodedMetaValue);

using (var s3Client = new AmazonS3Client())
{
    var response = await s3Client.PutObjectAsync(putRequest);
}

方案二：用Base64编码（通用方案，支持所有非ASCII字符） #

如果你的元数据包含更复杂的非ASCII字符（比如超出ISO-8859-1范围的），Base64编码是更稳妥的选择：

var putRequest = new PutObjectRequest
{
    BucketName = "你的存储桶名称",
    Key = "对象键名",
    FilePath = "本地文件路径",
    Metadata = new Dictionary<string, string>()
};

string frenchMetaValue = "Café au lait";
// 先转UTF8字节，再Base64编码
string base64EncodedValue = Convert.ToBase64String(Encoding.UTF8.GetBytes(frenchMetaValue));

putRequest.Metadata.Add("x-amz-meta-french-label", base64EncodedValue);

using (var s3Client = new AmazonS3Client())
{
    var response = await s3Client.PutObjectAsync(putRequest);
}

注意：当你后续读取元数据时，需要反向解码——如果用Base64编码，就先解码Base64再转UTF8；如果用ISO-8859-1，直接转成对应编码的字符串即可。

额外注意事项 #

• 元数据的键名也不能包含非ASCII字符，建议统一用x-amz-meta-前缀+ASCII命名（比如x-amz-meta-french-description）。
• 彻底放弃HttpUtility.HtmlEncode处理S3元数据，这种转义方式是为HTML场景设计的，完全不符合S3的元数据规则。

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