edge-tts 语音合成报错排查：4 类常见故障的定位与修复

edge-tts 语音合成报错排查：4 类常见故障的定位与修复

【免费下载链接】edge-ttsUse Microsoft Edge's 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秒自查

先对号入座，再决定读哪一节。

一分钟看懂它怎么工作

它像在外卖档口点餐：你递出订单（文本），订单走一条专用线送到后厨（WebSocket），后厨把菜一盘盘端出来（音频数据块），你接住装进餐盒（mp3）。

• 专用线的建立、订单解析、接菜，都在src/edge_tts/communicate.py里完成。
• 任何一环出错都会抛异常，六类异常定义在src/edge_tts/exceptions.py，报错信息能和上表一一对上。

🛠️ 按场景修复

修 edge-tts 403：升级版本，同步时钟，走直连

现象：合成时抛403 Client Response，重试后仍然失败。

最常见原因：

1. 本地版本过旧，与服务端接口变更对不上。
2. 电脑系统时间偏了几分钟，服务会校验请求时间并拒绝。

别慌，先跑升级命令，多数 403 到这一步就消失了。

pip install --upgrade edge-tts # 同步时钟：Windows 执行 w32tm /resync，Linux 执行 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 解析错误。

最常见原因：

1. 当前网络（内网、校园网、公司代理）无法直连微软端点。
2. 代理环境变量配了但地址或端口不对。

修复：语音列表请求在src/edge_tts/voices.py发起，单独给它指定代理，别依赖环境变量：

edge-tts --list-voices --proxy http://127.0.0.1:7890

验证：该命令能打印出几百行语音列表。

修 0 字节音频：核对语音名与控制字符

现象：抛NoAudioReceived，或--write-media生成的 mp3 是 0 字节。

最常见原因：

1. --voice名字拼错或大小写不对，未知语音不会返回音频。
2. 文本含控制字符（OCR 出来的竖线符最常见），服务直接拒绝。

修复：先从列表里拿准确名字，再合成；长文本先清洗掉不可见字符。

edge-tts --list-voices | grep zh-CN edge-tts -t "你好" -v zh-CN-XiaoxiaoNeural --write-media test.mp3

验证：ls -l test.mp3看到文件大小大于 0。

修速度慢：拆分长文本，并发请求

现象：一条几千字的文本要跑好几分钟，后一段干等前一段。

最常见原因：

1. 脚本逐条串行调用合成。
2. 单次文本过长，服务端处理时间自然拉长。

修复：把文本按约 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_ascii=False)

失败重试 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(f"out_{i}.mp3") for i, t in enumerate(texts)] await asyncio.gather(*jobs, return_exceptions=True)

避坑清单

1. 先升级版本，再查网络，403 大多是版本问题。
2. 语音名从edge-tts --list-voices里复制，不要手打。
3. OCR 或 PDF 文本先清洗再喂给服务，控制字符是 0 字节的首要原因。
4. 代理用--proxy显式指定，别只依赖环境变量。
5. 系统时间保持 NTP 同步，偏几分钟就会被拒绝。
6. 单次文本别超 1000 字，超过就分段。
7. 每次运行把 mp3 写到独立目录，防止旧 0 字节文件误导判断。
8. 按异常类名定位报错，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 Edge's online text-to-speech service from Python WITHOUT needing Microsoft Edge项目地址: https://gitcode.com/GitHub_Trending/ed/edge-tts