# 踩坑与排障记录 > 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。 ## 记录格式 ```md ## 问题标题 - 现象：看到什么错误或异常行为 - 原因：确认后的根因 - 处理：具体修复步骤 - 验证：如何确认修复有效 - 关联：相关文件、文档、提交或 Issue ``` ## Vidu 文生音频线上网关可能要求 sound 字段 - 现象：画板点击 `生成游戏音效` 后，请求返回 `Failed to deserialize the JSON body into the target type: missing field sound`。 - 原因：VectorEngine Apifox `创建文生音频任务` 文档仍写 `/ent/v2/text2audio` 使用 `model + prompt + duration`，但线上 Vidu 网关曾按 `sound` 字段反序列化；只发送 `prompt` 会被上游拦截在 JSON 解析阶段。 - 处理：前端和 BFF 对内继续使用用户语义更清晰的 `prompt`；`platform-audio` 转发到 VectorEngine Vidu 时同时发送 `prompt` 与 `sound`，两者值保持一致。不要把 UI 改回 Suno `task: "sound"`、`type`、`tempo` 或 BPM。 - 验证：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml --test vector_engine_audio` 中音效请求体测试必须同时断言 `prompt` 与 `sound`；必要时用线上生成音效 smoke 确认不再出现 `missing field sound`。 - 关联：`server-rs/crates/platform-audio/src/request.rs`、`server-rs/crates/platform-audio/tests/vector_engine_audio.rs`、`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。 ## Suno 任务完成不代表已经拿到 wav 下载地址 - 现象：画板生成背景音乐时，前端报 `音频生成尚未返回可下载地址(requestId:...)`；画板生成音效时，前端可能报 `获取 Suno 音效 wav 失败(requestId:...)`。上游任务可能已经完成，但 wav 下载地址还没就绪。 - 原因：VectorEngine Suno `/suno/fetch/{task_id}` 可能先在 `data` 中返回歌曲 / 音效 clip id，而不是直接返回 `.wav` / `.mp3` URL；需要再调用 `/suno/act/wav/{clipId}` 获取 `wav_file_url`。如果只兼容 `data` 是字符串，会漏掉 `data` 对象 / 数组里的 `id`、`clip_id`、`audioId` 或 `songId`。 - 处理：`platform-audio` 查询 Suno 结果时先提取直接音频 URL；没有 URL 时，从 `data` 字符串、对象或数组提取 clip id，逐个调用 `/suno/act/wav/{clipId}`。已拿到 clip id 但 wav 地址仍未就绪，或 wav 子请求暂时返回上游错误时，都保持 `processing` 让上层继续轮询，不能直接判定为缺少可下载地址或 wav 获取失败。 - 验证：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml`；`cargo test -p api-server vector_engine_audio_generation --manifest-path server-rs/Cargo.toml`。 - 关联：`server-rs/crates/platform-audio/src/client.rs`、`server-rs/crates/platform-audio/src/response.rs`、`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。 ## 图片画布音频卡播放条 0:00 要优先查签名 URL 和嵌套交互 - 现象：画板音效或背景音乐已经生成成功，但卡片里的播放条显示 `0:00`，点击无法预览。 - 原因：generated 音频资源通常是私有 OSS 路径，直接把 `/generated-*` 或 generated OSS 地址交给 `