火山引擎TOS Java SDK上传文件需先初始化客户端并确保AK/SK通过环境变量配置，再创建桶或确认其存在，最后调用putObject上传本地文件或字节流；批量上传需控制并发≤10并妥善处理404/403/400等异常。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎对象存储（TOS）用Java SDK上传文件，核心是初始化客户端、创建桶、调用putObject方法传入本地文件路径或字节流。整个流程必须确保AK/SK环境变量已设置，且目标桶已存在或有创建权限。
准备SDK与认证信息
在项目pom.xml中添加TOS Java SDK依赖：
<dependency>
<groupId>com.volcengine</groupId>
<artifactId>tos-java-sdk</artifactId>
<version>2.1.0</version>
</dependency>
设置环境变量：【TOS_ACCESS_KEY】和【TOS_SECRET_KEY】必须通过系统环境变量注入，不能硬编码在代码里——否则会触发安全扫描失败，且无法通过CI/CD流水线校验。
立即学习“Java免费学习笔记（深入）”；
初始化TOS客户端
使用TosV2ClientBuilder构建客户端实例，endpoint和region需严格匹配目标桶所在地域：
String endpoint = "https://tos-cn-beijing.volces.com";
String region = "cn-beijing";
TosV2 client = TosV2ClientBuilder.builder()
.endpoint(endpoint)
.region(region)
.build();
注意：endpoint末尾不能带斜杠，region值必须与控制台桶详情页显示的“地域”完全一致（如华东1为cn-shanghai），写错会导致403 Forbidden错误。
上传单个本地文件
方法一：直接指定文件路径上传
PutObjectInput input = new PutObjectInput();
input.setBucket("my-bucket-name");
input.setKey("images/photo.jpg");
input.setFile(new File("/Users/you/pic.jpg"));
client.putObject(input);
方法二：用InputStream上传字节流（适合从HTTP响应、数据库BLOB等来源读取）
byte[] data = Files.readAllBytes(Paths.get("/tmp/report.pdf"));
input.setBucket("my-bucket-name");
input.setKey("docs/report.pdf");
input.setContent(new ByteArrayInputStream(data));
client.putObject(input);
【对象名（Key）不能以/开头，也不能包含\或控制字符】，否则抛出InvalidObjectNameException；若Key含中文，SDK会自动URL编码，无需手动处理。
批量上传多个文件
第一步：确认目标桶已存在，否则上传会失败
第二步：遍历文件列表，逐个构造PutObjectInput
第三步：对每个文件执行client.putObject()，不建议并发超过10路——TOS默认单客户端连接池上限为10，盲目开高并发反而导致ConnectionPoolTimeoutException
第四步：捕获TosServerException判断404（桶不存在）、403（权限不足）、400（参数非法）等关键错误，跳过TosClientException（网络抖动类）并重试3次
