最近更新时间：2024.04.12 10:40:24
首次发布时间：2023.05.10 19:17:12
本文介绍使用 TOS SDK 过程中遇到的常见问题。
以上报错是由于使用 PathStyle 请求方式导致的。 TOS 不支持路径样式（即 PathStyle）的请求方式，仅支持使用虚拟主机（即 VirtualHostStyle）的请求方式。
Path 和 VirtualHost 的区别主要在于 HTTP URL 中存储桶名称的位置，如下所示：
# Path 访问方式 https://tos-s3-cn-beijing.volces.com/{bucketname} # VirtualHost 访问方式 https://{bucketname}.tos-s3-cn-beijing.volces.com
使用各种支持 S3 协议的 SDK 和工具访问 TOS 时，请务必确保配置了 VirtualHostStyle 的请求方式。例如：
AmazonS3Builder.withPathStyleAccessEnabled(false)。~/.aws/config 文件中添加 addressing_style = virtual 内容，确保请求方式为 VirtualHostStyle。以上报错通常是因为初始化客户端时设置的 TOS 服务的域名（Endpoint）错误，TOS SDK 当前仅支持使用 TOS 协议域名（例如北京地域域名为 tos-cn-beijing.volces.com），不支持使用 S3 协议域名（例如北京 tos-s3-cn-beijing.volces.com），关于 TOS 支持的域名信息，请参见地域和访问域名。
下文列举了TOS Java SDK的依赖包及版本，如您遇到java.lang.NoSuchMethodError，java.lang.ClassNotFoundException等错误，您可以对比参考以下依赖，解决依赖冲突问题。
<dependencies> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.9.2</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>2.12.5</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.12.5</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>1.7.25</version> <scope>compile</scope> </dependency>
TOS Java SDK 底层依赖的 okhttp client，依赖了 kotlin-stdlib 的 1.4.10 版本组件。如遇到 okhttp client 的依赖冲突报错，可以在最外层 pom.xml 声明 kotlin-stdlib 的 1.4.10 版本组件依赖。
<dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-stdlib</artifactId> <version>1.4.10</version> <scope>compile</scope> </dependency>
您需要先配置桶的 CORS 策略，允许跨域请求，详细配置方式，请参见跨域访问设置。
由于跨域访问设置（CORS 策略）是配置在桶上的，因此 BrowserJS SDK 无法支持 ListBuckets 和 CreateBucket。
这个问题有两个方面的原因：
在希望提升上传对象速度的场景，推荐使用 TOS 工具，例如 tosutil、tosbrowser。
报错原因通常如下：
. 号开头，当前 Python SDK 不支持以 .开头的对象名。如果非以上原因导致的错误，请提交工单联系技术支持。
以上报错通常是因为初始化客户端时设置的 TOS 服务的域名（Endpoint）错误，TOS SDK 当前仅支持使用 TOS 协议域名（例如北京地域域名为 tos-cn-beijing.volces.com），不支持使用 S3 协议域名（例如北京 tos-s3-cn-beijing.volces.com），关于 TOS 支持的域名信息，请参见地域和访问域名。
您可以设置 enable_crc=False 关闭 CRC 校验。更多信息，请参见配置数据校验。
调用接口失败，HTTP状态码返回 400，说明客户端侧的配置或者参数有误，根据返回的信息提示进行重新配置。
以上报错通常是因为客户端到 TOS 服务端的网络高延迟导致的（触发客户端-服务端断流进而请求中断），比如客户端的网络过慢、客户端带宽过低、客户端请求超带宽、客户端 CPU 过高导致收发流异常等，建议您先确认客户端当前的网络以及程序运行环境的负载情况。如果以上均没有问题，您可以提交工单联系技术支持。
以上报错通常是因为 TOS 服务的域名（Endpoint）配置错误，TOS SDK 当前仅支持使用 TOS 协议域名（例如北京地域域名为 tos-cn-beijing.volces.com），不支持使用 S3 协议域名（例如北京 tos-s3-cn-beijing.volces.com），关于 TOS 支持的域名信息，请参见地域和访问域名。
TOS SDK 统一定义了服务端错误（TosServerError）和客户端错误（TosClientError）。各 SDK 错误码的详细获取方式，请参见以下文档：
预签名 URL 完全由 TOS SDK 在本地通过签名算法生成，不会与服务端交互，因此也不会校验有效性（例如桶是否存在、对象是否存在 etc），仅当使用预签名 URL 进行实际请求时，才会进行预签名 URL 有效性校验。
不需要，TOS SDK 会自行处理特殊字符的问题，确保上传后桶中对象名和传入的对象名一致。
TOS SDK 下载对象时，会首先生成 .temp 临时文件并将下载的数据写入该临时文件，当临时文件完全写入成功后，再重命名成最终的文件，避免已有文件被未写入完成的中间态文件覆盖导致已有文件损坏。
TOS SDK 支持通过临时 AK、临时 SK 和 STS Token 生成客户端，常用主流语言的初始化示例如下：
TOS API 没有提供删除目录的接口，使用 TOS SDK 可以通过组合列举对象和删除对象接口实现，您可以参考以下文档设置：
如果您需要定期删除桶中的对象，您可以创建生命周期规则，详细信息，请参见设置生命周期规则。
https://{bucketname}.{endpoint}/{objectkey}。TOS SDK 的日志是默认关闭的，如果您需要打开日志，可以参考以下文档：
TOS SDK 统一封装了 UploadFile、DownloadFile、ResumableCopyObject 函数分别用于实现分片上传、分片下载和分片复制，支持设置并发度并实现了断点续传能力，详细示例代码，请参见各语言的 SDK 文档。
如果想获取对象某个区间的数据，可以通过 Range 下载方式进行下载，Range 下载还可以把大对象分成多个Range下载，提升下载效率，具体使用示例，请参见范围下载 Java SDK、范围下载 Go SDK、范围下载 C++ SDK、范围下载 Node.js SDK、范围下载 Browser.js SDK、范围下载 Python SDK。
从 2.1.0 版本开始，TOS Java SDK 新增了失败重试机制，对于服务端返回的 429 和 5xx 错误，默认会进行指数退避重试，最大重试次数默认为 3。您可以在初始化 TOSV2Client 时，通过 TOSClientConfiguration 配置 maxRetryCount 参数来调整最大重试次数，设置为 0 即可关闭重试机制。具体说明，请参见初始化客户端。
TOS PHP SDK 和 TOS .NET SDK 自身没有失败重试机制，在网络环境不好的场景下，可能出现网络导致的请求失败，建议您根据实际业务情况在自己代码上添加重试机制。
警告
请勿无限重试，建议重试2 ~ 3次即可，重试会导致指数回退一段时间。如果一段时间内重试的失败率比较高，建议您放弃重试。
以上报错通常是因为客户端的 Android 环境版本较低导致，需要进行脱糖处理，详细配置方式，请参见安装 Android SDK 的注意事项。