需显式声明aliyun-sdk-oss 3.17.6并排除其httpclient依赖，手动引入兼容版本；JDK至少为8，17+需用3.17.0+；初始化后必须调用listBuckets验证连通性；上传大文件须设超时、ContentLength或改用uploadFile；AK/SK应通过环境变量管理。
怎么配 com.aliyun.oss 依赖不报 NoClassDefFoundError
Aliyun OSS SDK 的 Java 版本对 JDK 和依赖管理很敏感，直接加个 Maven 依赖常会漏掉关键组件。最常见的是缺 aliyun-java-sdk-core 或用了不兼容的 httpclient 版本。
- 用 Maven 时，必须显式声明
aliyun-sdk-oss（最新稳定版是3.17.6），它不传递引入aliyun-java-sdk-core，得自己加 - 如果项目里已有
org.apache.httpcomponents:httpclient（比如 Spring Boot 2.x 自带 4.5.x），别让 OSS SDK 拉它的旧版 4.3.x —— 排除掉httpclient子依赖，再手动指定版本 - JDK 8 是底线，JDK 17+ 需确认用的是
3.17.0+，否则OSSClientBuilder初始化会抛UnsupportedClassVersionError
<dependency>
<groupId>com.aliyun.oss</groupId>
<artifactId>aliyun-sdk-oss</artifactId>
<version>3.17.6</version>
<exclusions>
<exclusion>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
</exclusion>
</exclusions>
</dependency>
OSSClientBuilder 初始化失败：AccessKey 无效但没报具体错
OSS SDK 默认静默吞掉部分认证异常，OSSClientBuilder.build() 成功不代表连接通了，只是对象建出来了。真到 putObject 才爆 InvalidAccessKeyId 或 SignatureDoesNotMatch。
- 初始化后务必调用一次
ossClient.listBuckets()做连通性验证，它会立即触发鉴权请求 - AccessKey ID 和 Secret 必须从阿里云控制台「AccessKey 管理」页获取，不能用 RAM 用户未授权的子账号密钥，否则报
AccessDenied - Endpoint 不能写错：华东1（杭州）是
https://oss-cn-hangzhou.aliyuncs.com，不是http://，也不是oss-cn-hangzhou.aliyuncs.com（少协议头）
上传文件时卡住或超时，PutObjectRequest 怎么设参数才稳
默认上传行为在弱网或大文件下极不可靠：无重试、无分片、超时仅 30 秒，且 InputStream 被读一次就失效，重复调用会空指针。
- 必设连接与 socket 超时：
request.setConnectTimeout(60 * 1000)、request.setSocketTimeout(120 * 1000) - 大于 100MB 的文件，别用
putObject(bucket, key, input)，改用ossClient.putObject(new PutObjectRequest(...).withMetadata(metadata))并提前算好ContentLength，否则 SDK 会试图缓存整个流 - 如需断点续传，直接换
ossClient.uploadFile(...)方法，它内部自动分片、校验、重试
Spring Boot 项目里怎么安全管 AccessKey 和 Endpoint
硬编码或塞 application.properties 明文是高危操作，OSS SDK 不支持 Spring 的 @ConfigurationProperties 自动绑定，得自己桥接。
立即学习“Java免费学习笔记（深入）”；
- 用
@Value("${aliyun.oss.endpoint}")注入配置项，但 AccessKey Secret 必须走系统环境变量或阿里云 KMS，避免被日志打印出来 - 别在
@Bean里直接 newOSSClientBuilder，要用@Scope(ConfigurableBeanFactory.SCOPE_SINGLETON)控制单例，否则每次拿 client 都新建连接池 - 记得在应用关闭时调用
ossClient.shutdown()，否则线程池不释放，Tomcat 重启后可能连不上
Endpoint 和 Bucket 名拼写错误、AK/SK 权限不足、网络策略拦截出方向 HTTPS 流量——这三类问题占线上故障的八成，查的时候先盯死这三项，比翻 SDK 源码快得多。
