edge-tts 语音合成报错排查4 类常见故障的定位与修复【免费下载链接】edge-ttsUse Microsoft Edges online text-to-speech service from Python WITHOUT needing Microsoft Edge项目地址: https://gitcode.com/GitHub_Trending/ed/edge-tts你刚敲完命令test.mp3 生成了却是 0 字节或者终端一直抛 WebSocket 异常。这篇文章把 edge-tts 语音合成报错按报错信息拆开讲现象、原因、修复、验证命令照着走就能定位你的卡点。 30秒自查先对号入座再决定读哪一节。现象最可能原因对应小节403错误或SkewAdjustmentError版本过旧、系统时间偏移、无法直连服务修 edge-tts 403--list-voices挂起或超时网络到不了语音列表接口修 edge-tts 连接失败NoAudioReceived或 mp3 为 0 字节语音名无效、文本含控制字符修 0 字节音频合成耗时随文本变长串行逐条请求修速度慢一分钟看懂它怎么工作它像在外卖档口点餐你递出订单文本订单走一条专用线送到后厨WebSocket后厨把菜一盘盘端出来音频数据块你接住装进餐盒mp3。专用线的建立、订单解析、接菜都在src/edge_tts/communicate.py里完成。任何一环出错都会抛异常六类异常定义在src/edge_tts/exceptions.py报错信息能和上表一一对上。️ 按场景修复修 edge-tts 403升级版本同步时钟走直连现象合成时抛403 Client Response重试后仍然失败。最常见原因本地版本过旧与服务端接口变更对不上。电脑系统时间偏了几分钟服务会校验请求时间并拒绝。别慌先跑升级命令多数 403 到这一步就消失了。pip install --upgrade edge-tts # 同步时钟Windows 执行 w32tm /resyncLinux 执行 timedatectl set-ntp true如果在公司内网给请求加代理edge-tts --text 测试 --write-media test.mp3 --proxy http://127.0.0.1:7890验证edge-tts --text 测试 --write-media test.mp3跑完不报 403。修 edge-tts 连接失败让请求显式走代理现象edge-tts --list-voices长时间无输出最后超时或抛 JSON 解析错误。最常见原因当前网络内网、校园网、公司代理无法直连微软端点。代理环境变量配了但地址或端口不对。修复语音列表请求在src/edge_tts/voices.py发起单独给它指定代理别依赖环境变量edge-tts --list-voices --proxy http://127.0.0.1:7890验证该命令能打印出几百行语音列表。修 0 字节音频核对语音名与控制字符现象抛NoAudioReceived或--write-media生成的 mp3 是 0 字节。最常见原因--voice名字拼错或大小写不对未知语音不会返回音频。文本含控制字符OCR 出来的竖线符最常见服务直接拒绝。修复先从列表里拿准确名字再合成长文本先清洗掉不可见字符。edge-tts --list-voices | grep zh-CN edge-tts -t 你好 -v zh-CN-XiaoxiaoNeural --write-media test.mp3验证ls -l test.mp3看到文件大小大于 0。修速度慢拆分长文本并发请求现象一条几千字的文本要跑好几分钟后一段干等前一段。最常见原因脚本逐条串行调用合成。单次文本过长服务端处理时间自然拉长。修复把文本按约 1000 字一段拆开并发生成多个 mp3 再拼接需要缩短音频时长时可加--rate 10%提高语速。验证给单段合成命令套time总耗时明显低于整篇串行。 让后续更省心三个进阶做法加上之后脚本会稳定很多。语音列表缓存 24 小时列表不会天天变别每次都请求在 async 函数里执行import json, os, time from edge_tts import list_voices if not os.path.exists(voices.json) or time.time() - os.path.getmtime(voices.json) 86400: json.dump(await list_voices(), open(voices.json, w), ensure_asciiFalse)失败重试 3 次捕获两个异常类退避 1 秒、2 秒、3 秒communicate由Communicate(text)创建for wait in (1, 2, 3): try: await communicate.save(test.mp3) break except (NoAudioReceived, WebSocketError): await asyncio.sleep(wait)批量异步20 条文本一起发别串行等 20 次import asyncio from edge_tts import Communicate jobs [Communicate(t).save(fout_{i}.mp3) for i, t in enumerate(texts)] await asyncio.gather(*jobs, return_exceptionsTrue)避坑清单先升级版本再查网络403 大多是版本问题。语音名从edge-tts --list-voices里复制不要手打。OCR 或 PDF 文本先清洗再喂给服务控制字符是 0 字节的首要原因。代理用--proxy显式指定别只依赖环境变量。系统时间保持 NTP 同步偏几分钟就会被拒绝。单次文本别超 1000 字超过就分段。每次运行把 mp3 写到独立目录防止旧 0 字节文件误导判断。按异常类名定位报错src/edge_tts/exceptions.py里的类和现象一一对应。继续学习README.md—— 基础用法与全部命令行参数说明examples/—— 同步、异步、流式、字幕生成的完整示例可直接运行src/edge_tts/communicate.py—— WebSocket 连接与音频接收的核心链路报错难定位时读它src/edge_tts/exceptions.py—— 全部异常类定义用于报错归类src/edge_tts/voices.py—— 语音列表的拉取与查找逻辑大部分报错按自查表逐项修就能过。卡住时先跑这条命令确认现象edge-tts --text 测试 --write-media test.mp3【免费下载链接】edge-ttsUse Microsoft Edges online text-to-speech service from Python WITHOUT needing Microsoft Edge项目地址: https://gitcode.com/GitHub_Trending/ed/edge-tts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考