Django客户端集成Speech Recognition语音识别报错解决

首先明确核心误区：在Django Python环境中安装的SpeechRecognition是后端语音处理库，和浏览器端运行的Web Speech API完全无关，安装后端依赖对前端语音识别功能没有任何作用。

初始化报错的核心原因是浏览器内置的SpeechRecognition接口仅在安全上下文中开放调用权限：

• 直接本地打开HTML文件时走file://协议，属于浏览器默认信任的上下文，因此可以正常运行
• 集成到Django后如果使用非localhost的HTTP协议访问（比如用局域网IP访问http://192.168.x.x:8000、线上部署用普通HTTP域名），浏览器会直接禁用该API，初始化时直接抛出错误。

分步修复方案 #

1. 优化前端JS逻辑，增加兼容性判断与实时识别能力 #

不要直接初始化SpeechRecognition实例，先做特性检测，同时开启临时结果返回实现边说边显示的效果，替换原有脚本内容如下：

// 先做浏览器兼容性检测
const SpeechRecognitionConstructor = window.SpeechRecognition || window.webkitSpeechRecognition || window.mozSpeechRecognition || window.msSpeechRecognition;
const voiceBtn = document.getElementById("the_button");
const formInput = document.getElementById("the_form");
let recognitionInstance = null;

if (!SpeechRecognitionConstructor) {
    voiceBtn.disabled = true;
    voiceBtn.value = "当前浏览器不支持语音输入";
} else {
    recognitionInstance = new SpeechRecognitionConstructor();
    // 按需配置识别参数
    recognitionInstance.lang = "zh-CN"; // 中文识别设为zh-CN，英文识别设为en-US
    recognitionInstance.interimResults = true; // 开启实时临时结果回显
    recognitionInstance.continuous = false; // 单次识别，说完自动停止

    voiceBtn.addEventListener("click", () => {
        recognitionInstance.start();
        voiceBtn.value = "正在聆听...";
    });

    // 实时更新输入框内容，用户可随时手动修正错误
    recognitionInstance.onresult = (event) => {
        let finalText = "";
        let interimText = "";
        for (let i = event.resultIndex; i < event.results.length; i++) {
            const currentText = event.results[i][0].transcript;
            if (event.results[i].isFinal) {
                finalText += currentText;
            } else {
                interimText += currentText;
            }
        }
        formInput.value = finalText + interimText;
    };

    recognitionInstance.onend = () => {
        voiceBtn.value = "点击说话";
    };

    recognitionInstance.onerror = (event) => {
        voiceBtn.value = "点击说话";
        if (event.error === "not-allowed") {
            alert("请允许站点访问麦克风权限后重试");
        }
    };
}

2. 确保访问Django服务时满足安全上下文要求 #

满足以下任意一种访问条件即可正常调用API：

• 本地开发阶段，使用http://127.0.0.1:8000或http://localhost:8000访问服务，这两个地址被浏览器默认标记为安全上下文
• 若需要局域网设备访问、或线上正式部署，必须为站点配置HTTPS，否则浏览器会永久屏蔽SpeechRecognition接口调用

3. Django侧适配注意事项 #

• 无需在INSTALLED_APPS中注册任何语音相关后端库，该功能完全运行在用户浏览器端，后端仅需按普通文本字段接收表单提交值即可
• 确保渲染模板时JS脚本在DOM元素加载完成后执行：可保留脚本放在</body>标签前的写法，或给script标签添加defer属性，避免因找不到DOM元素触发报错
• 若站点配置了内容安全策略（CSP），需放开麦克风访问权限，不要限制媒体源与内联脚本执行（或把JS代码抽到静态文件中正确加载）

内容的提问来源于stack exchange，提问作者Dmitry