Angular由一个bug说起之九：AWS S3 文件下载问题

引言

在现代 Web 开发中，我们经常需要处理来自全球不同地区的数据，这包括文件名中可能包含的非拉丁文字符。最近，在一个项目中，我们遇到了一个与 Amazon S3 服务相关的挑战，涉及到文件名编码的处理。当从 S3 下载文件时，Content-Disposition 响应头默认使用 ISO-8859-1 编码，这在处理非西欧语言的文件名时产生了问题。本文将探讨这个问题的根源以及我们如何通过 JavaScript 解决它，确保文件名在全球范围内都能正确显示和处理。

问题描述

S3 在处理文件名时，当涉及到具有非 ASCII 字符的文件名时，这会出现以下报错。

<Error><Code>InvalidArgument</Code><Message>Header value cannot be represented using ISO-8859-1.</Message><ArgumentName>response-content-disposition</ArgumentName><ArgumentValue>attachment; filename="你好_08/13/2024 08:20:13.txt"</ArgumentValue><RequestId>7V589GT52SR89KPV</RequestId><HostId>ELk+GX3W7FrkfoBVirG0MgIYwhPFpCSsdscn9Ab9M9R1va7ueWihyT0IjgWWcpx2uKkLBDne0205pT53QljA==</HostId></Error>

报错的原因是我们使用了非英文字符，HTTP 协议的 Content-Disposition 头通常用来告诉客户端如何处理响应内容，比如是否应该提示用户下载文件。此头中包含的文件名默认使用 ISO-8859-1 编码，这在处理中文、日文、韩文等语言的文件名时就会出现问题，因为这些字符在 ISO-8859-1 编码中是无法表示的。

解决方案：使用正确的编码与请求头

要解决这个问题，我们需要在发送下载请求时使用正确的编码格式，并在请求头中明确指定文件名的编码方式。以下是使用 JavaScript 和 AWS SDK for JavaScript 来实现这一目标的具体步骤：

文件名编码：在上传文件时，使用 URL 编码（百分比编码）对文件名进行编码，以确保其中的 Unicode 字符能够被正确识别。例如，中文"你好"应编码为 %E4%BD%A0%E5%A5%BD。
设置请求头：在下载文件时，通过设置 response-content-disposition 请求头，指定使用 UTF-8 编码来解码文件名。这告诉接收方应用程序应如何解码文件名。

实践示例

以下是一个使用 AWS SDK for JavaScript (v3) 的示例代码片段，展示了如何正确设置请求头以支持 Unicode 文件名：

javascript 复制代码

// 导入必要的模块
const { S3Client, GetObjectCommand } = require("@aws-sdk/client-s3");

// 初始化 S3 客户端
const s3Client = new S3Client({ region: "your-region" });

// 设置参数
const params = {
  Bucket: 'your-bucket-name',
  Key: encodeURIComponent('你的文件名.txt'), // 注意：使用 encodeURIComponent 对文件名进行编码
};

// 构建请求头
const headers = {
  'response-content-disposition': `attachment; filename*=UTF-8''${encodeURIComponent('你的文件名.txt')}`,
};

// 发送 GET 请求下载文件
const command = new GetObjectCommand(params);
command.input.RequestPayer = 'requester';
command.overrideConfiguration({ httpOptions: { headers } });

s3Client.send(command).then(response => {
  console.log("File downloaded successfully.");
}).catch(error => {
  console.error("Error downloading file:", error);
});

注意事项

确保在上传文件时，文件名已正确编码。
在下载请求中，使用 encodeURIComponent 函数对文件名进行编码，并在请求头中明确指定 UTF-8 编码。
如果使用的是浏览器环境，还需要注意浏览器对响应的处理方式，确保正确解码文件名。

结论

通过在 JavaScript 应用程序中采用正确的编码策略和设置请求头，您可以确保在使用 AWS S3 服务时，即使文件名包含 Unicode 字符，也能正确显示和下载。这不仅提高了用户体验，还体现了应用程序对全球用户的包容性。