Vue3对接讯飞实时语音转文字：WebSocket鉴权与音频流处理实战

简介：一套基于Vue.js的科大讯飞实时语音转文字集成示例，面向希望在前端项目中直接接入语音转写能力的开发者，尤其适合对WebAudio与REST接口衔接感兴趣的中高级前端。压缩包仅16KB，共8个文件，包含1个HTML入口与7个JS脚本：其中音频处理脚本（Worker/Worklet）负责音频流采集与切片，鉴权相关脚本（MD5、HMAC等）完成API签名，SDK入口脚本负责整体封装，结构紧凑，便于直接对照阅读。该资源已有4420人学习，是Vue.js结合讯飞WebAPI的实用参考。虽然文件量不大，但覆盖了从获取用户麦克风、音频流实时上传到前端动态展示识别结果的完整链路，并演示了加密鉴权与异常处理逻辑；同时分离了Worker和Worklet线程，避免大量音频计算阻塞页面渲染，展示了如何将底层Web Audio能力嵌入Vue组件。开发者可替换API密钥快速验证效果，也可学习其中的鉴权实现和音视频处理思路，为构建会议字幕、语音笔记等生产级应用提供基础样例。 讯飞实时语音转文字接口是我这两年做前端音视频项目时用得比较多的云服务之一，前阵子刚好在Vue3项目里完整对接了一版“网页端实时语音转写”功能，从鉴权、麦克风采集、WebSocket音频流上送到最终的文字增量渲染，整套流程踩了不少坑。网上聊这个主题的资料不少，但大部分停留在调用官方demo，真正把Vue组件里音频采集、协议细节、结果拼接讲透的不多。这篇就把我实际跑通的方案完整拆开，按“为什么选这个方案→鉴权怎么做→Vue组件怎么写→常见问题怎么排查”的顺序记录一遍，如果你正准备在网页里做会议纪要、客服质检、采访字幕这类实时转写功能，可以直接照着我这份流程走。

顺便提一句，最近在搜索“科大讯飞实时语音转文字vuejs版本”这个词的时候，总能看到“科大讯飞语音引擎9.0”“科大讯飞t30lite拆机配件配置”这类热搜词，很多人对讯飞的语音引擎版本和硬件方案感兴趣。语音引擎9.0在噪声鲁棒性、中英文混读、标点预测上确实有明显升级，而像t30lite这类讯飞录音笔硬件里也是套着同一套语音识别技术在做离线转写。但网页端实时转写走的是讯飞开放平台的WebAPI，和后端引擎版本逻辑一致，前端只需要关心API层的对接即可，不需要关心内部模型，这也是我选用它的一个重要原因——把重型识别交给云，前端只做采集和展示。

1. 方案选型：为什么是“讯飞WebSocket实时转写”

1.1 实时转写链路的基本原理

先说清楚“实时语音转文字”和“录音文件转写”的本质区别。录音文件转写是你先把一段音频整个录下来，上传到服务端，服务端一次性返回完整文本，适合“先录后转”的场景。而实时转写走的是流式识别：麦克风采集到的音频按帧切分，每帧几十毫秒，边采集边通过WebSocket发送给讯飞服务端，服务端一边接收一边做增量识别，再把识别出的中间结果实时推回前端。

所以整个技术链路可以拆成四段：

1. 浏览器通过getUserMedia拿到麦克风音频流
2. 用AudioContext把原始音频重采样成讯飞要求的16kHz、16bit、单声道PCM数据
3. 建立WebSocket连接，按固定帧长把PCM二进制数据推给讯飞
4. 接收识别结果，解析JSON协议，增量渲染到页面

这四段里每一段都有容易出问题的地方，尤其是音频格式和结果解析，后面我会分别展开讲。

1.2 为什么选讯飞而不是其他语音服务

技术选型这件事，我觉得要放在具体场景里看。如果你做的是英文识别，Google和Azure的表现都还可以；但如果你做的是中文识别，特别是带口音、带专业术语的中文，讯飞在中文本土化上的积累确实是实打实的。讯飞开放平台的“实时语音转写”接口（一般叫语音听写WebAPI或流式听写）有这几个优势：

• 中文识别准确率高：日常对话场景下，识别效果明显好于很多通用引擎，语音引擎9.0在标点预测、数字格式化和热词召回上又进了一步
• 协议简单：整体就是WebSocket + JSON，前端原生就能接，不依赖特定SDK，Vue/React都能玩
• 支持扩展：热词、方言、语种、标点、动态修正这些参数都在握手阶段配置，一个URL就能带过去
• 按量计费：个人项目和小团队门槛低，有免费额度，demo阶段基本不花钱

我在决定用讯飞之前其实也试过一些开源方案，比如基于Kaldi部署的离线识别服务，部署成本高不说，识别效果调优非常耗时，不适合快速落地。讯飞这种云API的优势就是我把主体逻辑写完，识别效果基本不用操心，省下大量调模型的时间。

1.3 前端直连还是后端代理

讯飞的流式听写WebAPI是支持前端直连的，认证方式不是传统的“AppID+APIKey明文请求”，而是通过hmac-sha256签名生成一个带鉴权参数的WebSocket URL，前端拿到这个URL之后直接new WebSocket()建立连接。签名所需的APIKey、APISecret一旦泄露，任何人都能拿你的额度去调用服务。

所以我建议的架构是这样的：

• 本机demo：可以把签名逻辑放在前端，纯本地调试用，方便
• 生产环境：签名URL由后端生成，前端向后端要一个类似wss://xxx的地址，密钥不出服务端

后面给的示例为了你方便跑通，签名逻辑会写成一个独立的Node脚本放在前端工程里演示，但部署上生产之前，请务必把这个逻辑挪到后端。

2. 鉴权URL是怎么算出来的：从排序到HMAC签名

2.1 鉴权三步走

讯飞流式听写WebAPI的握手地址是这样的格式：

wss://iat-api.xfyun.cn/v2/iat

但直接连这个地址是不行的，必须在URL后面拼上authorization、date、host三个鉴权参数。拼接规则我拆解一下：

1. 生成RFC1123格式的date：即当前时间的GMT字符串，比如Thu, 01 Jan 2025 00:00:00 GMT
2. 拼接签名原串：把host、date、request-line按特定格式拼成一个字符串
3. 用APISecret做HMAC-SHA256签名：对签名原串做HMAC加密，结果做base64编码，得到authorization的值

签名原串的格式非常关键，它是这样的：

host: iat-api.xfyun.cn date: Thu, 01 Jan 2025 00:00:00 GMT GET /v2/iat HTTP/1.1

注意这三个部分之间不能有多余的空行，第二行末尾是\n，第三行是GET /v2/iat HTTP/1.1，这个request-line必须严格写成这样，少了HTTP/1.1或者大小写不对，后面握手直接401。

2.2 Node.js生成鉴权URL的完整代码

我们项目的后端是Node.js，所以签名逻辑长这样：

const crypto = require('crypto'); const url = require('url'); function getAuthUrl(apiKey, apiSecret, host = 'iat-api.xfyun.cn', path = '/v2/iat') { const date = new Date().toUTCString(); // 1. 拼接签名原串 const signatureOrigin = `host: ${host}\ndate: ${date}\nGET ${path} HTTP/1.1`; // 2. HMAC-SHA256签名 const signature = crypto .createHmac('sha256', apiSecret) .update(signatureOrigin) .digest('base64'); // 3. 拼接authorization const authorization = `api_key="${apiKey}", algorithm="hmac-sha256", headers="host date request-line", signature="${signature}"`; // 4. URL编码后拼到wss地址上 const query = { authorization: Buffer.from(authorization).toString('base64'), date: encodeURIComponent(date), host: host, }; return `wss://${host}${path}?${new URLSearchParams(query).toString()}`; }

这段代码里最容易出错的就是new Date().toUTCString()生成的date和Python/Java后端生成的date格式要一致，如果后端不是Node，也要确保是RFC1123格式，长这样：Thu, 01 Jan 2025 00:00:00 GMT，不是2025-01-01T00:00:00Z这种ISO格式。签名原串里的date必须和URL上query里的date是同一个字符串，这个细节也常被忽略。

2.3 为什么需要这样设计鉴权

你可能会问，为什么不能像老接口那样直接把APIKey放在参数里请求？因为WebSocket连接一旦建立会持续很久，而且鉴权参数要在URL里传递，如果直接放明文APIKey，抓包就能看到，风险极高。HMAC签名的好处是APIKey和APISecret不需要直接传输，传输的只是签名结果，就算URL被别人截获，也有date时间戳做有效期限制，过期之后连接自然失败。这是很多云服务通用的认证思路。

不过要注意，这个签名URL和最终建立的WebSocket连接的“有效期”相关的主要是date的时效性，如果客户端本机时间和服务器时间差太多，签名验证也会失败，所以生产环境务必要保证客户端时钟是准的。还要注意，URL里参数的顺序不影响鉴权，但签名原串里的顺序必须严格是host、date、request-line。

3. Vue3组件实现：从麦克风到文字的完整链路

3.1 麦克风采集与AudioContext重采样

浏览器拿麦克风音频流是navigator.mediaDevices.getUserMedia，这一步简单，但后续处理才是关键。麦克风原始采样率通常是48kHz或44.1kHz，而讯飞要求的是16kHz、16bit、单声道PCM。浏览器里做重采样最方便的就是AudioContext。

我用的逻辑是这样的：

async function initAudioStream() { const stream = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true, autoGainControl: true, }, }); const audioCtx = new AudioContext({ sampleRate: 16000 }); const source = audioCtx.createMediaStreamSource(stream); // 这里用ScriptProcessor做采集（AudioWorklet更优但复杂度高） const processor = audioCtx.createScriptProcessor(4096, 1, 1); source.connect(processor); processor.connect(audioCtx.destination); processor.onaudioprocess = (e) => { const inputData = e.inputBuffer.getChannelData(0); // Float32 -> Int16 PCM const pcmData = floatTo16BitPCM(inputData); // 发送给WebSocket if (ws && ws.readyState === WebSocket.OPEN) { ws.send(pcmData); } }; }

这里有个重要细节：new AudioContext({ sampleRate: 16000 })并不保证所有浏览器都支持直接指定采样率，某些浏览器会忽略这个参数，实际返回的context还是48kHz。所以更稳妥的做法是正常创建AudioContext（默认44.1/48kHz），然后在onaudioprocess里手动做重采样。重采样最简单的办法是用离线AudioContext做一次再采样，但实时场景下不现实，我建议直接用线性插值或者引入xaudio.js这类库。实测下来线性插值在语音场景完全够用，语音本身频带窄，插值造成的高频损失几乎不影响识别率。

3.2 Float32转Int16 PCM

WebAudio的音频采样数据是Float32数组，范围是-1.0 ~ 1.0，而讯飞要求的是16bit PCM，也就是有符号整数-32768 ~ 32767，必须做一次转换：

function floatTo16BitPCM(input) { const buffer = new ArrayBuffer(input.length * 2); const view = new DataView(buffer); for (let i = 0; i < input.length; i++) { let s = Math.max(-1, Math.min(1, input[i])); view.setInt16(i * 2, s < 0 ? s * 0x8000 : s * 0x7fff, true); } return buffer; }

这里有两个坑：一是setInt16的第三个参数littleEndian必须传true，讯飞协议里明确是小端序，不传的话后端解析出来的就是乱码；二是转换前要做一次Math.max/min限幅，防止样本越界产生爆音，这个在实时采集时特别容易出现，因为麦克风自动增益和说话人离麦远近都会让信号幅度跳变。

3.3 WebSocket连接与音频帧发送

连接地址就是上面签名生成的URL，建立连接后有一个非常关键的握手协议：你必须在连接建立后先发送一个JSON文本帧，告诉讯飞你要做什么、参数是什么。这个JSON长这样：

ws = new WebSocket(authUrl); ws.onopen = () => { ws.send(JSON.stringify({ common: { app_id: '你的AppID', }, business: { language: 'zh_cn', domain: 'iat', accent: 'mandarin', vad_eos: 5000, ptt: 1, dwa: 'wpgs', }, data: { status: 0, format: 'audio/L16;rate=16000', encoding: 'raw', }, })); };

这段参数里，business中的domain: 'iat'是听写领域的标志，accent可以换成方言（比如cantonese粤语、henan河南话），language默认zh_cn。vad_eos表示静音多久算一句话结束，单位是毫秒，默认5000，也就是5秒不说话自动断句，我建议根据你实际场景调一下，会议纪要场景可以调大一点到8000，一句话说到一半停顿超过5秒会被切成两句，影响阅读。ptt: 1是开启标点预测，识别结果里会带逗号句号问号，如果不需要标点可以设0。dwa: 'wpgs'是开启动态修正和分段，这一项直接影响后面解析增量结果，强烈建议开启。

第一帧JSON里的data.status = 0表示这是音频流的“第一帧”，后续所有纯音频二进制帧的status都不需要再设置（因为那些是二进制帧不是JSON），要等到音频全部发完了，最后发一个data:{status: 2}的JSON帧表示流结束。

音频数据帧的发送就是上面onaudioprocess里那个ws.send(pcmData)，不需要额外加什么头，WebSocket本身会保证帧边界，讯飞服务端做的就是边收边识别。需要注意的是，不要每采集到一帧就立刻发送，这会导致网络包特别碎、识别不连贯。实测下来，ScriptProcessor的缓冲区大小设为4096（大约85ms音频）发送一次，效果和稳定性最好。

3.4 识别结果解析与增量拼接

这是整个对接过程中最容易写错的部分。讯飞WebSocket返回的报文长这样：

{ "code": 0, "data": { "status": 2, "data": { "cn": { "st": { "type": "word", "ws": [ { "bg": 0, "cw": [{ "sc": 0, "w": "你好" }] } ] } } }, "status_text": "", "type": "0" } }

只看结构的话，data.cn.st.ws是一个词数组，每个ws元素里有bg（词的开始帧）、cw（候选词数组，我们一般取cw[0].w作为最佳识别结果）。这本身不难，难的是多个帧的增量结果怎么拼。

实时识别不是一次性给你完整一句话，而是同一句话会反复返回多次中间结果，每次返回的ws数组都比上一次多几个词或者修正了前面几个词。所以如果你简单地把每次返回的ws全部concat到一个数组里，页面上会出现“你好你好好你好今天”这种重复文本。

讯飞针对这个问题提供了一种模式，也是我在business里加dwa: 'wpgs'的原因。开启wpgs模式后，返回的type字段会变成"wpgs"，每次返回的数据里除了cn.st.ws，还会带一个cn.st.type和data.status，配合ws数组里每个词的bg（开始时间）来区分当前这段是“新的增量”还是“对前面某个词的修正”。

我的拼接策略是这样的：

• 维护一个lastText变量保存当前句子已经完整识别的文本
• 每次收到新消息，判断data.type === '0'还是"wpgs"，wpgs模式下会有data.data.cn.st.ws完整的当前句候选
• 如果返回的ws数组里第一个词的bg大于当前已渲染词的最大bg，说明这是新追加的内容，把新增部分push到结果数组
• 遇到data.status === 2，说明这句话已经完整识别结束（或者vad断句），把当前临时句子的内容输出到最终结果，清空临时状态

上面这段描述听起来抽象，实际代码我是这样写的：

let curText = ''; // 当前句子最终文本 let curWs = []; // 当前句中已经处理过的词 function handleMessage(json) { const code = json.code || 0; if (code !== 0) { console.error('识别错误, code:', code, json.message); return; } const data = json.data; const status = data.status; const cn = data.data?.cn; if (!cn) return; const wsArr = cn.st?.ws || []; // 找到这个增量结果里是否包含已经处理过的词 // 这里简化处理，用每句话累计的文本做替换更新 const sentenceText = wsArr.map(item => item.cw[0].w).join(''); // 更新中间结果展示（页面上的灰色文字） interimText.value = sentenceText; // 如果这句话已经结束 if (status === 2) { finalText.value += sentenceText; interimText.value = ''; lastSentence = ''; } }

这个简化版适用于“只展示最终识别结果”的场景，中间结果每次覆盖更新，最终结果在整句话结束后追加。但如果要做“边说边出字，颜色渐变区分”，就需要维护一个更精细的词级状态机。我在项目中做的是“词级增量渲染”：每次来新的wpgs结果，取ws中新增的、bg比当前渲染位置大的词追加到已确定区，最后一句的词显示为淡色。这是体验最好的方式，但复杂度会上一个台阶，建议先用上面简化版跑通，再逐步加。

4. 实操中的常见问题与排查清单

我在对接过程中前前后后遇到了十几个报错和异常现象，下面这些是最典型的，写出来给你排雷。

4.1 错误码与协议问题

10163这个错我印象最深。第一次对接时我一直怀疑是AudioContext采样率设置没生效，折腾了一个多小时，最后发现是floatTo16BitPCM里setInt16没传小端参数，数据出来是反的。这种细节影响特别大，光看错误码完全看不出来。

4.2 浏览器兼容与权限问题

getUserMedia必须跑在https或者localhost环境下，这是浏览器的安全策略。如果你的Vue项目是http://192.168.x.x这种局域网IP，直接调用getUserMedia会报NotAllowedError。本地联调用vite或webpack的devServer默认是localhost，没问题；但如果要放到内网其他设备上测试，devServer需要开启https。Vite里开https很简单：

// vite.config.js export default { server: { https: true, host: '0.0.0.0', }, };

这时候浏览器会提示证书不受信任，但自己测试点“继续访问”就行。另外注意，Chrome对AudioContext有自动播放策略限制，如果你在页面加载完成后直接调用new AudioContext()，它可能处于suspended状态，需要用户点击按钮后再resume()。所以开始录音按钮的第一步先做audioCtx.resume()再初始化，否则采到的全是静音。

4.3 识别效果相关的问题

识别不准这个“问题”，其实是很多因素叠加出来的，远程排查的时候90%跟代码无关，而是音频质量。我遇到过的情况包括：

• 说话人离麦克风1米以上，识别率明显下降。网页场景下，建议用耳麦或者把设备放到说话人面前
• 开启noiseSuppression后某些浏览器会有声音断续的情况，如果发现识别文本掉字，试着去掉这个约束
• 专业术语识别很差，比如“Vue.js”“webpack”这类词会识别成“无爱点解”“外博配克”。解决方法是配置热词，在握手帧的business里加hotwords: 'Vue.js:50,webpack:40'，权重范围1-100，数字越大优先度越高
• 中英混读场景，language设成zh_cn有可能把英文词吃掉，可以试试language: 'zh_en'

我实际项目里遇到的“热词”问题是最影响体验的，因为前端培训类内容里大量的API、Vue、JavaScript这些词，默认模型经常识别错。把热词配置加上之后，准确率肉眼可见地提升，发布前强烈建议把你业务里的高频命名词都列出来加进热词表。

5. 从Demo到生产环境，还要解决哪些事

5.1 服务端鉴权与连接状态管理

Demo阶段签名放在前端很快，但生产上我坚决建议把生成鉴权URL的接口挪到后端，前端只保留一个类似getAuthUrl()的异步请求。后端需要做两件事：一是鉴权（校验调用者身份），二是限流（防止某个用户恶意刷你的API额度）。讯飞的流式听写额度是按音频时长计算的，同一个AppID如果被刷，你每个月免费额度很快就没了，而且账单会很吓人。

连接管理上，WebSocket断开后要自动重连，但重连的时候不能直接拿旧的鉴权URL，因为旧的URL里的date可能已过期，需要重新向后端申请。所以我在封装useIatRecognition这个组合式函数时，把“创建连接-重连-销毁连接”的状态机统一管理，页面组件只关心调用start()和stop()。

5.2 进一步可以考虑的增强能力

讯飞这个接口还支持不少高级参数，按需开启能显著提升产品力：

• 动态修正（dwa: 'wpgs'）：不光是增量解析，它对数字、时间、地名的识别结果修正作用明显，建议保持开启
• 标点预测（ptt: 1）：默认加标点，直接用于生成会议纪要很合适
• 方言识别：accent改成henan/cantonese/sichuan等，如果有方言场景会很有用
• 语种扩展：language: 'zh_en'支持中英混说，访谈类场景好用
• 自定义热词：上面的hotwords参数，格式是词:权重,词:权重，权重越高越优先
• 语义分段：讯飞有“语义分段”的服务，需要在控制台单独开通，开通后长对话会自动分段落，省去前端自己按标点切段的工作

这些参数全部是在握手帧的business字段里配置的，和代码结构强耦合。我的习惯是先搭一个JSON配置对象，把语言、方言、标点、热词、vad超时全部配好，然后生成JSON后发送，调试时直接改配置看效果，比改代码快得多。

6. 一点踩坑心得

最后说点代码之外的东西。实时语音转文字这个功能，实现的难点不在于某一个单独环节，而在于整条链路的串联。音频采集要稳、签名要规范、协议要正确、增量拼接要细心，任何一个环节出问题，表现都是“识别结果不对”或者“页面不工作”，排查起来非常隐蔽。我的建议是分阶段调试，先用讯飞官方提供的在线demo把音频格式和鉴权URL验通，再接入Vue组件，最后再调展示层。不要在没验证音频格式的情况下直接写完整组件，不然后面光是定位是音频问题还是解析问题就很头疼。

另外一个提醒是，麦克风权限和音频上下文的生命周期在SPA应用里要格外注意。Vue组件切换到其他页面时，记得在onBeforeUnmount里把AudioContext关闭、把WebSocket关闭、把getUserMedia拿到的MediaStream的track全部stop掉，不然会出现切走页面之后麦克风还在工作、识别的文字还在不断打印的诡异现象。这个我在实际项目中踩过，开会中间切到别的tab，整个会议结束才发现后台一直在识别。

这个小功能其实可以从“实时语音转文字”延伸到很多有趣的方向，比如再加一段翻译逻辑就成了“AI同传”demo，把识别结果对接到大模型就可以做“会议问答摘要”。讯飞这套WebAPI能力足够稳，你只要把前端链路打通，剩下的想象空间非常大。

本文还有配套的精品资源，点击获取