企业官网建设流程全解析

前段时间接了个内部小需求：把一批运营文档批量转成音频，方便同事通勤路上听。我第一反应是看云厂商的文本转语音接口，结果一算账单，每天几百次要合成的内容，按字符计费一个月的成本足够买好几杯奶茶了。后来调研了一圈，发现 EdgeTTS 这个方案——不需要 API Key、不按字符扣费、音质还过得去，而且能直接在 Spring Boot 里集成成内部接口。这篇文章就从原理到代码，把我在项目里真实跑通的集成过程完整拆给你。适合已经会 Spring Boot 基础开发、想在项目里低成本实现 TTS 的读者，你先把思路理清，再照着代码抄就行。

1. 为什么是 EdgeTTS：免费额度与商用方案的取舍

1.1 先算一笔账：商用 TTS 的账单长什么样

做技术选型最忌讳只看功能不看成本。文本转语音这个能力，市面上的商用方案通常是按字符或者按请求次数计费。以常见的云厂商长文本语音合成为例，接口价格大致在每千字符几毛到几块钱区间，再加上调用次数、并发资源、存储和带宽，一个每天调用几千次的内部应用，月度成本很容易做到几十甚至上百元。对于公司系统来说这钱不多，但对于个人项目、内部小工具或者原型演示，这笔开销就很没必要了。

也有几家主流的语音平台提供免费试用包，但免费额度通常有有效期，而且限制音色、限制并发，甚至限制合成的文本长度。等到试用期一过，价格恢复原样，项目还得重新做一轮改造，这种隐性成本很少有人提前算进去。

1.2 EdgeTTS 到底免在哪里

EdgeTTS 听起来像官方 SDK，其实不是。它是微软 Edge 浏览器“大声朗读”功能背后使用的一个在线语音合成服务，底层走的是 WebSocket 协议。浏览器点击“朗读”按钮时，前端会把文本和 voice 参数发给微软的语音服务，服务端合成好 MP3 音频流再推回来。

这套体系没有对第三方开放正式的计费通道，协议本身也没有 API Key 这种鉴权方式，而是靠客户端生成的一个动态 token 放进请求头里。所以你可以绕开付费 API，直接通过协议调用的方式拿到语音合成结果，本质上就是在模拟浏览器朗读的那一次网络请求。

这里必须说清楚：它不是官方承诺给开发者长期免费使用的接口，没有 SLA，服务条款里也未必允许你大规模商用。所以我把它的定位放在“低成本、内部使用、非关键链路”这个区间，用来做内部工具和原型验证非常香，但如果要做对外商业化产品，还是老老实实用有授权的语音合成服务。

1.3 什么场景适合用，什么场景千万别用

我在决定用它之前列了一张判断表，你可以直接参考：

这个判断是实践里最重要的部分。技术实现本身不难，难的是搞清楚它应该在什么位置使用。我的经验是：凡是内部工具、低频调用、不依赖它赚钱的系统，闭眼用；凡是面向用户、对外承诺可用性的链路，换方案。

2. EdgeTTS 的请求原理与音频格式要点

2.1 一句话说清它的“协议”

表面看是文本转语音，本质上是 WebSocket 长连接会话。客户端连上微软语音服务的 WebSocket 端点后，按顺序发送两类消息：

• 第一条是speech.config，告诉服务端我要什么输出格式。
• 第二条是ssml消息，携带要合成的文本、音色、语速、音调。
• 之后服务端会持续推送音频二进制数据帧，推送结束时会发一条包含Path:turn.end的文本消息。

你可以把它理解成一个不断收发消息的聊天室，只不过其中一类消息是连续的音频字节流。客户端要做的就是从二进制消息里把音频数据抠出来，拼成一个完整的 MP3 文件。

这个协议本身不复杂，很多语言都有参考实现。用 Java 写的时候不需要造轮子，直接用一个成熟的 WebSocket 客户端库即可，核心就是拼消息、收消息、拼字节。

2.2 音频格式和码率怎么选

合成请求里有个关键参数叫 outputFormat，决定服务端返回什么格式的音频。我实测常用的几个如下：

选用默认的 MP3 格式就是因为它紧凑。48kbps 的码率换算下来大约是每秒 6KB 数据量，三分钟的语音合成结果也就 1MB 多，存数据库、做缓存、走 HTTP 返回都很轻量。

这里有个容易被忽略的点：如果你拿到的是 PCM 格式，后续要自己负责转码；而 EdgeTTS 默认返回的 MP3 已经是编码完成的成品，直接播放没问题。我的建议是没特殊需求就保持默认，不要为了“原始数据”这种执念去选 PCM，徒增转码工作量。

2.3 voice 参数、语速和音调怎么控制

音频格式只是一部分，真正决定听感的是 voice 和 prosody 参数。EdgeTTS 支持的语言和音色非常多，我日常用的中文音色有这些：

• zh-CN-XiaoxiaoNeural：晓晓，女声，自然清晰，通用场景首选
• zh-CN-YunxiNeural：云希，男声，叙事感强，适合解说类内容
• zh-CN-YunyangNeural：云扬，男声，有新闻播报感
• zh-CN-XiaoyiNeural：晓伊，女声，偏年轻活泼
• zh-CN-liaoning-XiaobeiNeural：晓北，东北口音女声，做搞怪内容时会用

语速、音调、音量通过 SSML 里的<prosody>标签控制。例如把语速调快 10%、音调升高 2Hz、音量提高 10%，措辞是这样：

<prosody rate="+10%" pitch="+2Hz" volume="+10%">要合成的文字</prosody>

这三个参数都有合法范围，rate 一般支持 -50% 到 +100%，pitch 用 Hz 表示，volume 用百分比。实际测试下来，rate 调到 +20% 以上听起来会明显发飘，建议日常控制在 ±10% 以内。

3. Spring Boot 集成实操：从依赖到对外接口

3.1 工程结构与 Maven 依赖

先明确项目基础配置：Spring Boot 3.x，Java 21，构建工具用 Maven。WebSocket 客户端我选的是Java-WebSocket这个库，不用 Spring 自带 WebSocket 原因是这里只需要充当客户端，Java-WebSocket 的 API 更直接，断线重连、消息回调都好控制。

pom.xml 里添加依赖：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.java-websocket</groupId> <artifactId>Java-WebSocket</artifactId> <version>1.5.7</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency>

如果你不想用 Lombok，后面的示例代码里把@Slf4j换成手动 logger 就行。核心包就这三个，不需要额外的 TTS SDK。

3.2 生成 Sec-MS-GEC：请求头里的“动态令牌”

EdgeTTS 请求头里有两个关键字段，一个是固定的TrustedClientToken，另一个是每次请求需要动态计算的Sec-MS-GEC。后者是 Edge 浏览器用来做客户端校验的临时令牌。它的生成逻辑并不复杂：取当前时间加上 5 分钟后的 Unix 时间戳，转成字符串，和一个固定值拼接后做 SHA256 哈希，再对哈希结果做 Base64 URL 编码。

下面这个工具类就是干这个事的：

public class EdgeAuth { private static final String TRUSTED_CLIENT_TOKEN = "6A9B..."; // 固定值，来自社区公开实现 private static final String WSS_URL = "wss://speech.platform.bing.com/consumer/speech/synthesize/readaloud/edge/v1?" + "TrustedClientToken=" + TRUSTED_CLIENT_TOKEN + "&ConnectionId=" + UUID.randomUUID(); public static String getWssUrl() { return WSS_URL; } public static String generateSecMsGec() { long timestamp = System.currentTimeMillis() / 1000 + 300; String input = timestamp + "6A9B..."; // 与 TrustedClientToken 关联的固定值 try { MessageDigest digest = MessageDigest.getInstance("SHA-256"); byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8)); return Base64.getUrlEncoder().withoutPadding().encodeToString(hash); } catch (NoSuchAlgorithmException e) { throw new IllegalStateException(e); } } }

这里有两个很实际的注意点。第一，TrustedClientToken不是我自己发明的，它来自社区对 Edge 协议的逆向分析，是一段公开的固定常量。如果你以后遇到请求返回 403，优先去最新的开源实现里同步这个值。第二，Sec-MS-GEC有一定时效性，有效期大约是 5 到 10 分钟，所以不要每个合成请求都重新生成一次，缓存起来才是理性做法，这一点我在第 4 节单独说。

3.3 核心合成器的完整封装

核心类是一个负责“建立连接、发配置、发 SSML、收音频、返回字节数组”的组件。我把它做成 Spring 的@Component，方便后面直接用依赖注入。

需要处理的逻辑分五步：

1. 构建 WSS URL，带上TrustedClientToken和随机ConnectionId。
2. 建立 WebSocket 连接，等待握手成功。
3. 发送speech.config消息，声明输出格式为 MP3。
4. 发送 SSML 消息，携带文本、voice、rate、pitch。
5. 接收二进制的音频数据帧，收到turn.end后结束并返回完整音频。

@Slf4j @Component public class EdgeTtsSynthesizer { private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor(); private final AtomicReference<String> tokenCache = new AtomicReference<>(); private final AtomicReference<Long> tokenExpireAt = new AtomicReference<>(0L); public byte[] synthesize(String text, String voice, String rate, String pitch) throws Exception { String ssml = buildSsml(escapeXml(text), voice, rate, pitch); CountDownLatch latch = new CountDownLatch(1); ByteArrayOutputStream audioOut = new ByteArrayOutputStream(); AtomicReference<String> errorMsg = new AtomicReference<>(); WebSocketClient client = new WebSocketClient(URI.create(EdgeAuth.getWssUrl())) { @Override public void onOpen(ServerHandshake handshakedata) { sendConfig(this); sendSsml(this, ssml); } @Override public void onMessage(String message) { if (message.contains("Path:turn.end")) { latch.countDown(); } } @Override public void onMessage(ByteBuffer bytes) { byte[] chunk = new byte[bytes.remaining()]; bytes.get(chunk); audioOut.write(chunk); } @Override public void onClose(int code, String reason, boolean remote) { latch.countDown(); } @Override public void onError(Exception ex) { errorMsg.set(ex.getMessage()); latch.countDown(); } }; client.connectBlocking(); client.setConnectionLostTimeout(15); if (!latch.await(30, TimeUnit.SECONDS)) { throw new IllegalStateException("合成超时: " + errorMsg.get()); } client.closeBlocking(); return audioOut.toByteArray(); } }

发送配置消息和 SSML 消息时，需要按协议拼头部。speech.config消息的发送逻辑如下：

private void sendConfig(WebSocketClient client) { Map<String, Object> context = new HashMap<>(); Map<String, Object> synthesis = new HashMap<>(); Map<String, Object> audio = new HashMap<>(); Map<String, Object> metadataOptions = new HashMap<>(); metadataOptions.put("sentenceBoundaryEnabled", "false"); audio.put("metadataoptions", metadataOptions); audio.put("outputFormat", "audio-24khz-48kbitrate-mono-mp3"); synthesis.put("audio", audio); context.put("synthesis", synthesis); Map<String, Object> payload = new HashMap<>(); payload.put("context", context); String json = new ObjectMapper().writeValueAsString(payload); String requestId = UUID.randomUUID().toString(); String configMessage = "X-RequestId:" + requestId + "\r\n" + "Content-Type:application/json\r\n" + "X-Timestamp:" + Instant.now().toString() + "\r\n" + "Path:speech.config\r\n\r\n" + json; client.send(configMessage); }

SSML 消息的拼法类似，Content-Type 换成application/ssml+xml，Path 换成ssml：

private String buildSsml(String text, String voice, String rate, String pitch) { return "<speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis' xml:lang='zh-CN'>" + "<voice name='" + voice + "'>" + "<prosody rate='" + rate + "' pitch='" + pitch + "'>" + text + "</prosody>" + "</voice></speak>"; }

很多第一次写的人会卡在消息格式上：服务端不是靠严格 JSON 解析，而是靠消息体开头那几行Path头来区分消息类型的。我把Path:speech.config和Path:ssml放在每一段消息的头部，再接空行和消息体，照着这个结构来就不会错。

3.4 对外接口：直接返回 MP3 而不是落盘

合成器封装好以后，暴露一个 REST 接口就很容易了。我建议接口直接返回字节流，客户端可以播放、下载，也可以继续加工，不强制落盘。

@RestController @RequestMapping("/api/tts") @RequiredArgsConstructor public class TtsController { private final EdgeTtsSynthesizer synthesizer; @PostMapping(produces = "audio/mpeg") public ResponseEntity<byte[]> tts(@RequestBody TtsRequest request) { try { byte[] audio = synthesizer.synthesize( request.getText(), request.getVoice() == null ? "zh-CN-XiaoxiaoNeural" : request.getVoice(), request.getRate() == null ? "+0%" : request.getRate(), request.getPitch() == null ? "+0Hz" : request.getPitch() ); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"tts.mp3\"") .contentType(MediaType.parseMediaType("audio/mpeg")) .body(audio); } catch (Exception e) { log.error("TTS synthesis failed", e); return ResponseEntity.status(502).build(); } } @Data public static class TtsRequest { private String text; private String voice; private String rate; private String pitch; } }

接口写好之后用 curl 验证：

curl -X POST http://localhost:8080/api/tts \ -H "Content-Type: application/json" \ -d '{"text":"你好，这是一段测试语音","voice":"zh-CN-XiaoxiaoNeural","rate":"+0%","pitch":"+0Hz"}' \ -o test.mp3

返回的test.mp3直接用播放器打开，能听到正常合成语音，这一步就算通了。

3.5 配置项别写死在代码里

把连接超时、输出格式、默认音色这些参数放进application.yml，后续调整不用改代码：

tts: output-format: audio-24khz-48kbitrate-mono-mp3 default-voice: zh-CN-XiaoxiaoNeural connect-timeout-ms: 10000 max-text-length: 1800

我这里把max-text-length单独拉出来，是为了配合第 4 节要说的分片逻辑。你的文本如果普遍很长，这个参数阈值直接影响单次合成的成功率。

4. 集成过程中我实踩的几个坑与修复

4.1 大段文本被服务器掐断：先分片再合成

第一次联调我用了一段 6000 字的文章做测试，结果服务端迟迟不返回turn.end，等到超时直接抛异常。反复试验后发现，单次 SSML 消息体最好像控制在一定长度以内，我按 1000 到 1500 字一片来切就稳定很多。

分片不能硬截，要按照句末标点切。我写了一个简单的分片工具：

private List<String> splitText(String text, int maxLength) { List<String> parts = new ArrayList<>(); String[] sentences = text.split("(?<=[。！？!?\\n])"); StringBuilder current = new StringBuilder(); for (String sentence : sentences) { if (current.length() + sentence.length() > maxLength && current.length() > 0) { parts.add(current.toString()); current.setLength(0); } current.append(sentence); } if (current.length() > 0) { parts.add(current.toString()); } return parts; }

这段代码的逻辑是优先在句号、感叹号、问号处断句，如果单句超长才会硬截到下一句。分片之后按顺序合成，再把多个 MP3 字节拼起来，就能覆盖长文场景。

4.2 Sec-MS-GEC 不要每次重新算

Token 生成有一个哈希开销，更重要的是如果每一个请求都生成新的 token，服务端可能会把这种短时间高频请求识别成异常行为。我们要做的就是缓存 token，快过期时再刷新。

我这里用AtomicReference加过期时间实现了一个很轻的缓存。获取 token 的逻辑是先检查缓存时间戳，未过期就直接用，过期则重新生成。注意 token 的实际有效期存在偏差，我会在服务端允许的时限上主动提前一分钟刷新，避免边缘时间点正好失效。

4.3 并发太高会被断开：给调用方加信号量

EdgeTTS 服务端对并发没有承诺，实际测试下来并发超过十几个时，会开始出现连接被重置、握手超时。我在生产工具的场景里做了两层控制：

第一层是调用代码里加Semaphore，限制同时处理的合成任务数量，我的配置是最大 8 个并发。

private final Semaphore concurrencyLimiter = new Semaphore(8); public byte[] synthesizeWithLimit(...) throws InterruptedException { concurrencyLimiter.acquire(); try { return synthesize(...); } finally { concurrencyLimiter.release(); } }

第二层是在调用方做补偿控制，如果系统短时间内触发很多请求，优先排队而不是无脑并发。这个信号量的思路比高并发线程池直连要稳妥得多。

4.4 多个 MP3 片段拼接时播放器会“跳一下”

分片合成后我直接做字节数组拼接，结果播放到分片衔接处总会出现轻微的跳变。原因在于每个 MP3 片段都会自带一个 ID3 标签头，拼接多个带独立 ID3 头的数据流，播放器会解析到多个元信息块，导致进度和音频数据错位。

解决办法是拼接前把每个片段开头的 ID3 标签剥离开。MP3 的 ID3v2 头部信息通常占据前 3 个字节，我在拼接函数里加了一个剥离逻辑：

private byte[] stripId3Header(byte[] mp3) { if (mp3.length > 3 && (mp3[0] & 0xFF) == 0x49 && (mp3[1] & 0xFF) == 0x44 && (mp3[2] & 0xFF) == 0x33) { int headerSize = ((mp3[6] & 0x7F) << 21) | ((mp3[7] & 0x7F) << 14) | ((mp3[8] & 0x7F) << 7) | (mp3[9] & 0x7F); int tagSize = headerSize + 10; if (tagSize <= mp3.length) { return Arrays.copyOfRange(mp3, tagSize, mp3.length); } } return mp3; }

如果是单次合成、不涉及分片，那可以不关心这个问题。长文合成的场景下这个处理是必须的，否则成品音频的听感会明显受损。

4.5 中文标点和特殊字符导致 SSML 解析失败

把一段包含商品说明的文本扔进接口后，我遇到过生成的音频是空的，服务端错误信息也没进日志。查了一圈发现文本里有英文&符号和<号，这些字符在 XML 里是保留字符，会直接破坏整个 SSML 结构。

解决方式是在拼 SSML 之前对文本做 XML 转义：

private String escapeXml(String text) { if (text == null) return ""; return text .replace("&", "&amp;") .replace("<", "&lt;") .replace(">", "&gt;") .replace("\"", "&quot;") .replace("'", "&apos;"); }

注意转义顺序，&必须第一个处理，否则会把<里的&再次转义，结果就乱了。这个坑很容易被忽略，尤其是当你的文本来自用户输入或富文本内容时。

4.6 超时重试：网络波动是常态

在实际使用中，第一次连接偶尔会出现握手超时，但重试一次往往就成功了。这种偶发性的网络波动没必要深挖根因，做好超时控制和重试即可。

我做了指数退避重试，最多尝试三次：

public byte[] synthesizeWithRetry(String text, String voice, String rate, String pitch) throws Exception { int maxAttempts = 3; int delayMs = 1000; for (int i = 1; i <= maxAttempts; i++) { try { return synthesize(text, voice, rate, pitch); } catch (Exception e) { log.warn("TTS attempt {} failed: {}", i, e.getMessage()); if (i == maxAttempts) { throw e; } Thread.sleep(delayMs); delayMs *= 2; } } throw new IllegalStateException("unreachable"); }

重试时要注意一个问题：如果已经发送了部分文本并且服务端合成成功，但响应超时导致客户端断线，重试会出现重复合成。我的做法是只在连接阶段或者还没有收到任何音频数据帧时重试，一旦开始收到音频数据就耐心等待完整结果。

5. 进阶玩法：SSML 控制、缓存和批量合成

5.1 用 SSML 做出更自然的停顿和语气

基础版只会把文字连续读出来，听多了会发现缺少节奏感。SSML 里提供了一些可以注入的停顿和语气控制标签。我最常用的两个场景：

长句读起来有压迫感时，在句号后面加一个短停顿：

<speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis' xml:lang='zh-CN'> <voice name='zh-CN-XiaoxiaoNeural'> 今天的会议重点有三项。<break time='500ms'/>第一项是项目管理流程调整。 </voice> </speak>

故事类内容想要更温和的语气，把语速调慢一点、音调降低一点：

<prosody rate='-10%' pitch='-2Hz'>夜已经很深了，窗外的灯光渐渐稀疏。</prosody>

SSML 的自由度比单纯传 text 大很多，但这意味着你需要在文本层面维护更复杂的标记结构。我的建议是：如果只是把整篇文章转成音频，不需要做太精细的标记，系统性地在换行处插break就够了；如果是做配音类的片段，再用 prosody 细调。

5.2 加一层缓存：同一个文本不合成第二次

同样的文本、同样的 voice 和语速，合成出来的 MP3 字节流是完全一样的。如果不加缓存，每次重复调用都会白耗一次网络请求。我在项目里引入了 Caffeine 作缓存，key 用文本、音色、rate、pitch 的 MD5 值，value 直接存合成的字节数组。

Cache<String, byte[]> ttsCache = Caffeine.newBuilder() .maximumSize(500) .expireAfterWrite(Duration.ofHours(24)) .build(); public byte[] synthesizeCached(String text, String voice, String rate, String pitch) throws Exception { String key = md5(text + "#" + voice + "#" + rate + "#" + pitch); byte[] cached = ttsCache.getIfPresent(key); if (cached != null) { return cached; } byte[] audio = synthesize(text, voice, rate, pitch); ttsCache.put(key, audio); return audio; }

这个缓存的收益比你想的大。接口耗时从几百毫秒到一两秒不等，缓存命中后直接减小到接近零；服务端的压力也能大幅下降。实测下来，我的文章转音频工具加完缓存之后，用户重复点击同一个任务，基本秒开。

5.3 批量合成与任务顺序控制

当你有几十篇文章需要转成音频时，同步调用接口逐个合成虽然可行，但效率很低。我的做法是交给线程池并发合成，同时保持顺序。

思路是：先按文章内部分片，用ExecutorService提交每个分片的合成任务，任务完成后把结果按索引放入结果数组，最后按顺序拼接并剥离 ID3 头。这样既能利用多线程提升吞吐量，又能保证最终成品的切分顺序正确。

ExecutorService executor = Executors.newFixedThreadPool(8); List<Future<byte[]>> futures = new ArrayList<>(); for (int i = 0; i < parts.size(); i++) { final int index = i; futures.add(executor.submit(() -> synthesizeWithRetry(parts.get(index), voice, rate, pitch))); } ByteArrayOutputStream merged = new ByteArrayOutputStream(); for (Future<byte[]> future : futures) { byte[] partAudio = future.get(); merged.write(stripId3Header(partAudio)); }

这里有个容易踩的细节：Future列表的顺序就是你提交任务的顺序，get()会阻塞等待结果，所以如果第一个分片合成很慢，后面的结果即使已经完成也要等它。如果任务之间没有强顺序要求，可以做更激进的乱序聚合；如果有，这个方案最简单可靠。

5.4 它还能往哪里延伸

集成稳定之后，我顺手做了两个扩展，你可以按需参考。

一个是给 MP3 文件补充 ID3 元信息，包括标题、作者、生成时间，这样音频文件在播放器里看起来更像正经产物。另一个是结合其他离线能力做“文章自动分章节配音”，根据文章标题自动生成淡入淡出的音频列表，再把合成结果交给播放器端做列表循环。

说到底，EdgeTTS 这套方案解决的是“低成本获得可用中文 TTS”的问题，它的上限取决于你对外设的边界。把它当成一个合成了字节流的工具，而不是一个语音云平台，你对它的预期就会清晰很多。

最后说一点个人体会：我在同事群里推广这套集成时，特意强调了两件事。第一，任何时候都不要把它部署成对外承诺 SLA 的生产链路，一旦服务端的协议或 token 规则调整，整个系统会立刻受牵连。第二，缓存和重试写到位之前，先小范围试用，等音频稳定了再铺开。我踩过超时、分片、ID3 头这些坑之后，这套工具才真正变成一个稳定省钱的内部能力。你上手时如果也遇到类似问题，按文章里的排查顺序走一遍，通常都能解决。