ThinkPHP 接入科大讯飞语音需前后端分工：前端录音，后端处理音频、签名鉴权并调用 API；ASR 要求 raw PCM 格式（16bit/16kHz/单声道），base64 编码传输；TTS 推荐 WebSocket 流式调用，动态生成带签名的 URL；需配置白名单、匹配服务类型 KEY、预装 ffmpeg，并统一封装为 XunFeiService 服务。
ThinkPHP 本身不提供语音能力，接入科大讯飞语音服务需分两步走：前端完成录音与音频准备，后端（ThinkPHP）负责接收、格式处理、签名认证并调用讯飞 API。语音合成（TTS）和语音听写（ASR）流程不同，但共用核心鉴权逻辑和音频规范。
语音听写（ASR）接入要点
听写是把用户语音转成文字，关键在音频格式、签名生成和接口调用方式：
- 音频必须为 raw PCM 格式：16bit、单声道、16kHz；WAV 文件需剥离头信息，MP3/AMR 等必须用 ffmpeg 先转码，例如：
ffmpeg -i input.wav -f s16le -ar 16000 -ac 1 -acodec pcm_s16le output.pcm - 讯飞 WebAPI 不接受文件上传，需将 PCM 内容 base64 编码后放入 JSON body 的 audio 字段，Content-Type 设为 application/x-www-form-urlencoded
- 签名（X-CheckSum）由 APP_KEY + X-CurTime + X-Param 拼接后 MD5 得到；X-Param 是 engine_type 和 aue 字段的 base64 编码 JSON，如：
{"engine_type":"sms16k","aue":"raw"} - ThinkPHP 接收音频建议用
$request->file('audio')，再读取临时路径，避免绕过框架校验；识别结果返回 JSON，需解析data['result']或遍历ws数组拼接文字
语音合成（TTS）接入要点
合成是把文字转成语音流，讯飞推荐使用 WebSocket 流式接口，更稳定、支持长文本：
- 需建立 WebSocket 连接，URL 由 APPID、APIKey、APISecret 动态生成，含时间戳和签名（HMAC-SHA256）
- 首次发送的消息体包含 appid、text、voice_name（如 xiaoyan）、speed、volume 等参数；后续接收的是分片音频 base64 数据，需持续解码并追加写入文件（如 .mp3）
- 状态字段
status === 2表示合成结束；中途任一响应code !== 0需中止并记录错误码（如 10105 表示鉴权失败） - ThinkPHP 中可用
ext-websocket扩展或原生stream_socket_client实现，注意设置超时和 SSL 上下文
ThinkPHP 项目配置与避坑提示
实际部署中常见问题多源于配置疏漏或格式偏差：
立即学习“PHP免费学习笔记（深入）”；
- 讯飞控制台需添加服务器出口 IP 到白名单，5–10 分钟生效；未加白名单会返回 10203 或 10210 错误
- APPID、APIKey、APISecret 必须与创建应用时的服务类型匹配——语音听写和语音合成的 KEY 是分开申请的，不可混用
- 开发调试阶段建议先用讯飞开放平台的「在线调试工具」验证参数组合，再迁移到 ThinkPHP；避免直接改代码盲试
- 音频上传大小限制默认 64MB，但讯飞听写接口建议单次请求 ≤ 60 秒语音（约 1.8MB raw PCM），超时或过大易触发 504 或 10407
简单封装建议
可在 ThinkPHP 的 service 层统一管理讯飞能力，例如：
- 新建
XunFeiService类，封装签名生成、PCM 转码、WebSocket 连接、错误映射等通用逻辑 - 听写方法接收
UploadedFile对象，自动判断扩展名并调用 ffmpeg 转码（需服务器预装） - 合成方法支持传入文字、语速、音色，并返回生成的音频 URL 或本地路径，便于前端播放
- 所有外部请求统一走 GuzzleHttp 客户端，设置默认 timeout=15、verify=true，避免 SSL 报错
