TOS文件上传失败需按四步排查：一查权限与凭证有效性，确认【tos:PutObject】权限及STS Token未过期；二判断点续传状态，检查checkpoint文件或日志提示；三排网络与分片异常，验证partSize、taskNum及byte range；四验对象命名与桶状态，确保objectKey合法、bucketName合规且状态为Active。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎对象存储（TOS）文件上传失败时，需根据错误类型快速定位原因并执行对应修复操作，避免重复提交或数据不一致。
检查上传权限与凭证有效性
确认当前账号具备 【tos:PutObject】 权限，且未被策略显式拒绝。若使用临时凭证（STS Token），需验证其未过期、AccessKey ID 和 Secret 未被轮转失效。
在控制台访问「权限配置指南」页面，核对策略中是否包含允许 PutObject 操作的 Statement，特别注意 Resource 字段是否精确匹配目标 Bucket 和 Object Key 前缀。
调用 SDK 时若抛出 TosClientError 且 message 含 “AccessDenied”，说明鉴权失败，此时应立即停止重试，先修正凭证或策略。
判断是否为断点续传中断导致
方法一：查看本地是否存在同名 checkpoint 文件（路径通常为 uploadFilePath.{Base64Md5(bucket+objectKey)}.upload）
方法二：若 SDK 日志中出现 “resume from checkpoint” 或 “upload resumed at part X”，说明上次上传已记录进度，可直接复用原参数再次调用 upload 接口。
【注意】上传过程中若本地文件内容被修改（如时间戳、大小、MD5 变更），SDK 将强制丢弃 checkpoint 并重新分片上传全部内容，此时需确认文件未被其他进程写入。
排查网络与分片异常
第一步：捕获错误码。若返回 TosServerError 且 statusCode 为 400，检查 partSize 是否在 5MB–5GB 范围内，taskNum 是否为 1–1000 整数。
第二步：若错误含 “Network Error” 或 “timeout”，切换至弱网模拟环境复现，启用 SDK 的 client-side timeout 配置（如 requestTimeoutMs 设为 30000）。
第三步：对单个分片上传失败的场景，SDK 默认自动重试 3 次；若连续失败，需手动检查该分片对应 byte range 是否与文件实际长度冲突——例如文件仅剩最后 2MB 却尝试上传 5MB 分片，将触发 400 错误。
验证对象命名与桶状态
确认 objectKey 不含非法字符（如 \、、?、*、|、"、:、/），且总长度 ≤1024 字节。
检查 bucketName 是否符合 DNS 兼容命名规范（全小写、仅含字母、数字、连字符，且不以连字符开头或结尾），并在控制台确认该 Bucket 状态为 “Active” 而非 “Suspended” 或 “Deleted”。
若上传路径含前缀（如 photos/2024/08/abc.jpg），无需额外创建“文件夹”，但需确保前缀本身不违反对象命名规则。
启用日志与事件回调定位根因
在 SDK 初始化时开启 debug 日志：设置 logLevel: 'debug'，捕获从初始化连接、分片调度、HTTP 请求到响应解析的完整链路。
注册 uploadProgress 回调函数，在每完成一个分片后打印 partNumber、size、elapsedTime，观察是否某一分片长期卡住或反复失败。
若使用 cancelToken 或 cancelHook，确认未在上传中途主动触发 cancel 方法——该操作不可逆，会清空 checkpoint 并终止任务。
