edge-tts 保姆级部署教程：免费调用微软 Edge 神经网络语音合成，Python/CLI/HTTP 服务全流程

edge-tts 是一个 Python 模块，让你在自己的 Python 代码里、或通过命令行，免费调用微软 Edge 浏览器背后那套神经网络语音合成（TTS）服务——不需要安装 Edge 浏览器、不需要 Windows、不需要申请 API Key、不需要付费。它本质上是把 Edge 朗读功能的 WebSocket 接口逆向封装成了一个开源库，输出的 mp3 音质与 Edge 浏览器里"大声朗读"按钮一模一样，音色覆盖全球 100+ 语言、数百种神经网络音色（包括中文晓晓、云希等明星音色）。对个人开发者、自媒体、有声书作者来说，这是目前能白嫖到的最高质量 TTS 接口之一。本文按官方 README，从安装、CLI 用法、Python API 一路讲到自托管 HTTP 服务。

一、项目介绍与适用场景

edge-tts 由 rany2 维护，源码主体采用 LGPLv3 协议（仅 src/edge_tts/srt_composer.py 一个文件是 MIT）。它的工作原理：Python 库通过 WebSocket 连接微软在线 TTS 端点，把文本发过去，流式接收 mp3 音频块，拼成完整文件。整个过程中你的代码只需要能联网访问微软服务器即可。

适用场景：

自媒体/有声书作者：批量把长文本转成带 SRT 字幕的 mp3，直接给视频配音；
Python 开发者：在自己的脚本里嵌一句 edge_tts.Communicate(text, voice).save("out.mp3") 就完成 TTS；
自托管轻量 TTS 服务：用 FastAPI 把 edge-tts 包一层 HTTP 接口，给家里的智能家居、阅读机器人、播客生成器用；
完全无 GPU 场景：不需要任何显卡、不需要下载模型，所有计算都在微软服务器上完成，树莓派、NAS、低配 VPS 都能跑。

与站点此前写过的所有 TTS 项目（GPT-SoVITS、VoxCPM、EmotiVoice 等）相比，edge-tts 是唯一"零本地推理"的方案：别的项目都要下载几个 GB 的模型、占几 GB 显存，edge-tts 只占几 MB，效果却接近商用级 TTS。代价是它依赖微软在线接口，不能离线、不能克隆自定义音色、商用有灰色地带（见第十一章）。

具体来说，edge-tts 适合的场景非常明确：你需要一个"立刻能用、效果好、不要钱、不要显卡"的 TTS，而不是要训练自己的音色、不是要离线部署。它背后是微软 Azure 神经网络 TTS 服务，输出质量和 Edge 浏览器大声朗读、微软 Office 配音功能同源，比绝大多数开源小模型的合成质量都高。一个常见玩法是：自媒体用它批量生成配音，再用剪映/CapCut 对齐字幕；开发者用它给命令行工具、智能家居、朗读类 App 接一个零成本 TTS 后端；研究者用它做 TTS 对比实验的 baseline。

二、核心功能逐条拆解

一行命令合成：edge-tts --text "..." --write-media out.mp3 直接出 mp3。
同步生成 SRT 字幕：--write-subtitles out.srt 同时导出带时间轴的字幕文件，可直接给剪辑软件用。
数百种音色：--list-voices 列出全部可用音色，按语言/性别/风格分类。
语速/音量/音高调节：--rate、--volume、--pitch 三个参数微调。
edge-playback 即时回放：合成完直接用 mpv 在终端播放，适合快速试听音色。
Python API：同步 Communicate 与异步 AsyncCommunicate 两种模式。
流式输出：边接收边写文件/边播放，长文本不用等全文合成完。
流式输出：边接收边写文件/边播放，长文本不用等全文合成完。
SubMaker 字幕生成器：edge_tts.SubMaker() 类直接从流式 chunk 里累积词边界时间轴，一行代码生成 SRT。
进度条：终端下自动显示下载进度（已接收音频占总时长百分比）。

官方内置的中文音色（从 --list-voices 里挑常用的）包括：

zh-CN-XiaoxiaoNeural：晓晓，女声，温暖亲切，最常用；
zh-CN-XiaoyiNeural：晓伊，女声，更年轻甜美；
zh-CN-YunjianNeural：云健，男声，体育解说风格；
zh-CN-YunxiNeural：云希，男声，阳光少年；
zh-CN-YunxiaNeural：云夏，男声，小男孩；
zh-CN-YunyangNeural：云扬，男声，专业新闻播报；
zh-HK-HiuMaanNeural：粤语女声；
zh-TW-HsiaoChenNeural：台湾国语女声。

三、全套官方链接

类型	链接
GitHub 仓库	https://github.com/rany2/edge-tts
官方文档	https://github.com/rany2/edge-tts/blob/master/README.md
官方 Demo	无（纯库，无在线 Demo）
License	LGPLv3（仅 srt_composer.py 为 MIT）

四、硬件与环境前置要求

edge-tts 是纯网络 IO 库，官方 README 没有任何 GPU/模型要求：

系统：Linux / macOS / Windows 任意；
Python：官方 PyPI 支持的 Python 版本（建议 3.9+）；
网络：必须能访问微软 Azure TTS 端点（国内直连通常可用，若被墙需代理）；
磁盘：< 10MB；
播放额外依赖：edge-playback 命令需要系统装 mpv（Windows 除外）。

官方出处：README "Installation" 与 "Usage" 小节。

补充说明：edge-tts 跑在 NAS、树莓派、Docker 容器、甚至 GitHub Actions 里都没问题——只要容器能访问外网。一个常见的部署姿势是把它塞进一个 Docker 镜像，配合 FastAPI 暴露成 TTS 微服务，给家庭自动化（HomeAssistant）、播客生成器、视频批量处理流水线共用。官方 README 也提到有第三方项目（hass-edge-tts、Podcastfy）已经把 edge-tts 作为 TTS 后端集成进了自己的产品，说明它在真实生产环境里是可用的。

五、多平台部署步骤

5.1 pip 安装（官方）

pip install edge-tts

如果只打算用命令行、不想污染全局 Python 环境，官方推荐用 pipx：

pipx install edge-tts

逐段解释：pipx 会为 edge-tts 创建一个独立的虚拟环境，并把 edge-tts、edge-playback 两个命令链接到系统 PATH，效果等同于"装了两个普通命令行工具"。

5.2 Windows 部署

Windows 上直接 pip install edge-tts 即可（官方 README 明确说 edge-playback 在 Windows 上不需要 mpv）。用 PowerShell 执行：

pip install edge-tts
edge-tts --text "你好，这是一段测试。" --voice zh-CN-XiaoxiaoNeural --write-media hello.mp3

5.3 验证安装

edge-tts --list-voices

终端会打印一张完整音色表，表头为 Name | Gender | ContentCategories | VoicePersonalities。看到类似 zh-CN-XiaoxiaoNeural、zh-CN-YunxiNeural 的中文音色即安装成功。

5.4 Linux / macOS 即时回放（可选）

# Ubuntu/Debian 装 mpv
sudo apt install mpv

# macOS 装 mpv
brew install mpv

edge-playback --text "Hello, world!"

六、配置文件全部参数解释

edge-tts 无配置文件，全部参数走命令行。按官方 README 整理：

参数	作用	可选值	默认值	示例	改错后果
`--text`	要合成的文本	字符串	必填	`--text "你好"`	不写会报错
`--voice`	音色名	见 `--list-voices`	`en-US-...` 默认英文音色	`--voice zh-CN-XiaoxiaoNeural`	音色名写错报 403
`--write-media`	输出音频文件路径	mp3 路径	无	`--write-media out.mp3`	目录不存在写失败
`--write-subtitles`	输出 SRT 字幕路径	srt 路径	无	`--write-subtitles out.srt`	同上
`--rate`	语速	百分比，如 `+50%`/`-50%`	`+0%`	`--rate=-50%`	负号必须用 `=` 写法，否则被当成命令行参数
`--volume`	音量	百分比	`+0%`	`--volume=-50%`	同上
`--pitch`	音高	Hz，如 `-50Hz`	`+0Hz`	`--pitch=-50Hz`	同上
`--list-voices`	列出全部音色	开关	关	`--list-voices`	与其他命令互斥
`--no-progress`	关闭进度条	开关	关	`--no-progress`	重定向 stderr 时自动关闭

官方特别提示：负参数必须写成 --rate=-50% 而不是 --rate -50%，否则命令行解析器会把 -50% 当成另一个选项。

七、启动、后台常驻与开机自启

edge-tts 本身是命令行工具，没有"常驻服务"概念。如果你希望把它变成一个常驻 HTTP TTS 服务，可以用 FastAPI 自己包一层（这是自托管价值所在）：

# tts_server.py
from fastapi import FastAPI
from pydantic import BaseModel
import edge_tts, asyncio, os

app = FastAPI()

class TTSRequest(BaseModel):
    text: str
    voice: str = "zh-CN-XiaoxiaoNeural"
    rate: str = "+0%"
    volume: str = "+0%"

@app.post("/tts")
async def tts(req: TTSRequest):
    out = "/tmp/out.mp3"
    communicate = edge_tts.Communicate(req.text, req.voice, rate=req.rate, volume=req.volume)
    await communicate.save(out)
    return {"url": f"/audio/{os.path.basename(out)}"}

启动：

pip install fastapi uvicorn
uvicorn tts_server:app --host 0.0.0.0 --port 50021

后台常驻写 systemd：

[Unit]
Description=Edge TTS HTTP Service
After=network.target

[Service]
User=your_user
WorkingDirectory=/your/path
ExecStart=/usr/bin/uvicorn tts_server:app --host 0.0.0.0 --port 50021
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now edge-tts-server

修改端口：改 --port 50021 为别的值。

八、功能实操教程

第 1 步：装好 pip install edge-tts，执行：

edge-tts --text "你好，这是 edge-tts 合成的第一段语音。" --voice zh-CN-XiaoxiaoNeural --write-media hello.mp3 --write-subtitles hello.srt

当前目录出现 hello.mp3 与 hello.srt 两个文件，播放 mp3 听到女声朗读、打开 srt 看到带时间轴的字幕即成功。

第 2 步：列出中文音色：

edge-tts --list-voices | grep zh-CN

会看到 zh-CN-XiaoxiaoNeural（晓晓，女）、zh-CN-YunxiNeural（云希，男）、zh-CN-YunjianNeural（云健，体育解说）、zh-CN-XiaoyiNeural（晓伊，女）等。

第 3 步：换男声、加快语速、降低音高：

edge-tts --voice zh-CN-YunxiNeural --rate=+20% --pitch=-5Hz \
  --text "大家好，今天给大家讲一个开源工具的故事。" \
  --write-media narration.mp3

第 4 步：Python API 调用（官方示例模式）：

import asyncio, edge_tts

async def main():
    communicate = edge_tts.Communicate("这是一段 Python 调用的语音。", "zh-CN-XiaoxiaoNeural")
    await communicate.save("py_demo.mp3")

asyncio.run(main())

官方 examples 目录里有 6 个更完整的示例：同步生成、异步生成、流式生成、带字幕的流式、动态选音色等，都可以直接参考。其中最实用的是"流式 + 字幕"组合（官方 examples/sync_audio_streaming_with_predefined_voice_subtitles.py 原文）：

import edge_tts

TEXT = "Hello World!"
VOICE = "en-GB-SoniaNeural"
OUTPUT_FILE = "test.mp3"
SRT_FILE = "test.srt"

communicate = edge_tts.Communicate(TEXT, VOICE)
submaker = edge_tts.SubMaker()
with open(OUTPUT_FILE, "wb") as file:
    for chunk in communicate.stream_sync():
        if chunk["type"] == "audio":
            file.write(chunk["data"])
        elif chunk["type"] in ("WordBoundary", "SentenceBoundary"):
            submaker.feed(chunk)

with open(SRT_FILE, "w", encoding="utf-8") as file:
    file.write(submaker.get_srt())

逐段解释：stream_sync() 是同步版的流式迭代器，每次返回一个 dict：type 为 audio 时 data 是 mp3 二进制块，直接写文件；type 为 WordBoundary 或 SentenceBoundary 时，把 chunk 喂给 SubMaker，它会自动累积每个词的起止时间戳；最后 submaker.get_srt() 返回标准 SRT 字符串。这个模式的好处是：长文本不用等全部合成完再写盘，边接收边落盘，内存占用极小。

第 5 步：批量合成。准备一个 texts.txt，每行一段文本，写个 shell 循环：

while IFS= read -r line; do
  edge-tts --text "$line" --voice zh-CN-XiaoxiaoNeural --write-media "$(echo $line | md5sum | cut -c1-8).mp3"
done < texts.txt

第 6 步：调用自托管 HTTP 服务：

curl -X POST http://localhost:50021/tts -H "Content-Type: application/json" \
  -d '{"text":"通过 HTTP 服务合成","voice":"zh-CN-YunxiNeural"}'

第 7 步：给视频配音实战。假设你有一段旁白 narration.txt，想生成配音 mp3 和字幕 srt：

edge-tts --text "$(cat narration.txt)" \
  --voice zh-CN-XiaoxiaoNeural \
  --rate=+0% \
  --write-media narration.mp3 \
  --write-subtitles narration.srt

然后把 narration.mp3 拖进剪辑软件，narration.srt 作为字幕轨，直接对齐画面。这是自媒体最常用的 edge-tts 工作流。

第 8 步：试听对比音色。用 edge-playback 快速过一遍几个候选音色，不用每次都生成文件：

edge-playback --text "这是一段测试语音，用来试听不同音色。" --voice zh-CN-XiaoxiaoNeural
edge-playback --text "这是一段测试语音，用来试听不同音色。" --voice zh-CN-YunxiNeural
edge-playback --text "这是一段测试语音，用来试听不同音色。" --voice zh-CN-YunjianNeural

九、全套报错故障排查

报错：403 Unauthorized 或 Failed to authenticate。 原因分析：网络无法访问微软 TTS 端点，或微软接口临时封禁了当前 IP。 分步解决方案：检查网络连通性；尝试挂代理；过一会儿重试（接口限流通常是临时的）。
报错：Invalid voice name。 原因分析：--voice 拼错了。 分步解决方案：先跑 edge-tts --list-voices 复制完整音色名，注意大小写和 Neural 后缀。
报错：负参数被当成选项，提示 --rate: no such option。 原因分析：写成了 --rate -50% 而不是 --rate=-50%。 分步解决方案：按官方提示改成 --rate=-50% 形式。
报错：edge-playback 命令找不到 mpv。 原因分析：Linux/macOS 未装 mpv。 分步解决方案：sudo apt install mpv 或 brew install mpv。
报错：输出 mp3 时长明显比文本应有时长短，或中间被截断。 原因分析：网络中断导致音频流没接收完。 分步解决方案：重新执行命令；长文本建议拆成多段分别合成再拼接。
报错：No module named edge_tts。 原因分析：pip 装到了别的 Python 环境，或用 pipx 装但 shell 没刷新 PATH。 分步解决方案：which edge-tts 确认命令位置；pip show edge-tts 确认安装位置；必要时 python -m edge_tts --help 直接用模块方式调。
报错：长文本合成中途断开，mp3 播放到一半就停。 原因分析：单次 WebSocket 连接有时长上限，几千字长文容易被服务端切断。 分步解决方案：把长文本按段落拆成多次调用，每段单独生成一个 mp3，最后用 ffmpeg 合并：ffmpeg -f concat -safe 0 -i list.txt -c copy merged.mp3。
报错：并发调用时多个请求互相阻塞。 原因分析：edge-tts 默认是单连接同步调用，多线程同时用会抢同一条 WebSocket。 分步解决方案：并发场景改用 AsyncCommunicate，每个请求创建独立实例，或在 HTTP 服务里给 Communicate 加队列限流。

十、升级、回滚与卸载

升级：pip install -U edge-tts。edge-tts 更新比较频繁，微软接口偶尔会变，遇到 403 时先升级到最新版往往就能解决——这是官方 issue 区最常见的建议。

备份建议：edge-tts 无本地状态，备份自己写的合成脚本与 HTTP 服务封装即可。

回滚：pip install edge-tts==<旧版本号>。

卸载：pip uninstall edge-tts；pipx 装的用 pipx uninstall edge-tts；HTTP 服务写了 systemd 的，记得 sudo systemctl disable --now edge-tts-server 并删 unit 文件。

十一、商用许可与合规风险提示

代码协议是 LGPLv3——你自己的应用静态链接/修改 edge-tts 库源码时，需要开源你的修改部分；动态调用（命令行、HTTP 调用）不触发开源义务。

但更重要的风险是服务侧：edge-tts 调用的是微软 Edge 浏览器的在线 TTS 端点，这个端点本身并非公开商用 API，微软条款并未授权把它当作商用 TTS 后端使用。个人学习、内部非商用演示、做视频配音自用，风险很低；但如果要把它集成到对外收费的商业产品里（例如给 App 做朗读功能、给客户交付语音），存在被微软封号、接口变更、用户追责的风险，建议改用 Azure 官方 Speech 服务或开源本地模型。本教程不构成法律意见。

参考链接

GitHub 仓库：https://github.com/rany2/edge-tts
PyPI：https://pypi.org/project/edge-tts/
官方 examples：https://github.com/rany2/edge-tts/tree/master/examples

edge-tts 保姆级部署教程：免费调用微软 Edge 神经网络语音合成，Python/CLI/HTTP 服务全流程

edge-tts 保姆级部署教程：免费调用微软 Edge 神经网络语音合成，Python/CLI/HTTP 服务全流程

一、项目介绍与适用场景

二、核心功能逐条拆解

三、全套官方链接

四、硬件与环境前置要求

五、多平台部署步骤

5.1 pip 安装（官方）

5.2 Windows 部署

5.3 验证安装

5.4 Linux / macOS 即时回放（可选）

六、配置文件全部参数解释

七、启动、后台常驻与开机自启

八、功能实操教程

九、全套报错故障排查

十、升级、回滚与卸载

十一、商用许可与合规风险提示

参考链接

周若琳

文章目录