1. 功能说明

本文档提供基于 AWS SDK for Java 2.x 实现的 S3 文件上传示例代码，支持通过指定 AK/SK（单独交付）和区域，将本地文件（字节数组形式）上传到指定 S3 Bucket 的指定路径下，适配第三方快速集成使用。

2. 前置依赖

2.1 Maven 依赖配置

将以下依赖添加到项目 pom.xml 文件中，无需额外依赖其他组件（可选工具依赖用于简化文件读取）：

<!-- AWS S3 SDK 核心依赖（必选） -->
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.25.0</version> 
</dependency>

<!-- AWS 区域管理依赖 -->
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>regions</artifactId>
    <version>2.25.0</version>
</dependency>

<!-- 可选：文件操作工具（示例用，简化本地文件读取，可替换为自有文件读取逻辑） -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.22</version>
</dependency>

2.2 环境要求

JDK 版本：JDK 8 及以上（兼容 JDK 11+）

密钥要求：已获取 AWS S3 访问密钥（AK/SK），密钥将单独以文件形式交付，且该密钥需拥有目标 Bucket 的上传权限

网络要求：服务器/本地环境可正常访问 AWS S3（ap-east-1 区域），无防火墙拦截

3. 完整示例代码

直接复制以下代码到项目中，替换占位符即可使用（关键注释已标注，无需修改核心逻辑）：

4. 使用指南

4.1 核心参数说明

参数名	说明	是否可修改	示例/占位符
accessKey	AWS S3 访问密钥 AK（单独文件交付）	是（必须替换为交付的 AK）	【请填入单独文件提供的 AK】
secretKey	AWS S3 访问密钥 SK（单独文件交付）	是（必须替换为交付的 SK）	【请填入单独文件提供的 SK】
region	S3 存储区域（香港区域）	否（固定为 ap-east-1）	ap-east-1
bucketName	S3 目标 Bucket 名称	是（和环境有关）	测试环境：falpay-test，生产环境falpay
s3Key	文件在 S3 中的存储路径（含文件名）	是（可根据需求调整路径）	/mk/20260203/test122.txt
localFilePath	本地待上传文件的绝对路径	是（必须替换为实际文件路径）	D:/test122.txt、/home/test.txt

4.2 具体操作步骤

获取密钥：从单独交付的密钥文件中，提取 AK 和 SK；

替换参数：打开示例代码，将 accessKey 和 secretKey 的占位符，替换为提取的实际密钥；

配置文件路径：将 localFilePath 替换为本地待上传文件的绝对路径（确保文件存在、有读取权限）；

可选调整：根据实际需求，修改 s3Key（文件在 S3 中的存储路径）；

运行测试：执行 main 方法，若控制台打印“文件上传成功”及响应 ETag，说明集成成功；

集成到项目：将 uploadFileToS3 方法集成到自身业务代码中，传入对应参数即可实现上传。

4.3 常见异常及解决方法

IOException：本地文件读取失败 → 检查 localFilePath 是否正确、文件是否存在、是否有读取权限；

S3Exception（密钥无效） → 检查 AK/SK 是否替换正确，是否与单独交付的文件一致；

S3Exception（权限不足） → 联系我方确认密钥是否拥有 falpay-test Bucket 的上传权限；

S3Exception（区域错误） → 确保 region 为 ap-east-1，未修改该参数；

网络连接异常 → 检查本地/服务器网络，确保可访问 AWS S3（ap-east-1 区域），关闭拦截防火墙。

5. 注意事项

密钥安全：

密钥仅单独交付，请勿将密钥硬编码到代码仓库、配置文件、日志等公开/共享位置；

生产环境建议通过环境变量、配置中心等安全方式注入密钥，避免明文存储；

请勿泄露密钥，若密钥不慎泄露，需立即联系我方更换。

文件大小限制：本示例适用于 小文件上传（建议单个文件不超过 100MB）。

客户端资源：使用完 S3Client 后，必须调用 close() 方法，避免连接泄漏，影响系统性能。

路径规范：s3Key 建议以 / 开头（如 /mk/xxx.txt），避免路径混乱；本地文件路径需符合对应系统规范（Windows 用 \，Linux/Mac 用 /）。

文件上传

1. 功能说明#

2. 前置依赖#

2.1 Maven 依赖配置#

2.2 环境要求#

3. 完整示例代码#

4. 使用指南#

4.1 核心参数说明#

4.2 具体操作步骤#

4.3 常见异常及解决方法#

5. 注意事项#