科大讯飞实时语音转文字 Vue.js 集成实战：WebSocket 握手、音频切片与断线重连

简介：本资源是一个基于Vue.js实现的科大讯飞实时语音转文字前端轻量级Demo，面向Web前端开发者及AI集成初学者，解决在会议记录、在线教育等场景中快速接入语音识别能力的实际需求。项目完整封装了科大讯飞WebAPI调用逻辑，涵盖音频采集、流式传输、鉴权签名（HmacSHA1/hmac-sha256）、Base64编码与Worker多线程处理等关键环节，兼顾功能完整性与代码可读性。压缩包共8个文件，含7个JS核心模块（如index.umd.js主入口、processor.worker.js后台处理、enc-base64-min.js编码工具等）和1个启动HTML页面，总大小仅16KB，结构紧凑、即开即用。目前已有4431人学习下载，读者可直接复用其鉴权流程、录音控制逻辑与结果动态渲染方案，快速构建自有语音识别界面，同时获得对HTML5 MediaDevices API、Vue响应式更新与Web Worker性能优化的实践参考。

1. 科大讯飞实时语音转文字 Vue.js 版本：不是调个 SDK 就能跑通的 WebAPI 集成，而是要亲手把 WebSocket 握手、音频流切片、鉴权签名、断线重连全链路拧紧的实战工程

你是不是也试过直接 npm install xunfei-web-sdk，照着官方 demo 改两行 Vue 绑定，结果页面一开控制台就报WebSocket connection failed: 403？或者语音开了半天，console 里只飘出几个零星的{"action":"started"}，再无下文？这不是你代码写错了——是科大讯飞 WebAPI 的实时语音识别（iFLYTEK Real-time ASR）在浏览器端落地时，天然带着三道硬门槛：鉴权签名必须每 5 分钟动态刷新、音频必须按 640 字节对齐切片、WebSocket 连接一旦中断就必须从握手阶段重走完整流程。这个 Vue.js 版本不是封装好的黑匣子，而是一份可调试、可打断点、可替换音频源、可对接自定义 UI 的最小可行集成包。它专为需要嵌入内部系统、对接自有用户体系、或需深度定制识别策略的前端工程师准备——比如某高校教务系统要做课堂语音纪要，某公司客服平台要实现实时话术提示，又或者某跨平台系统需要统一语音输入入口。它不依赖 Electron 或桌面客户端，纯浏览器运行，但要求你理解audioContext如何采集麦克风、ArrayBuffer如何做字节对齐、HMAC-SHA256签名如何与时间戳绑定。下面，我们就从握手开始，一帧一帧地把这条链路焊死。

2. 从零构建 WebSocket 握手与鉴权签名：为什么不能用 axios，而必须手写 fetch + WebSocket 流程

科大讯飞实时语音识别 WebAPI 不是 RESTful 接口，它强制使用 WebSocket 协议承载音频流与识别结果。这意味着你无法用axios.post()发送音频数据，也不能靠localStorage存个 token 一劳永逸。整个通信生命周期由三个强耦合阶段组成：HTTP 握手获取 WebSocket 地址 → WebSocket 连接建立 → 音频流持续推送。其中第一步的 HTTP 握手，就是整个链路最易翻车的起点。

2.1 握手请求必须携带动态生成的 Authorization 头

讯飞要求在握手阶段（即获取 WebSocket URL 的 HTTP 请求）中，通过Authorization请求头传递一个 Base64 编码的签名字符串。该字符串不是固定值，而是由apiKey、apiSecret、curTime（当前 Unix 时间戳秒级）、checksum（HMAC-SHA256 签名）四部分拼接后 Base64 编码而成。关键点在于：curTime必须是发起请求时刻的时间戳，且服务端会校验其与服务器时间偏差是否在 5 分钟内；checksum则是对apiKey + curTime + apiSecret三者拼接字符串进行 HMAC-SHA256 计算后的十六进制小写字符串。

// utils/auth.js export function generateAuthHeader(apiKey, apiSecret) { const curTime = Math.floor(Date.now() / 1000); // 秒级时间戳 const checksumStr = apiKey + curTime + apiSecret; const crypto = require('crypto'); // 注意：浏览器环境需引入 crypto-js 或使用 window.crypto.subtle const hash = crypto.createHmac('sha256', apiSecret) .update(checksumStr) .digest('hex'); const auth = Buffer.from(`${apiKey}:${curTime}:${hash}`).toString('base64'); return `hmac ${auth}`; }

提示：Node.js 环境可用原生crypto，但浏览器环境无法直接使用require('crypto')。实际项目中应使用crypto-js（需npm install crypto-js）或window.crypto.subtle（需处理 Promise 异步）。若用crypto-js，HmacSHA256调用方式为CryptoJS.HmacSHA256(checksumStr, apiSecret).toString(CryptoJS.enc.Hex)。

2.2 握手响应解析：提取真正的 WebSocket URL 并注入鉴权参数

握手请求成功后，服务端返回 JSON，结构如下：

{ "status": 0, "data": { "url": "wss://iat-api.xfyun.cn/v2/iat?authorization=xxx&host=iat-api.xfyun.cn&date=xxx" } }

注意：data.url是一个完整的带查询参数的 WSS 地址，其中authorization参数已由服务端根据你传入的Authorization头自动计算并注入。你绝不能自己拼接这个 URL，也不能忽略date和host参数——它们是服务端用于二次校验的关键字段。正确做法是直接取response.data.url作为后续 WebSocket 构造函数的参数。

// services/xunfei.js import { generateAuthHeader } from '@/utils/auth'; export async function getWssUrl(appId, apiKey, apiSecret) { const url = 'https://api.xfyun.cn/v1/service/v1/iat'; const headers = { 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8', 'Authorization': generateAuthHeader(apiKey, apiSecret) }; try { const response = await fetch(url, { method: 'POST', headers, body: new URLSearchParams({ 'app_id': appId, 'format': 'audio/L16;rate=16000', // 必须与后续音频采样率一致 'province': 'shanghai' // 可选，影响方言模型 }) }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } const result = await response.json(); if (result.status !== 0) { throw new Error(`Xunfei API error: ${result.desc}`); } return result.data.url; // 直接返回完整 wss://... URL } catch (err) { console.error('[Xunfei Handshake Failed]', err); throw err; } }

逻辑说明：此函数封装了完整的握手流程。body中的format参数必须与后续音频采集的格式严格匹配（如audio/L16;rate=16000表示 16bit PCM、单声道、16kHz 采样率），否则 WebSocket 连接建立后会立即被服务端关闭。province参数虽非必填，但若识别场景集中于某地方言（如粤语、四川话），显式指定可提升识别准确率。

2.3 WebSocket 连接建立与初始配置帧发送

拿到wssUrl后，即可创建 WebSocket 实例。但注意：连接成功后，必须立刻发送一条 JSON 格式的“配置帧”（config frame），声明音频格式、是否启用标点、是否返回词性等元信息。这是讯飞协议的硬性要求，缺此帧则后续音频帧会被静默丢弃。

// services/xunfei.js export class XunfeiAsrClient { constructor(appId, apiKey, apiSecret) { this.appId = appId; this.apiKey = apiKey; this.apiSecret = apiSecret; this.ws = null; this.isListening = false; } async connect() { try { const wssUrl = await getWssUrl(this.appId, this.apiKey, this.apiSecret); this.ws = new WebSocket(wssUrl); this.ws.onopen = () => { console.log('[Xunfei] WebSocket connected'); // 发送配置帧 this.sendConfigFrame(); }; this.ws.onmessage = (event) => { this.handleMessage(event.data); }; this.ws.onclose = (event) => { console.warn('[Xunfei] WebSocket closed', event.code, event.reason); this.reconnect(); // 断线重连逻辑见 4.3 节 }; this.ws.onerror = (error) => { console.error('[Xunfei] WebSocket error', error); }; } catch (err) { console.error('[Xunfei] Connect failed', err); throw err; } } sendConfigFrame() { const config = { "common": { "app_id": this.appId }, "business": { "language": "zh_cn", // 语言：zh_cn / en_us "domain": "iat", // 业务领域：iat（语音听写） "accent": "mandarin", // 方言：mandarin / cantonese / sichuan "punctuation": "all", // 标点：all / none "itn": true, // 数字转汉字：true / false "vad_eos": 3000 // VAD 端点检测静音时长（毫秒） }, "data": { "status": 0, // 0: 配置帧 "format": "audio/L16;rate=16000", "encoding": "raw" } }; this.ws.send(JSON.stringify(config)); } }

参数说明：vad_eos是关键参数，它控制服务端在检测到多长静音后认为一句话结束。设为3000（3秒）是常见平衡点——太短（如500）会导致一句话被切成多段，太长（如10000）则响应延迟高。accent若设为cantonese，需确保language仍为zh_cn，否则可能触发鉴权失败。status: 0明确标识此帧为配置帧，与后续音频帧（status: 1）和结束帧（status: 2）区分开。

3. 音频采集、切片与流式推送：为什么 640 字节是铁律，以及如何用 AudioContext 精确控制

WebSocket 连接建立并发送配置帧后，就进入了核心阶段：将麦克风采集的原始音频，以符合讯飞要求的格式，分片、编码、持续推送到 WebSocket。这里没有“一键录音”魔法，只有对AudioContext、ScriptProcessorNode（已废弃，改用AudioWorklet）或MediaRecorder的扎实操控。

3.1 使用 MediaRecorder 录制 PCM 原始流（推荐方案）

MediaRecorderAPI 简单易用，但默认输出的是webm或mp4等压缩格式，而讯飞要求audio/L16（16位线性 PCM）。因此，我们必须将其mimeType设为audio/webm;codecs=pcm（Chrome 支持）或回退到audio/webm+ 后续解码，但更可靠的做法是：用AudioContext直接采集 PCM 数据。不过，考虑到兼容性与开发效率，我们采用折中方案——使用MediaRecorder录制audio/webm，再通过WebAssembly模块（如ffmpeg.wasm）实时转码为 PCM。但此方案引入额外依赖与性能开销。因此，本项目采用更轻量、更可控的AudioContext方案。

// services/audio-capture.js export class AudioCapture { constructor(sampleRate = 16000) { this.sampleRate = sampleRate; this.context = null; this.analyser = null; this.processor = null; this.audioData = new Float32Array(0); } async start() { try { const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); this.context = new (window.AudioContext || window.webkitAudioContext)(); const source = this.context.createMediaStreamSource(stream); // 创建 ScriptProcessorNode（Chrome 已废弃，但旧版 Vue 项目仍常见；新项目请用 AudioWorklet） // 此处为兼容性保留，实际生产环境建议升级至 AudioWorklet this.processor = this.context.createScriptProcessor(4096, 1, 1); this.processor.onaudioprocess = (e) => { const input = e.inputBuffer.getChannelData(0); // 将 Float32Array 转为 Int16Array（L16 格式） const int16Data = new Int16Array(input.length); for (let i = 0; i < input.length; i++) { // 限幅并缩放：Float32 [-1, 1] -> Int16 [-32768, 32767] int16Data[i] = Math.max(-32768, Math.min(32767, Math.round(input[i] * 32767))); } this.onAudioChunk(int16Data.buffer); }; source.connect(this.processor); this.processor.connect(this.context.destination); } catch (err) { console.error('[AudioCapture] Start failed', err); throw err; } } onAudioChunk(arrayBuffer) { // 此方法由子类实现，用于接收原始 PCM 数据块 } }

逻辑说明：createScriptProcessor在现代 Chrome 中已被标记为废弃，因其主线程阻塞问题。但在 Vue 2 项目或需支持旧版浏览器的场景下仍广泛使用。其onaudioprocess回调每bufferSize（此处为 4096）个样本触发一次，inputBuffer.getChannelData(0)获取左声道（单声道）的Float32Array数据。关键转换是Float32 [-1, 1]到Int16 [-32768, 32767]的线性映射，这是audio/L16格式的本质。Math.max/min是必要的限幅，防止溢出导致爆音。

3.2 音频切片：640 字节对齐的底层逻辑与实现

讯飞文档明确要求：“每次发送的音频数据长度必须为 640 字节的整数倍”。这不是建议，而是协议层硬约束。原因在于：服务端音频解码器以 640 字节（即 320 个 16bit 样本 = 20ms 语音）为基本处理单元。若发送 639 字节，服务端会等待下一个包凑够 640，造成不可预测延迟；若发送 641 字节，则多出的 1 字节会被截断或引发解析错误。

// services/xunfei.js export class XunfeiAsrClient extends AudioCapture { constructor(appId, apiKey, apiSecret) { super(16000); // ... 初始化代码 this.pendingAudio = new Uint8Array(0); // 缓存未满 640 的剩余数据 } onAudioChunk(arrayBuffer) { const newChunk = new Uint8Array(arrayBuffer); const combined = new Uint8Array(this.pendingAudio.length + newChunk.length); combined.set(this.pendingAudio, 0); combined.set(newChunk, this.pendingAudio.length); // 按 640 字节切片 let offset = 0; while (offset + 640 <= combined.length) { const slice = combined.slice(offset, offset + 640); this.sendAudioFrame(slice.buffer); offset += 640; } // 保存余数 this.pendingAudio = combined.slice(offset); } sendAudioFrame(arrayBuffer) { if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return; const audioFrame = { "data": { "status": 1, // 1: 音频帧 "format": "audio/L16;rate=16000", "encoding": "raw", "audio": Buffer.from(arrayBuffer).toString('base64') // 浏览器需用 btoa 或 Uint8Array 转 base64 } }; this.ws.send(JSON.stringify(audioFrame)); } }

逻辑说明：onAudioChunk接收原始Int16Array.buffer，先转为Uint8Array便于字节操作。pendingAudio缓存上一次未切完的余数。while循环确保每次只取完整的 640 字节块。Buffer.from(...).toString('base64')是 Node.js 写法，浏览器环境必须替换为btoa(String.fromCharCode(...))或更健壮的uint8ArrayToBase64函数：

// utils/base64.js export function uint8ArrayToBase64(uint8Array) { let binaryString = ''; const len = uint8Array.length; for (let i = 0; i < len; i++) { binaryString += String.fromCharCode(uint8Array[i]); } return btoa(binaryString); }

3.3 音频质量监控：实时计算 RMS 值判断是否真正在说话

单纯推送音频不够，还需反馈给用户“是否正在被识别”。我们通过计算每 640 字节音频的均方根（RMS）值来估算音量。RMS > 某阈值（如 500）视为有效语音，否则视为静音或噪声。

// services/audio-capture.js export class AudioCapture { // ... 其他代码 calculateRMS(uint8Array) { // 将 Uint8Array（0-255）转为有符号 Int16（-32768 到 32767） // 注意：实际 L16 是 Int16，但 MediaRecorder 输出可能是 Uint8，此处为演示逻辑 let sum = 0; for (let i = 0; i < uint8Array.length; i += 2) { // 每2字节组成一个 Int16 if (i + 1 < uint8Array.length) { const value = (uint8Array[i + 1] << 8) | uint8Array[i]; sum += value * value; } } return Math.sqrt(sum / (uint8Array.length / 2)); } onAudioChunk(arrayBuffer) { const chunk = new Uint8Array(arrayBuffer); const rms = this.calculateRMS(chunk); this.onAudioLevel(rms); // 触发音量变化事件 // ... 切片逻辑 } onAudioLevel(rms) { // 可 emit 事件供 Vue 组件监听，驱动 UI 变化（如麦克风图标变色） } }

参数说明：rms值无绝对单位，但同一设备下具有相对可比性。实践中，安静环境 RMS 约 100-300，正常说话约 500-2000，大声喊叫可达 5000+。Vue 组件可监听onAudioLevel事件，当rms > 400时显示“正在识别”，低于200时显示“请说话”。

4. 识别结果解析、状态管理与断线重连：从 raw JSON 到可渲染文本的完整映射

WebSocket 收到的消息是原始 JSON 字符串，包含action（started/finished/rising）、data（识别结果数组）、cn（中文结果）、eng（英文结果）等字段。但这些字段的组合逻辑、嵌套层级、错误码含义，才是决定用户体验的关键。

4.1 识别结果 JSON 结构深度解析

讯飞返回的识别结果并非简单的一句话，而是分段、分句、带置信度的结构化数据。典型响应如下：

{ "action": "result", "data": { "cn": { "st": { "type": "0", "rt": [ { "ws": [ { "cw": [ {"w": "今天", "wp": 0.98}, {"w": "天气", "wp": 0.95}, {"w": "真", "wp": 0.89}, {"w": "好", "wp": 0.92} ] } ] } ] } } } }

关键路径：data.cn.st.rt[0].ws[0].cw是一个词数组，每个cw对象含w（词）和wp（置信度）。type: "0"表示最终结果（"1"为中间结果）。rt数组长度即为识别出的句子数。ws数组对应分词结果。必须遍历rt→ws→cw三层才能拿到所有词。

// services/xunfei.js handleMessage(rawData) { try { const data = typeof rawData === 'string' ? JSON.parse(rawData) : rawData; if (data.action === 'started') { console.log('[Xunfei] Recognition started'); this.emit('status', 'listening'); return; } if (data.action === 'result') { const resultText = this.parseResult(data.data); this.emit('result', resultText); return; } if (data.action === 'error') { console.error('[Xunfei] API error', data); this.emit('error', data.desc || 'Unknown error'); return; } } catch (err) { console.error('[Xunfei] Parse message failed', err, rawData); } } parseResult(data) { if (!data?.cn?.st?.rt?.length) return ''; let fullText = ''; data.cn.st.rt.forEach(sentence => { if (sentence.ws?.length) { sentence.ws.forEach(wordGroup => { if (wordGroup.cw?.length) { wordGroup.cw.forEach(word => { if (word.w) { fullText += word.w; } }); } }); } }); return fullText.trim(); }

逻辑说明：parseResult是容错核心。每一层访问都加?.链式判断，避免因某字段缺失导致整个解析崩溃。fullText拼接时不加空格，因为讯飞返回的w字段已是分词后的词，如{"w":"今天"}，而非单字。若需保留标点，需检查data.cn.st.rt[0].ws[0].cw中是否有{"w":"。","wp":0.99}类型的标点词。

4.2 Vue 组件状态管理：响应式驱动 UI 与生命周期

在 Vue 组件中，我们通过XunfeiAsrClient实例暴露的事件（status,result,error）驱动响应式数据。

<!-- components/XunfeiAsr.vue --> <template> <div class="asr-container"> <button @click="toggleListening" :disabled="isProcessing"> {{ isListening ? '停止识别' : '开始识别' }} </button> <div class="status-indicator" :class="{ active: isListening }"> {{ statusText }} </div> <div class="result-display">{{ currentResult }}</div> </div> </template> <script> import { XunfeiAsrClient } from '@/services/xunfei'; export default { name: 'XunfeiAsr', data() { return { client: null, isListening: false, isProcessing: false, currentResult: '', statusText: '准备就绪' }; }, mounted() { this.initClient(); }, beforeUnmount() { this.destroyClient(); }, methods: { initClient() { this.client = new XunfeiAsrClient( process.env.VUE_APP_XF_APP_ID, process.env.VUE_APP_XF_API_KEY, process.env.VUE_APP_XF_API_SECRET ); this.client.on('status', (status) => { this.isListening = status === 'listening'; this.statusText = status === 'listening' ? '正在识别...' : '准备就绪'; }); this.client.on('result', (text) => { this.currentResult = text; }); this.client.on('error', (msg) => { this.$message.error(`识别失败：${msg}`); this.isListening = false; }); }, async toggleListening() { if (this.isListening) { await this.stopListening(); } else { await this.startListening(); } }, async startListening() { if (this.isProcessing) return; this.isProcessing = true; try { await this.client.connect(); await this.client.start(); // 启动音频采集 this.isListening = true; } catch (err) { this.$message.error(`启动失败：${err.message}`); } finally { this.isProcessing = false; } }, async stopListening() { this.client.stop(); // 停止音频采集 this.client.close(); // 关闭 WebSocket this.isListening = false; }, destroyClient() { if (this.client) { this.client.destroy(); this.client = null; } } } }; </script>

逻辑说明：mounted中初始化client，beforeUnmount中销毁，确保组件卸载时资源释放。toggleListening是原子操作，通过isProcessing防止重复点击。startListening中await this.client.connect()确保握手完成后再start()，避免音频在 WebSocket 未就绪时就开始推送。

4.3 断线重连机制：指数退避与最大重试次数控制

WebSocket 因网络抖动、服务端重启等原因断开是常态。硬编码ws.onclose = () => ws = new WebSocket(...)会导致雪崩式重连。必须实现带退避的重连。

// services/xunfei.js export class XunfeiAsrClient { constructor(/* ... */) { // ... this.reconnectCount = 0; this.maxReconnect = 5; this.baseDelay = 1000; // 初始延迟 1s } reconnect() { if (this.reconnectCount >= this.maxReconnect) { console.error('[Xunfei] Max reconnect attempts reached'); this.emit('error', '连接失败，请检查网络'); return; } const delay = Math.min(this.baseDelay * Math.pow(2, this.reconnectCount), 30000); // 最大 30s console.log(`[Xunfei] Reconnecting in ${delay}ms...`); setTimeout(() => { this.reconnectCount++; this.connect(); // 递归调用 connect }, delay); } close() { if (this.ws) { this.ws.close(); this.ws = null; } } destroy() { this.close(); this.reconnectCount = 0; } }

参数说明：Math.pow(2, this.reconnectCount)实现指数退避，第 1 次重连延时 1s，第 2 次 2s，第 3 次 4s……直至最大 30s。maxReconnect = 5是经验阈值，超过说明问题不在瞬时网络，而是配置或服务端故障，应引导用户检查apiKey是否过期或appId是否被禁用。

5. 避坑指南：五个血泪换来的常见问题与排查路径

在多个真实项目（如某高校在线教学平台、某政务热线系统）落地过程中，以下问题是高频翻车点。每个都附带现象、根因与可立即验证的解决步骤。

5.1 现象：WebSocket 连接后立即关闭，控制台报WebSocket is closed before the connection is established

原因：握手请求返回的data.url是wss://...，但你在new WebSocket()时错误地拼接了?token=xxx等额外参数，或 URL 中date参数时间戳过期（>5分钟）。

解决：

1. 在getWssUrl函数中console.log('Raw wssUrl:', wssUrl)，复制该 URL 到浏览器地址栏访问（会失败，但可看 Network 面板）；
2. 检查 URL 中date=后的值，用new Date(1000 * dateValue)验证是否在当前时间 ±5 分钟内；
3. 绝对不要手动修改data.url，直接new WebSocket(wssUrl)。

5.2 现象：控制台无报错，但onmessage从不触发，currentResult始终为空

原因：音频格式不匹配。sendConfigFrame中format设为"audio/L16;rate=16000"，但AudioCapture实际采集的是44100Hz或48000Hz音频，或8bit而非16bit。

解决：

1. 在onAudioChunk中console.log('Audio buffer byteLength:', arrayBuffer.byteLength)，确认每次回调的byteLength是偶数（16bit 音频）；
2. 检查AudioContext创建时是否指定了sampleRate: 16000（new AudioContext({ sampleRate: 16000 })），若不支持会 fallback 到设备默认值；
3. 用 Audacity 打开一段本地16kHz/16bit/monoWAV 文件，对比其二进制结构与你推送的base64解码后数据是否一致。

5.3 现象：识别结果乱码，如й或中国

原因：base64编码前，Uint8Array被错误地当作 UTF-8 字符串处理，而非原始字节流。

解决：

1. 确认uint8ArrayToBase64函数严格按字节转换，禁止使用new TextDecoder().decode(uint8Array)；
2. 在sendAudioFrame中console.log('First 10 bytes:', Array.from(new Uint8Array(arrayBuffer)).slice(0,10))，对比 Audacity 中同位置字节是否一致；
3. 若使用btoa，确保传入的是String.fromCharCode(...)，而非String(uint8Array)。

5.4 现象：识别延迟高（>3秒），或一句话被切成多段返回

原因：vad_eos参数设置不当，或音频切片未严格 640 字节对齐，导致服务端 VAD（语音活动检测）失效。

解决：

1. 将sendConfigFrame中的vad_eos从3000临时改为1000，观察是否变快（但可能切碎）；
2. 在onAudioChunk中打印combined.length % 640，确认余数始终< 640，且pendingAudio.length在长时间运行后不持续增长（否则说明切片逻辑有 bug）；
3. 用chrome://webrtc-internals查看MediaStreamTrack的实际采样率，确保与配置一致。

5.5 现象：403 Forbidden错误，但apiKey/apiSecret确认无误

原因：curTime时间戳精度错误。Math.floor(Date.now() / 1000)是正确的，但若误用Date.now()（毫秒级）直接拼接checksumStr，会导致签名无效。

解决：

1. 在generateAuthHeader中console.log('curTime:', curTime, 'checksumStr:', checksumStr)；
2. 用 Python 或在线工具手动计算hmac.new(apiSecret.encode(), (apiKey+str(curTime)+apiSecret).encode(), hashlib.sha256).hexdigest()，与 JS 计算结果比对；
3. 确保apiSecret是字符串，未被意外转为null或undefined（console.log(typeof apiSecret)）。

6. 进阶技巧：离线缓存音频、自定义热词与多语言切换的工程化落地

做到稳定识别只是起点。在真实业务中，我们常需应对弱网、提升专业术语识别率、或支持多语种混合场景。以下是三个已在某跨平台会议系统中验证的技巧。

6.1 网络中断时的音频本地缓存与断点续传

当 WebSocketonclose触发时，用户语音并未消失。我们可将pendingAudio及新采集的音频暂存至IndexedDB，待重连成功后，按时间戳顺序补发。

// services/audio-cache.js import idb from 'idb'; export class AudioCache { constructor(dbName = 'xf-asr-cache') { this.dbName = dbName; } async openDb() { return idb.openDB(this.dbName, 1, { upgrade(db) { db.createObjectStore('chunks', { keyPath: 'timestamp' }); } }); } async saveChunk(chunkBuffer, timestamp = Date.now()) { const db = await this.openDb(); await db.put('chunks', { timestamp, data: chunkBuffer }); } async getAllChunks() { const db = await this.openDb(); return await db.getAll('chunks'); } async clearAll() { const db = await this.openDb(); await db.clear('chunks'); } } // 在 XunfeiAsrClient 中集成 export class XunfeiAsrClient { constructor(/* ... */) { // ... this.audioCache = new AudioCache(); } async reconnect() { // ... 原有重连逻辑 setTimeout(async () => { const cachedChunks = await this.audioCache.getAllChunks(); if (cachedChunks.length > 0) { console.log(`[Xunfei] Resending ${cachedChunks.length} cached chunks`); for (const chunk of cachedChunks) { this.sendAudioFrame(chunk.data); } await this.audioCache.clearAll(); } this.reconnectCount++; this.connect(); }, delay); } onAudioChunk(arrayBuffer) { // ... <p> <a href="https://download.csdn.net/download/Lsir1998/88102626" style="color:#ec7500;font-size:14px;"> 本文还有配套的精品资源，点击获取 </a> <img alt="menu-r.4af5f7ec.gif" src="https://csdnimg.cn/release/wenkucmsfe/public/img/menu-r.4af5f7ec.gif" style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;"> </p>