错误与排障（Errors & Troubleshooting）

本页汇总分镜生成、素材处理、工程剪辑与下载环节的常见错误数据示例与排障建议，涵盖参数缺失、ICE任务失败、OSS预签名异常、媒体已存在兼容等。

常见错误与示例

上传/注册异常

{ "message": "上传ICE素材异常：返回为空", "returnCode": 10000 }

排查要点：

• 确认 videoUrl/audioUrl 是否可访问；若为私有路径，需走OSS直传并转为 presign_url。
• 优先使用 oss://bucket/key 注册；HTTP地址会追加 &extension=extension.mp4 来确保识别。

缺少视频素材ID（步骤1校验失败）

{ "message": "第 1 条素材上传/注册失败：缺少视频素材ID", "returnCode": 10000 }

排查要点：

• 检查 fetchUploadMediaByUrl 返回结果是否包含 videoMediaId。
• 如素材已注册，改用 fetchRegisterMediaInfo 返回的 MediaId。

生成任务失败（步骤4）

{ "MediaProducingJob": { "Status": "Failed", "Message": "剪辑失败" } }

排查要点：

• 检查 Timeline 结构：VideoTracks、AudioTracks、SubtitleTracks 是否完整且时长匹配。
• 检查输出配置 outputMediaConfig.MediaURL 是否指向有效OSS写入位置。

获取临时下载地址失败（步骤5）

{ "timestamp": 1760596678, "returnCode": 1001, "message": "参数错误,system_error_lack_params" }

排查要点：

• 确认传参包含 bucket 与 key；后端已默认 region=cn-shenzhen。
• 若是多区域部署，请显式传递 region。

ICE 媒体已存在（后端兼容）

// 原始 ICE 异常
{ "code": "MediaAlreadyExist", "message": "registerMediaInfo: mediaId: 60b6c2d... 已存在" }

// 兼容返回（成功透传 MediaId）
{ "responseHeader": { "returnCode": 0, "message": "成功" }, "responseData": { "MediaId": "60b6c2d32e5071f080580360d1d76502", "existed": 1 } }

排查要点：

• 遇到已存在直接使用返回 MediaId；避免重复上传与浪费时间。

排障清单（Checklist）

• URL合法性：统一用 sanitizeUrl 清理并校验 http(s) 格式；blob: 需走直传。
• OSS对象存在性：通过 listFiles 或后端存在性校验确认 key 可用。
• Timeline生成：字幕字体大小与换行策略保持一致（ice-lib.js 的动态计算）。
• 任务轮询：失败时停止并提示；成功后读取 MediaURL。
• 预签名下载：bucket/key 必填；下载用 presign_url。
• 错误提示一致性：统一使用交互提示与日志输出，便于复盘。

建议与最佳实践

• 优先走OSS Key注册与工程创建，减少网络不稳定对URL上传的影响。
• 合成类型选择：单条合成更易定位问题；合并合成需确保各分镜时长与音轨一致。
• 内容合规：若涉及审核，建议在生成阶段对文本进行 Green-OCR 或内容安全筛查。