iOS WKWebView调用WebKit语音识别API无法获取转写结果咨询

算力阿峰

2026-10-5

问题原因

WKWebView默认未开启语音识别API的调用权限：Safari作为系统内置浏览器默认可调用Siri语音识别服务，第三方App内嵌的WKWebView需要额外的权限配置，仅在info.plist中声明权限无法满足调用要求。
自定义音频处理逻辑抢占了音频输入流：你实现的MicrophoneHandler使用AVAudioEngine占用了系统音频输入通道，Web层的SpeechRecognition API无法获取到实时音频流，自然无法生成识别结果，也就不会触发onresult事件。
本地文件加载的安全限制：使用loadFileURL加载本地网页时，WKWebView对系统级权限API的访问限制比加载远程HTTPS站点更严格，会限制语音识别API的正常调用。

遗漏的配置项

未在WKWebView初始化时配置媒体捕获权限策略：iOS 15及以上系统的WKWebView提供了媒体权限配置接口，默认需要用户交互才能触发权限申请，你没有修改该默认配置。
未在原生层提前请求语音识别权限：Web层的SpeechRecognition API可调用的前提是App本身已经获得了系统的语音识别授权，你仅在Web侧触发权限申请无法拿到系统级授权。
未处理音频会话的兼容配置：自定义的音频会话设置和WKWebView内置的音频会话逻辑冲突，导致Web层无法正常获取麦克风输入数据。

解决思路

移除自定义的MicrophoneHandler相关代码，不要自行抢占音频输入通道，让WKWebView自行处理麦克风访问逻辑，避免资源冲突。
App启动后先在原生层主动请求语音识别权限，确认授权通过后再加载Web页面，参考代码如下：

import Speech

SFSpeechRecognizer.requestAuthorization { authStatus in
    DispatchQueue.main.async {
        guard authStatus == .authorized else {
            // 处理权限拒绝逻辑
            return
        }
        // 权限通过后再加载Web页面
        loadWebPage()
    }
}

调整WKWebView初始化的配置项，添加媒体权限相关配置，参考代码如下：

let webView: WKWebView = {
    let prefs = WKWebpagePreferences()
    prefs.allowsContentJavaScript = true
    let webConfiguration = WKWebViewConfiguration()
    webConfiguration.defaultWebpagePreferences = prefs
    webConfiguration.allowsInlineMediaPlayback = true
    webConfiguration.allowsPictureInPictureMediaPlayback = true
    
    if #available(iOS 15.0, *) {
        // 移除媒体播放的用户交互限制
        webConfiguration.mediaTypesRequiringUserActionForPlayback = []
        // 移除媒体捕获的用户交互限制
        webConfiguration.requiresUserActionForMediaCapture = false
    }
    return WKWebView(frame: .zero, configuration: webConfiguration)
}()

// 页面加载完成后主动授予对应站点麦克风和语音识别权限
func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
    guard let origin = webView.url?.host, #available(iOS 15.0, *) else {
        return
    }
    webView.setPermission(.allow, for: .microphone, origin: origin)
    webView.setPermission(.allow, for: .speechRecognition, origin: origin)
}

如果是加载本地HTML文件，建议将本地文件托管到本地临时HTTP服务上，使用http://localhost的地址加载，避免本地文件协议的安全限制。
在Web端的语音识别逻辑中添加onerror事件监听，打印具体错误信息，可辅助定位具体问题。

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