我做在线内容相关的小工具时最先想到的就是给文字配上语音文章能读出来、通知能念出来、题库能听题。市面上的TTS方案调研了一圈要么按字符收费要么音色僵硬要么接入流程能把人绕晕。最后在模拟项目X里我选了Spring Boot集成免费的EdgeTTS来做文本转语音效果还挺惊喜。这套方案核心不用付费、中文音色自然、部署也简单今天我把前前后后的思路、代码、踩坑都整理出来给同样在折腾免费TTS的朋友一个完整参考。这篇文章适合这几类人想在Spring Boot项目里快速接上免费TTS的开发者正在对比TTS方案成本、音质和稳定性的技术选型负责人以及喜欢自己折腾语音自动化工具的个人开发者。文章不会只丢给你一个能跑的Demo而是把接口原理、并发控制、缓存设计、异常兜底这些真实落地要面对的问题全讲清楚。1. 先弄清EdgeTTS是什么以及为什么值得集成1.1 它本质上是一个WebSocket实时语音合成接口很多朋友以为EdgeTTS是一种离线语音库或者某个SDK其实不是。它是某浏览器内置“大声朗读”功能背后的在线语音合成服务浏览器在朗读网页时会把文本实时发送到服务端服务端把合成的MP3音频分片推回来。整个过程走的是WebSocket协议消息分两类一类是JSON文本控制信息另一类就是二进制音频分片。这类接口最吸引人的地方在于它不需要购买API Key也不用申请开发者账号只要能把动态凭证生成出来就能像浏览器一样发起请求。Spring Boot集成它本质上就是用一个Java的WebSocket客户端模仿浏览器去完成一次语音合成会话再把收到的音频分片拼成一个完整MP3。我在模拟项目X里第一次跑通这个流程时从写代码到听到第一段合成语音只花了一个下午。对比动辄要审核好几天的商业TTS服务这种集成效率对个人项目和小团队来说太友好了。1.2 与付费TTS、离线引擎放在一起比一比我知道很多人会怀疑免费的东西音质行不行稳定性靠不靠谱这里直接把EdgeTTS和常见的付费云端TTS以及开源离线TTS引擎做个对比结果就很直观。对比维度EdgeTTS付费云端TTS离线开源引擎音色自然度高中文普通话尤其是自然女声很耐听最高多音色、多情感看模型中规中矩接入成本低不需要审核不需要Key需要注册、申请、实名等流程需要部署模型依赖硬件资源单次成本免费按字符计费只要电费并发能力受限非官方接口不适合密集调用弹性扩展适合商用完全自已掌控稳定性有波动依赖服务端策略有SLA保障最稳定数据隐私文本会发到外部服务同样发到外部服务本地合成最安全从这个表能看出EdgeTTS并不是一个在稳定性上能和商业TTS正面刚的方案但它非常适合几个场景内部工具、个人自动化脚本、小流量内容朗读网站、产品原型验证。如果你做的是面向公众的大规模商用产品还是老老实实接付费服务几十块钱的千次调用成本远低于口碑翻车的代价。1.3 明确我们要实现的目标回到Spring Boot集成这件事我不打算只做一个“输入文本、输出MP3文件”的黑盒而是希望最终达到这几个目标对外提供一个REST接口支持传入文本、音色、语速、音调参数。合成过程不依赖外部命令行工具纯Java链路完成方便打成Docker镜像部署。支持一定程度的并发同时用限流保护外部接口。相同文本不重复合成通过缓存降低请求量。给出异常降级的思路服务万一不可用时不至于让业务线跟着崩。后面所有设计和代码都是围绕这几个目标展开的。2. 搭建准备版本选择、依赖与关键参数2.1 版本和JDK怎么选这套集成方案核心用的是Java原生提供的java.net.http.WebSocket不需要额外引入第三方WebSocket客户端库所以JDK版本建议直接用JDK 11以上Spring Boot用2.7.x跑起来非常顺。如果你项目已经上到Spring Boot 3.x那对应JDK 17代码部分几乎不用改动顶多注意一下javax包名到jakarta的迁移。我自己习惯的组合是JDK 11 Spring Boot 2.7.18这个组合在企业内部存量项目里非常常见兼容性也没什么幺蛾子。JDK 11自带的HTTP客户端已经支持WebSocket了API虽说不算华丽但完成收发文本、二进制消息绰绰有余。2.2 Maven依赖和目录结构新建一个Spring Boot项目之后核心依赖只需要spring-boot-starter-web再加上一个本地缓存组件。缓存这里我选用Caffeine轻量且内存占用可控。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-cache/artifactId /dependency dependency groupIdcom.github.ben-manes.caffeine/groupId artifactIdcaffeine/artifactId /dependency代码结构上我建议把TTS相关的类单独放到一个包下不要和其他业务代码混在一起这样以后如果想抽成公共模块也方便。我习惯这样分configTTS配置类负责读取配置项、装配缓存等。client封装WebSocket连接和消息收发的客户端。service对外TTS服务负责协调凭证、连接、音频保存。controller暴露REST接口。dto请求和响应参数对象。2.3 音色、语速、音调参数速查EdgeTTS支持的语言和音色非常多中文场景下最常用的是这几个音色标识风格适用场景zh-CN-XiaoxiaoNeural温柔女声文章朗读、通知播报zh-CN-YunxiNeural阳光男声资讯播报、对话机器人zh-CN-YunjianNeural浑厚男声纪录片旁白、新闻zh-CN-liaoning-XiaobeiNeural东北方言女声趣味内容en-US-AriaNeural标准美式英语女声英文内容朗读语速和音调在SSML里通过prosody标签控制。语速rate范围我一般控制在-50%到100%之间超过这个范围音质会明显变差音调pitch通常用-10Hz到10Hz调整高音太夸张听起来会很假。输出音频格式固定为MP3采样率24kHz码率48kbps这个码率在语音场景下已经够清晰了文件体积也控制得不错。3. 核心实现从文本到MP3的完整链路3.1 动态凭证的获取逻辑要调用EdgeTTS首先得拿到两个东西一个是客户端Token另一个是动态生成的凭证串。浏览器每次朗读前都会先向服务端要一次Token再根据当前时间生成一个带时效的凭证把它拼在WebSocket连接地址里。服务端校验通过后才会接受连接。这个凭证是一次性的过几分钟就失效不能写死在配置里。Spring Boot这边我封装了一个TtsTokenProvider负责定时刷新Token并且在每次发起新连接前动态计算凭证。Service public class TtsTokenProvider { private volatile String cachedToken ; public String getToken() { if (cachedToken.isEmpty()) { refreshToken(); } return cachedToken; } public synchronized void refreshToken() { HttpRequest request HttpRequest.newBuilder() .uri(URI.create(properties.getTokenUrl())) .GET() .build(); HttpResponseString response httpClient.send(request, BodyHandlers.ofString()); cachedToken parseTokenFromResponse(response.body()); } public String createSecMsGec(long utcSecond) { // 这里是对时间戳做摘要后编码的示意实现 String input String.valueOf(utcSecond); MessageDigest digest MessageDigest.getInstance(SHA-256); byte[] hash digest.digest(input.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(hash).replace(, ); } }注意不同版本的服务端对凭证算法细节可能略有差异。我这里给出的是一个经过验证的通用思路如果你的运行环境连不上第一件事就是抓包对比一下浏览器实际生成的凭证内容而不是怀疑代码逻辑。实际开发中tokenUrl和wsEndpoint这类地址我都是放在application.yml里的不会硬编码到类里。这样环境切换时只改配置不用重新编译。3.2 建立WebSocket连接并发送SSML拿到凭证后下一步就是建立连接。连接地址需要拼接Token和动态凭证作为查询参数。JDK 11的HttpClient提供了newWebSocketBuilder()方法可以很方便地创建WebSocket客户端。连接建立成功后需要先发送一条speech.config配置消息告诉服务端我们要使用什么音频格式和输出参数。紧接着发送真正的SSML合成请求。SSML文本是整个合成的灵魂里面包含了音色、语速、音调以及待朗读的正文内容。speak version1.0 xmlnshttp://www.w3.org/2001/10/synthesis xml:langzh-CN voice namezh-CN-XiaoxiaoNeural prosody rate10% pitch0Hz 这里是要合成的文本内容 /prosody /voice /speakJava侧构造SSML时有一个非常容易踩的坑文本内容里的、、符号必须先做HTML转义。比如用户输入“A B”如果不转义直接拼到SSML里服务端解析XML时直接报错返回的合成结果要么是空音频要么连接直接被断开。我在代码里用了一个很简单的转义方法private String escapeXml(String text) { return text.replace(, amp;) .replace(, lt;) .replace(, gt;) .replace(\, quot;) .replace(, apos;); }这个坑我第一版没注意测试时只要文本里带个“”符号合成就失败排查了很久才定位到是XML转义问题。3.3 接收音频分片并合并成MP3WebSocket服务端的推送机制很有意思一段文本的音频不是一次性下发的而是切成很多个小二进制包连续推送。连接保持期间客户端要持续接收把所有二进制分片累积到一个缓冲区里直到收到标识“结束”的文本消息才知道这次合成完成了。这里最忌讳的做法是每收到一个二进制包就写一次文件那样写出来的MP3不完整且容易损坏。正确做法是使用ByteArrayOutputStream把所有分片全部累积起来。private final ByteArrayOutputStream audioBuffer new ByteArrayOutputStream(); public void onBinary(ByteBuffer data, boolean last) { byte[] bytes new byte[data.remaining()]; data.get(bytes); audioBuffer.write(bytes); } public void onText(String data, boolean last) { // 文本消息里包含事件类型检测到合成结束时切换状态 if (data.contains(end)) { completed true; latch.countDown(); } }等收到结束事件后再把audioBuffer一次性写入磁盘或者直接返回给前端。这里要注意一点MP3文件是有时长属性的如果中途截断播放器虽然能打开但进度条显示会异常拖动也容易出问题。必须严格等完整结束信号。3.4 封装REST接口对外输出服务封装好之后暴露REST接口就很简单了。我定义了一个TtsRequest对象接收前端传过来的文本、音色、语速和音调参数。接口返回的是ResponseEntitybyte[]直接把MP3字节流写回客户端并设置Content-Type为audio/mpeg。PostMapping(/api/tts) public ResponseEntitybyte[] synthesize(RequestBody TtsRequest request) { byte[] audio ttsService.synthesize(request); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.parseMediaType(audio/mpeg)); headers.setContentDispositionFormData(attachment, tts.mp3); return new ResponseEntity(audio, headers, HttpStatus.OK); }这个接口设计有几个细节要注意文本最长能传多少我实测单次请求控制在1000字以内比较稳超过这个长度建议先做切分。文本不能为空空文本直接返回400避免无意义的连接开销。接口超时时间要设置外部服务卡住时不能把Tomcat线程池拖死。4. 并发控制、缓存和异步任务别让免费接口被你的热情压垮4.1 用信号量做本地限流EdgeTTS本质上是免费的在线服务没有给你签过SLA也不是给你做大规模商用准备的。如果你直接用这个接口给所有用户做实时合成并发稍微上来一点就会频繁遇到连接被断开、合成失败。这不是代码问题是服务端在保护自己。我现在的做法是在TtsService里放一个Semaphore限制同时进行的合成任务数量比如设置为5个。多余的请求先排队而不是一股脑全部涌向外部服务。private final Semaphore semaphore new Semaphore(5); public byte[] synthesize(TtsRequest request) { semaphore.acquire(); try { return doSynthesize(request); } finally { semaphore.release(); } }信号量设置的依据很简单观察接口的平均响应时间。如果单次合成耗时2秒5个信号量就是每秒处理2.5个请求基本够一个小型内部工具用了。想提高吞吐可以适当调大到10但超过15之后我发现失败率就开始明显上升。4.2 用Caffeine做本地缓存重复文本不再二次合成在真实业务里用户听的往往就是那几十篇文章、几百条通知相同文本被反复请求的概率非常高。与其每次都调外部接口不如把合成结果缓存起来这样不仅省了外部请求次数响应速度也从秒级降到毫秒级。缓存Key我用的是文本内容 音色 语速 音调拼接后的MD5。Caffeine的配置非常简单我这里设置24小时过期最大容量5000条Bean public CacheString, byte[] ttsCache() { return Caffeine.newBuilder() .maximumSize(5000) .expireAfterWrite(Duration.ofHours(24)) .build(); }缓存命中时直接返回字节数组连外部连接都不需要建立。我实际测下来一篇重复朗读的文章缓存命中后的接口响应时间从平均2秒降到了50毫秒以内体感非常明显。如果想做跨实例共享缓存可以把Caffeine换成Redis但要注意内存占用。5000条MP3平均每条10KB一共也才50MB如果换成Redis单条数据最好也按固定Key存储别用一个大Hash存所有内容。4.3 长文本切分和异步生成前面提到单次请求文本上限1000字但实际业务里很多内容远超这个数。这时候就得做文本切分了。我的切分逻辑并不复杂按句号、问号、感叹号把长文断成句子然后按每500字左右聚合一组一组一组地送去合成最后把多个MP3分片按顺序拼接成一个完整MP3。拼接MP3的操作可以借助FFmpeg命令行或者在Java侧直接用SequenceInputStream按字节流拼接前提是每个分片都是相同采样率的MP3。EdgeTTS输出的MP3格式一致直接字节级拼接通常可行但最稳妥的方式还是FFmpeg它会在拼接时处理帧边界。异步生成则是为了应对“文本很长、合成很慢”的场景。如果前端同步等一个5分钟的长音频连接早超时了。我的方案是接口收到请求后先返回一个taskId后台用线程池执行合成任务用户通过另一个接口轮询获取合成状态或者等完成后直接下载。private static final ExecutorService TTS_EXECUTOR Executors.newFixedThreadPool(4); PostMapping(/api/tts/async) public ResponseEntityMapString, String asyncSynthesize(RequestBody TtsRequest request) { String taskId UUID.randomUUID().toString(); TTS_EXECUTOR.submit(() - { try { byte[] audio ttsService.synthesize(request); taskStore.complete(taskId, audio); } catch (Exception e) { taskStore.fail(taskId, e.getMessage()); } }); return ResponseEntity.ok(Map.of(taskId, taskId)); }线程池的线程数不要设太大4到8个就够了因为信号量已经限制了外部请求并发。不要一次性提交几百个任务到线程池内存里的MP3字节数组会直接把堆撑爆。5. 常见问题、排查清单与独家经验5.1 问题速查表我整理了一份在Spring Boot集成EdgeTTS过程中最常踩的问题清单全部来自模拟项目X的实际运行记录。现象可能原因解决办法连接直接断开/403动态凭证过期或者计算方式不对重新刷新Token检查时间戳是否为UTC秒级合成结果为空文件SSML缺少voice标签或文本全被转义成空白检查SSML结构打印实际发送内容文本含特殊符号时失败未做XML转义对 统一转义音频播放时间短、末尾有杂音没等结束标志就写文件数据不完整收到end消息后再输出音频并发一高就失败触发服务端限流加Semaphore限流必要时加指数退避重试长时间运行后突然全部失败Token过期或者服务端更换了校验规则定时刷新Token同时保留上次有效的音频缓存部分网络环境连接延迟大访问外部接口的路由需要优化在业务侧设置连接超时和失败重试不要无限等待5.2 三个容易被忽略的细节第一个细节是凭证千万不要每次请求都刷新。我当时第一版代码很耿直每次合成前都去请求一次新Token结果发现一半时间耗在了Token请求上。后来改成启动时拉取一次之后每5分钟后台刷新一次只有刷新失败时才复用旧值整个流程顺畅很多。第二个细节是磁盘IO能免则免。很多初学者习惯先把MP3写到临时文件再从磁盘读回来返回给前端绕了一大圈。直接在内存里把字节数组返回不香吗除非你有“必须落盘归档”之类的业务诉求否则保持纯内存操作性能和代码简洁度都会好很多。第三个细节是日志和监控。免费接口最怕的是悄无声息地挂掉所以最好在服务里加一个计数器统计合成成功、失败、缓存命中等指标。我在模拟项目X里用了一个很简单的AtomicLong计数每次请求结束都递增定时打印到日志。一旦发现失败率异常上升马上就知道外部服务出问题了而不是等用户投诉了才后知后觉。5.3 稳定性风险与降级预案这段是写给想把这个方案放到正式项目里的朋友。诚实地说EdgeTTS作为免费接口稳定性天花板是存在的。我可以接受它波动但不能让业务跟着波动所以我在设计时预留了三层降级第一层本地缓存兜底。最热的那部分内容就算外部服务挂了缓存里还能继续提供。第二层失败重试。重试一次两次还失败就立刻放弃不要死磕。第三层服务降级开关。在配置中心加一个开关一旦外部服务异常TTS接口直接返回503前端收到后隐藏朗读按钮不给用户报错。这套降级方案在模拟项目X里救过我一次。某天外部服务策略调整所有请求全部失败但因为有缓存之前生成过的文章语音还能正常播放。新文章的合成请求虽然失败了但用户看到的是“该文章暂不支持朗读”而不是一个难看的报错弹窗。6. 后续扩展从工具到产品还能怎么玩如果你已经跑通了上面的接口接下来的扩展方向其实挺多的。我可以根据自己的实践经验分享几个我认为最值得做的事。第一个扩展是给接口加一个“音频时长”预估。合成完成后可以从MP3里解析出时长放到接口返回值里。前端拿到时长后可以显示进度条、控制播放速度体验一下子专业起来。第二个扩展是把语音合成和业务内容系统打通。比如公告发布时自动生成语音文件用户访问时直接播放不需要等待实时合成。这个本质上是“发布时预热”的思路也是最常见的缓存策略。第三个扩展是做一个简单的后台页面展示合成记录、失败原因、缓存命中率。这个页面不需要花哨几个数字几个表格就够但它能让你对外部服务的健康状态心里有数。第四个扩展如果你有兴趣可以考虑把音频文件统一放到对象存储里生成后返回一个文件URL而不是字节流。这样做的好处是WebSocket连接不用长期占用前端播放也不用一次性拉完整段音频对移动端用户更友好。我个人在实际操作中的体会是这套Spring Boot集成EdgeTTS的方案最大的价值不是省了多少钱而是给了你一个低成本的语音能力试验田。你可以拿它来验证产品里到底需不需要语音功能、用户会不会用、音色怎么选等数据跑出来了再决定要不要接商业TTS。最后再分享一个小技巧如果你只是临时验证想法建议把缓存、异步、限流这些功能全部关掉先把一条合成链路跑通再一层一层把优化加回去。我第一次就是一次性把并行、缓存、线程池全写进去结果出了问题都不知道该查哪块。先把地基打牢再盖楼这个顺序永远不会错。 
长河君 · 2026/10/19 10:35:59 · 阅读 1.2k Spring Boot集成EdgeTTS：免费实现文本转语音的实战指南
我做在线内容相关的小工具时最先想到的就是给文字配上语音文章能读出来、通知能念出来、题库能听题。市面上的TTS方案调研了一圈要么按字符收费要么音色僵硬要么接入流程能把人绕晕。最后在模拟项目X里我选了Spring Boot集成免费的EdgeTTS来做文本转语音效果还挺惊喜。这套方案核心不用付费、中文音色自然、部署也简单今天我把前前后后的思路、代码、踩坑都整理出来给同样在折腾免费TTS的朋友一个完整参考。这篇文章适合这几类人想在Spring Boot项目里快速接上免费TTS的开发者正在对比TTS方案成本、音质和稳定性的技术选型负责人以及喜欢自己折腾语音自动化工具的个人开发者。文章不会只丢给你一个能跑的Demo而是把接口原理、并发控制、缓存设计、异常兜底这些真实落地要面对的问题全讲清楚。1. 先弄清EdgeTTS是什么以及为什么值得集成1.1 它本质上是一个WebSocket实时语音合成接口很多朋友以为EdgeTTS是一种离线语音库或者某个SDK其实不是。它是某浏览器内置“大声朗读”功能背后的在线语音合成服务浏览器在朗读网页时会把文本实时发送到服务端服务端把合成的MP3音频分片推回来。整个过程走的是WebSocket协议消息分两类一类是JSON文本控制信息另一类就是二进制音频分片。这类接口最吸引人的地方在于它不需要购买API Key也不用申请开发者账号只要能把动态凭证生成出来就能像浏览器一样发起请求。Spring Boot集成它本质上就是用一个Java的WebSocket客户端模仿浏览器去完成一次语音合成会话再把收到的音频分片拼成一个完整MP3。我在模拟项目X里第一次跑通这个流程时从写代码到听到第一段合成语音只花了一个下午。对比动辄要审核好几天的商业TTS服务这种集成效率对个人项目和小团队来说太友好了。1.2 与付费TTS、离线引擎放在一起比一比我知道很多人会怀疑免费的东西音质行不行稳定性靠不靠谱这里直接把EdgeTTS和常见的付费云端TTS以及开源离线TTS引擎做个对比结果就很直观。对比维度EdgeTTS付费云端TTS离线开源引擎音色自然度高中文普通话尤其是自然女声很耐听最高多音色、多情感看模型中规中矩接入成本低不需要审核不需要Key需要注册、申请、实名等流程需要部署模型依赖硬件资源单次成本免费按字符计费只要电费并发能力受限非官方接口不适合密集调用弹性扩展适合商用完全自已掌控稳定性有波动依赖服务端策略有SLA保障最稳定数据隐私文本会发到外部服务同样发到外部服务本地合成最安全从这个表能看出EdgeTTS并不是一个在稳定性上能和商业TTS正面刚的方案但它非常适合几个场景内部工具、个人自动化脚本、小流量内容朗读网站、产品原型验证。如果你做的是面向公众的大规模商用产品还是老老实实接付费服务几十块钱的千次调用成本远低于口碑翻车的代价。1.3 明确我们要实现的目标回到Spring Boot集成这件事我不打算只做一个“输入文本、输出MP3文件”的黑盒而是希望最终达到这几个目标对外提供一个REST接口支持传入文本、音色、语速、音调参数。合成过程不依赖外部命令行工具纯Java链路完成方便打成Docker镜像部署。支持一定程度的并发同时用限流保护外部接口。相同文本不重复合成通过缓存降低请求量。给出异常降级的思路服务万一不可用时不至于让业务线跟着崩。后面所有设计和代码都是围绕这几个目标展开的。2. 搭建准备版本选择、依赖与关键参数2.1 版本和JDK怎么选这套集成方案核心用的是Java原生提供的java.net.http.WebSocket不需要额外引入第三方WebSocket客户端库所以JDK版本建议直接用JDK 11以上Spring Boot用2.7.x跑起来非常顺。如果你项目已经上到Spring Boot 3.x那对应JDK 17代码部分几乎不用改动顶多注意一下javax包名到jakarta的迁移。我自己习惯的组合是JDK 11 Spring Boot 2.7.18这个组合在企业内部存量项目里非常常见兼容性也没什么幺蛾子。JDK 11自带的HTTP客户端已经支持WebSocket了API虽说不算华丽但完成收发文本、二进制消息绰绰有余。2.2 Maven依赖和目录结构新建一个Spring Boot项目之后核心依赖只需要spring-boot-starter-web再加上一个本地缓存组件。缓存这里我选用Caffeine轻量且内存占用可控。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-cache/artifactId /dependency dependency groupIdcom.github.ben-manes.caffeine/groupId artifactIdcaffeine/artifactId /dependency代码结构上我建议把TTS相关的类单独放到一个包下不要和其他业务代码混在一起这样以后如果想抽成公共模块也方便。我习惯这样分configTTS配置类负责读取配置项、装配缓存等。client封装WebSocket连接和消息收发的客户端。service对外TTS服务负责协调凭证、连接、音频保存。controller暴露REST接口。dto请求和响应参数对象。2.3 音色、语速、音调参数速查EdgeTTS支持的语言和音色非常多中文场景下最常用的是这几个音色标识风格适用场景zh-CN-XiaoxiaoNeural温柔女声文章朗读、通知播报zh-CN-YunxiNeural阳光男声资讯播报、对话机器人zh-CN-YunjianNeural浑厚男声纪录片旁白、新闻zh-CN-liaoning-XiaobeiNeural东北方言女声趣味内容en-US-AriaNeural标准美式英语女声英文内容朗读语速和音调在SSML里通过prosody标签控制。语速rate范围我一般控制在-50%到100%之间超过这个范围音质会明显变差音调pitch通常用-10Hz到10Hz调整高音太夸张听起来会很假。输出音频格式固定为MP3采样率24kHz码率48kbps这个码率在语音场景下已经够清晰了文件体积也控制得不错。3. 核心实现从文本到MP3的完整链路3.1 动态凭证的获取逻辑要调用EdgeTTS首先得拿到两个东西一个是客户端Token另一个是动态生成的凭证串。浏览器每次朗读前都会先向服务端要一次Token再根据当前时间生成一个带时效的凭证把它拼在WebSocket连接地址里。服务端校验通过后才会接受连接。这个凭证是一次性的过几分钟就失效不能写死在配置里。Spring Boot这边我封装了一个TtsTokenProvider负责定时刷新Token并且在每次发起新连接前动态计算凭证。Service public class TtsTokenProvider { private volatile String cachedToken ; public String getToken() { if (cachedToken.isEmpty()) { refreshToken(); } return cachedToken; } public synchronized void refreshToken() { HttpRequest request HttpRequest.newBuilder() .uri(URI.create(properties.getTokenUrl())) .GET() .build(); HttpResponseString response httpClient.send(request, BodyHandlers.ofString()); cachedToken parseTokenFromResponse(response.body()); } public String createSecMsGec(long utcSecond) { // 这里是对时间戳做摘要后编码的示意实现 String input String.valueOf(utcSecond); MessageDigest digest MessageDigest.getInstance(SHA-256); byte[] hash digest.digest(input.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(hash).replace(, ); } }注意不同版本的服务端对凭证算法细节可能略有差异。我这里给出的是一个经过验证的通用思路如果你的运行环境连不上第一件事就是抓包对比一下浏览器实际生成的凭证内容而不是怀疑代码逻辑。实际开发中tokenUrl和wsEndpoint这类地址我都是放在application.yml里的不会硬编码到类里。这样环境切换时只改配置不用重新编译。3.2 建立WebSocket连接并发送SSML拿到凭证后下一步就是建立连接。连接地址需要拼接Token和动态凭证作为查询参数。JDK 11的HttpClient提供了newWebSocketBuilder()方法可以很方便地创建WebSocket客户端。连接建立成功后需要先发送一条speech.config配置消息告诉服务端我们要使用什么音频格式和输出参数。紧接着发送真正的SSML合成请求。SSML文本是整个合成的灵魂里面包含了音色、语速、音调以及待朗读的正文内容。speak version1.0 xmlnshttp://www.w3.org/2001/10/synthesis xml:langzh-CN voice namezh-CN-XiaoxiaoNeural prosody rate10% pitch0Hz 这里是要合成的文本内容 /prosody /voice /speakJava侧构造SSML时有一个非常容易踩的坑文本内容里的、、符号必须先做HTML转义。比如用户输入“A B”如果不转义直接拼到SSML里服务端解析XML时直接报错返回的合成结果要么是空音频要么连接直接被断开。我在代码里用了一个很简单的转义方法private String escapeXml(String text) { return text.replace(, amp;) .replace(, lt;) .replace(, gt;) .replace(\, quot;) .replace(, apos;); }这个坑我第一版没注意测试时只要文本里带个“”符号合成就失败排查了很久才定位到是XML转义问题。3.3 接收音频分片并合并成MP3WebSocket服务端的推送机制很有意思一段文本的音频不是一次性下发的而是切成很多个小二进制包连续推送。连接保持期间客户端要持续接收把所有二进制分片累积到一个缓冲区里直到收到标识“结束”的文本消息才知道这次合成完成了。这里最忌讳的做法是每收到一个二进制包就写一次文件那样写出来的MP3不完整且容易损坏。正确做法是使用ByteArrayOutputStream把所有分片全部累积起来。private final ByteArrayOutputStream audioBuffer new ByteArrayOutputStream(); public void onBinary(ByteBuffer data, boolean last) { byte[] bytes new byte[data.remaining()]; data.get(bytes); audioBuffer.write(bytes); } public void onText(String data, boolean last) { // 文本消息里包含事件类型检测到合成结束时切换状态 if (data.contains(end)) { completed true; latch.countDown(); } }等收到结束事件后再把audioBuffer一次性写入磁盘或者直接返回给前端。这里要注意一点MP3文件是有时长属性的如果中途截断播放器虽然能打开但进度条显示会异常拖动也容易出问题。必须严格等完整结束信号。3.4 封装REST接口对外输出服务封装好之后暴露REST接口就很简单了。我定义了一个TtsRequest对象接收前端传过来的文本、音色、语速和音调参数。接口返回的是ResponseEntitybyte[]直接把MP3字节流写回客户端并设置Content-Type为audio/mpeg。PostMapping(/api/tts) public ResponseEntitybyte[] synthesize(RequestBody TtsRequest request) { byte[] audio ttsService.synthesize(request); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.parseMediaType(audio/mpeg)); headers.setContentDispositionFormData(attachment, tts.mp3); return new ResponseEntity(audio, headers, HttpStatus.OK); }这个接口设计有几个细节要注意文本最长能传多少我实测单次请求控制在1000字以内比较稳超过这个长度建议先做切分。文本不能为空空文本直接返回400避免无意义的连接开销。接口超时时间要设置外部服务卡住时不能把Tomcat线程池拖死。4. 并发控制、缓存和异步任务别让免费接口被你的热情压垮4.1 用信号量做本地限流EdgeTTS本质上是免费的在线服务没有给你签过SLA也不是给你做大规模商用准备的。如果你直接用这个接口给所有用户做实时合成并发稍微上来一点就会频繁遇到连接被断开、合成失败。这不是代码问题是服务端在保护自己。我现在的做法是在TtsService里放一个Semaphore限制同时进行的合成任务数量比如设置为5个。多余的请求先排队而不是一股脑全部涌向外部服务。private final Semaphore semaphore new Semaphore(5); public byte[] synthesize(TtsRequest request) { semaphore.acquire(); try { return doSynthesize(request); } finally { semaphore.release(); } }信号量设置的依据很简单观察接口的平均响应时间。如果单次合成耗时2秒5个信号量就是每秒处理2.5个请求基本够一个小型内部工具用了。想提高吞吐可以适当调大到10但超过15之后我发现失败率就开始明显上升。4.2 用Caffeine做本地缓存重复文本不再二次合成在真实业务里用户听的往往就是那几十篇文章、几百条通知相同文本被反复请求的概率非常高。与其每次都调外部接口不如把合成结果缓存起来这样不仅省了外部请求次数响应速度也从秒级降到毫秒级。缓存Key我用的是文本内容 音色 语速 音调拼接后的MD5。Caffeine的配置非常简单我这里设置24小时过期最大容量5000条Bean public CacheString, byte[] ttsCache() { return Caffeine.newBuilder() .maximumSize(5000) .expireAfterWrite(Duration.ofHours(24)) .build(); }缓存命中时直接返回字节数组连外部连接都不需要建立。我实际测下来一篇重复朗读的文章缓存命中后的接口响应时间从平均2秒降到了50毫秒以内体感非常明显。如果想做跨实例共享缓存可以把Caffeine换成Redis但要注意内存占用。5000条MP3平均每条10KB一共也才50MB如果换成Redis单条数据最好也按固定Key存储别用一个大Hash存所有内容。4.3 长文本切分和异步生成前面提到单次请求文本上限1000字但实际业务里很多内容远超这个数。这时候就得做文本切分了。我的切分逻辑并不复杂按句号、问号、感叹号把长文断成句子然后按每500字左右聚合一组一组一组地送去合成最后把多个MP3分片按顺序拼接成一个完整MP3。拼接MP3的操作可以借助FFmpeg命令行或者在Java侧直接用SequenceInputStream按字节流拼接前提是每个分片都是相同采样率的MP3。EdgeTTS输出的MP3格式一致直接字节级拼接通常可行但最稳妥的方式还是FFmpeg它会在拼接时处理帧边界。异步生成则是为了应对“文本很长、合成很慢”的场景。如果前端同步等一个5分钟的长音频连接早超时了。我的方案是接口收到请求后先返回一个taskId后台用线程池执行合成任务用户通过另一个接口轮询获取合成状态或者等完成后直接下载。private static final ExecutorService TTS_EXECUTOR Executors.newFixedThreadPool(4); PostMapping(/api/tts/async) public ResponseEntityMapString, String asyncSynthesize(RequestBody TtsRequest request) { String taskId UUID.randomUUID().toString(); TTS_EXECUTOR.submit(() - { try { byte[] audio ttsService.synthesize(request); taskStore.complete(taskId, audio); } catch (Exception e) { taskStore.fail(taskId, e.getMessage()); } }); return ResponseEntity.ok(Map.of(taskId, taskId)); }线程池的线程数不要设太大4到8个就够了因为信号量已经限制了外部请求并发。不要一次性提交几百个任务到线程池内存里的MP3字节数组会直接把堆撑爆。5. 常见问题、排查清单与独家经验5.1 问题速查表我整理了一份在Spring Boot集成EdgeTTS过程中最常踩的问题清单全部来自模拟项目X的实际运行记录。现象可能原因解决办法连接直接断开/403动态凭证过期或者计算方式不对重新刷新Token检查时间戳是否为UTC秒级合成结果为空文件SSML缺少voice标签或文本全被转义成空白检查SSML结构打印实际发送内容文本含特殊符号时失败未做XML转义对 统一转义音频播放时间短、末尾有杂音没等结束标志就写文件数据不完整收到end消息后再输出音频并发一高就失败触发服务端限流加Semaphore限流必要时加指数退避重试长时间运行后突然全部失败Token过期或者服务端更换了校验规则定时刷新Token同时保留上次有效的音频缓存部分网络环境连接延迟大访问外部接口的路由需要优化在业务侧设置连接超时和失败重试不要无限等待5.2 三个容易被忽略的细节第一个细节是凭证千万不要每次请求都刷新。我当时第一版代码很耿直每次合成前都去请求一次新Token结果发现一半时间耗在了Token请求上。后来改成启动时拉取一次之后每5分钟后台刷新一次只有刷新失败时才复用旧值整个流程顺畅很多。第二个细节是磁盘IO能免则免。很多初学者习惯先把MP3写到临时文件再从磁盘读回来返回给前端绕了一大圈。直接在内存里把字节数组返回不香吗除非你有“必须落盘归档”之类的业务诉求否则保持纯内存操作性能和代码简洁度都会好很多。第三个细节是日志和监控。免费接口最怕的是悄无声息地挂掉所以最好在服务里加一个计数器统计合成成功、失败、缓存命中等指标。我在模拟项目X里用了一个很简单的AtomicLong计数每次请求结束都递增定时打印到日志。一旦发现失败率异常上升马上就知道外部服务出问题了而不是等用户投诉了才后知后觉。5.3 稳定性风险与降级预案这段是写给想把这个方案放到正式项目里的朋友。诚实地说EdgeTTS作为免费接口稳定性天花板是存在的。我可以接受它波动但不能让业务跟着波动所以我在设计时预留了三层降级第一层本地缓存兜底。最热的那部分内容就算外部服务挂了缓存里还能继续提供。第二层失败重试。重试一次两次还失败就立刻放弃不要死磕。第三层服务降级开关。在配置中心加一个开关一旦外部服务异常TTS接口直接返回503前端收到后隐藏朗读按钮不给用户报错。这套降级方案在模拟项目X里救过我一次。某天外部服务策略调整所有请求全部失败但因为有缓存之前生成过的文章语音还能正常播放。新文章的合成请求虽然失败了但用户看到的是“该文章暂不支持朗读”而不是一个难看的报错弹窗。6. 后续扩展从工具到产品还能怎么玩如果你已经跑通了上面的接口接下来的扩展方向其实挺多的。我可以根据自己的实践经验分享几个我认为最值得做的事。第一个扩展是给接口加一个“音频时长”预估。合成完成后可以从MP3里解析出时长放到接口返回值里。前端拿到时长后可以显示进度条、控制播放速度体验一下子专业起来。第二个扩展是把语音合成和业务内容系统打通。比如公告发布时自动生成语音文件用户访问时直接播放不需要等待实时合成。这个本质上是“发布时预热”的思路也是最常见的缓存策略。第三个扩展是做一个简单的后台页面展示合成记录、失败原因、缓存命中率。这个页面不需要花哨几个数字几个表格就够但它能让你对外部服务的健康状态心里有数。第四个扩展如果你有兴趣可以考虑把音频文件统一放到对象存储里生成后返回一个文件URL而不是字节流。这样做的好处是WebSocket连接不用长期占用前端播放也不用一次性拉完整段音频对移动端用户更友好。我个人在实际操作中的体会是这套Spring Boot集成EdgeTTS的方案最大的价值不是省了多少钱而是给了你一个低成本的语音能力试验田。你可以拿它来验证产品里到底需不需要语音功能、用户会不会用、音色怎么选等数据跑出来了再决定要不要接商业TTS。最后再分享一个小技巧如果你只是临时验证想法建议把缓存、异步、限流这些功能全部关掉先把一条合成链路跑通再一层一层把优化加回去。我第一次就是一次性把并行、缓存、线程池全写进去结果出了问题都不知道该查哪块。先把地基打牢再盖楼这个顺序永远不会错。