Troubleshooting - zkwi/VoxType GitHub Wiki

声写 VoxType 常见问题与排障

本页面是 GitHub Wiki Troubleshooting 的仓库内草稿镜像，用于避免线上 Wiki 与仓库文档长期漂移。

English version: Troubleshooting

快速检查

遇到问题时，先按顺序检查：

  1. API配置页顶部健康检查是否有红色阻断项。
  2. 当前 ASR 服务的必填认证是否填写。
  3. Windows 是否允许桌面应用访问麦克风。
  4. 首页是否显示至少一种触发方式。
  5. 光标是否在可输入文本框中。
  6. 目标软件是否拦截粘贴快捷键。
  7. 选项页是否能打开日志或复制脱敏诊断报告。

启动白屏或卡在启动页

现象

  • 打开 VoxType 后主窗口一直白屏。
  • 一直停留在“声写正在启动”页面。
  • 重装 VoxType 后仍然无法进入主界面。
  • 其他依赖 WebView2 的 Windows 桌面应用也可能异常。

原因

VoxType 是 Tauri 桌面应用，主窗口依赖 Microsoft Edge WebView2 Runtime 渲染。如果系统里的 WebView2 Runtime 损坏、缺失、版本过旧，或被系统策略阻断，应用前端还没加载起来，VoxType 自己就无法展示完整的排障界面。

因此不建议 VoxType 在应用内自动下载、提权或静默修复系统组件。更稳妥的做法是让安装包负责缺失时安装 Runtime；如果系统 Runtime 已损坏，再由用户手动覆盖修复。

推荐修复步骤

  1. 关闭 VoxType。
  2. 打开微软官方 WebView2 下载页：https://developer.microsoft.com/microsoft-edge/webview2/
  3. 下载 Evergreen Standalone Installer，Windows 10/11 普通 64 位电脑选择 x64。
  4. 将安装器保存到本地，例如 C:\Temp\MicrosoftEdgeWebView2RuntimeInstallerX64.exe。
  5. 右键安装器，选择“以管理员身份运行”，执行覆盖安装。
  6. 安装完成后重启 VoxType。
  7. 如果仍然白屏，重启 Windows 后再打开 VoxType。

也可以在管理员 PowerShell 中运行：

Start-Process -Wait -Verb RunAs "C:\Temp\MicrosoftEdgeWebView2RuntimeInstallerX64.exe" -ArgumentList "/silent", "/install"

开机后没有看到主窗口

从 0.14.0 起，随 Windows 登录自动启动且语音识别已配置好时，VoxType 直接待在托盘，不再弹出主窗口。这是预期行为，语音输入照常可用。

  • 点击任务栏右侧的托盘图标即可打开主窗口；图标可能收在“显示隐藏的图标”里。
  • 再次从开始菜单启动 VoxType，也会唤起已在运行的主窗口。
  • 手动启动、尚未完成配置、或从托盘菜单点“重启程序”时，主窗口照常显示。

按 Ctrl + Q 没有反应

可能原因：

  • ASR 认证未填写，主流程被锁定。
  • 主快捷键被关闭。
  • 快捷键被其他软件占用。
  • VoxType 正在启动、停止、等待最终结果、润色或输出。
  • 目标软件以管理员身份运行，拦截了普通权限程序的模拟输入。

处理方式：

  1. 进入 API配置，确认 ASR 必填项已填写。
  2. 进入选项页，确认主快捷键是 Ctrl + Q 且至少一种触发方式开启。
  3. 换一个热键测试。
  4. 如果目标软件是管理员权限，尝试同样以管理员身份启动 VoxType。

没有识别到文字

可能原因：

  • 麦克风权限未开启。
  • 输入设备选择错误。
  • 麦克风音量过低或距离太远。
  • 麦克风驱动、蓝牙耳机或独占占用导致输入流运行中异常。
  • 本次录音没有有效语音。
  • 网络连接 ASR 服务异常。

处理方式：

  1. 在 Windows 设置中允许桌面应用访问麦克风。
  2. 在选项页选择正确输入设备。
  3. 如果麦克风声音偏小但清晰，先确认 Windows 麦克风音量和说话距离；录音质量卡片仍反复提示音量偏小时，再在选项页的录音排障中把输入增益小幅调到 +3 dB 或 +6 dB。
  4. 在 API配置页点击当前 ASR 服务测试。
  5. 在安静环境下重新录音。
  6. 如果提示麦克风采集异常，重新插拔或切换输入设备，关闭可能独占麦克风的软件后再试。

说明：

  • 空识别会进入失败态，不会触发润色、粘贴或成功统计。
  • 麦克风输入流运行中异常也会进入失败态，避免缺帧音频产生低质量识别结果。
  • 输入增益默认 0 dB，只在本地放大发送给当前 ASR 服务的 PCM，不会保存音频；过高会削波或放大环境噪声。
  • ASR 无反馈自动停止默认 30 秒，只在服务端没有返回有效文本反馈时按正常停录流程收尾。
  • 如果网络或服务端响应较慢，可在选项页调大该秒数；填 0 可关闭。

ASR 测试失败

如果在浏览器表单里按右 Alt 或鼠标中键会丢焦点，先确认对应触发方式是否已开启：开启后 VoxType 会独占这个按键，浏览器收不到，也就不会失焦；关闭时按键原样传给浏览器，Chrome 会把单独的 Alt 当成激活菜单栏、把中键当成自动滚动，从而让输入框失焦。

先确认 API配置页选择的 ASR 服务和豆包接入方式与认证字段匹配。豆包语音控制台 API Key 方式只需要控制台创建的 API Key 和已开通的 Resource ID；旧版标准方式需要 App Key、Access Key 和 Resource ID 属于同一个语音识别服务；Agent Plan 需要方舟专属 API Key，并在方舟控制台配置豆包流式语音识别模型 2.0 和超额后付费。阿里云 FunASR 模式需要 API Key、Workspace ID、地域和模型权限属于同一个百炼工作空间。不要把大模型 API Key、GitHub Token、火山引擎 IAM Secret 或其他平台密钥填到错误的 ASR 服务里。

常见处理：

  1. 豆包认证或权限失败：先确认接入方式；语音控制台 API Key 方式确认密钥来自「API Key 管理」且资源已开通，旧版标准方式重新复制 App Key、Access Key 并检查 Resource ID，Agent Plan 重新复制专属 API Key 并检查模型配置和超额后付费。方舟 Agent Plan 订阅失效时会返回 InvalidSubscription，需要改用其他接入方式或恢复订阅。
  2. 阿里云认证或权限失败：重新复制 API Key，确认 Workspace ID、地域和 fun-asr-realtime 模型权限匹配。
  3. 连接失败或超时：检查代理、防火墙和网络是否能访问当前 ASR 服务域名。
  4. 修改识别语言后失败：先改回“自动 / 服务默认”再测试。
  5. 测试通过但录音没字：检查 Windows 麦克风权限、输入设备和音量。

“测试通过”只证明真实凭据、网络/TLS 和服务权限可用：测试发送的是程序生成的短静音包，不会开启麦克风。录音没字仍需单独排查麦克风采集、真实音频、最终包和输出链路。

公开提问时只贴脱敏诊断报告中的错误码和状态，不要贴真实密钥、完整日志或识别正文。

识别成功但没有粘贴

先按 Ctrl + V 手动粘贴。如果文字能粘贴，说明识别和剪贴板写入成功，问题通常在目标软件拦截模拟粘贴。

首页出现“已完成本次输入”时，VoxType 已把识别文本写入剪贴板并尝试粘贴。可以点击首页的“复制文本”重新写入剪贴板，或点“查看识别文本”确认本次内容；这份文本只保留在当前窗口，关闭窗口或开始下一次录音后会清除。

处理方式：

  1. 先在记事本测试。
  2. 若文本已复制，手动按 Ctrl + V。
  3. 在选项页尝试 Shift + Insert 或“仅复制到剪贴板”。
  4. 如果目标软件读取剪贴板较慢，可在 config.toml 中增加剪贴板恢复延迟。

粘贴后原剪贴板没有完整恢复

VoxType 会尽量恢复常见剪贴板格式。截图这类位图只要不超过快照上限（默认 8MB）就能恢复；超过上限的大图、文件句柄和大体积私有格式可能无法完整备份。

建议：

  • 普通文本和常见富文本通常更稳定。
  • 大剪贴板内容容易触发快照上限。
  • 原剪贴板完全无法恢复时，VoxType 会给出提示，并保留识别文本可手动粘贴；只是个别格式没能备份时不打扰你，只记在日志里。
  • 如果经常处理大图、大表格或文件列表，可临时关闭自动恢复或改用“仅复制到剪贴板”。

大模型润色没有生效

可能原因：

  • 大模型润色未启用。
  • Base URL、API Key 或模型名不完整。
  • 润色触发长度低于 min_chars。
  • LLM 测试失败。

处理方式：

  1. 在 API配置页开启大模型润色。
  2. 填写 Base URL、API Key 和模型。
  3. 点击 LLM 测试。
  4. 确认 Base URL、API Key 和模型来自同一个大模型平台/地域。
  5. 短文本不需要润色时，保持默认即可。

说明：

  • 默认 DashScope / 阿里云百炼北京地域 Base URL 是 https://dashscope.aliyuncs.com/compatible-mode/v1。
  • DeepSeek 等标准 OpenAI 兼容服务可填写服务根地址、/v1 地址或完整 /chat/completions 地址，例如 https://api.deepseek.com、https://api.deepseek.com/v1/、https://api.deepseek.com/v1/chat/completions 会作为等价地址处理。
  • Base URL 常见问题是填错服务商地址，或 Key 来自另一个平台/地域。
  • 模型名称必须是账号可调用的模型名；模型不存在或无权限都会导致测试失败。
  • 大模型润色失败不会清空 ASR 文本，VoxType 会继续使用原始识别文本。

大模型润色太慢

优化建议：

  • qwen3.7-max-preview 和 qwen3.7-max-2026-05-17 仅支持思考模式，无法关闭；请改用 qwen3.7-max、qwen3.7-max-2026-05-20 或 qwen3.7-max-2026-06-08。
  • 修改 Base URL、API Key、模型名或 thinking 开关后，等待自动保存触发的大模型适配测试；如果仍然很慢，再在 API配置页手动重新测试一次，并保持 thinking 关闭。
  • 提高 min_chars，让短文本直接使用 ASR 结果。
  • 降低热词、最近上下文和屏幕 OCR 的 LLM 参考预算，减少发送给模型的上下文。
  • 使用响应更快的模型。
  • 网络慢时再增加 LLM 超时，不要把超时当作加速手段。
  • 如果同一个模型在其他客户端更快，优先对比是否关闭了 thinking/reasoning、是否使用同一个 Base URL、是否同样没有设置过小的输出上限。

参考：LLM 润色模型测试记录 已补充 2026-05-30 复测，说明不同服务商和思考参数对速度的影响。

技术路径或文件名被大模型改错

大模型会尝试把 ASR 文本整理成“看起来合理”的形式，代码路径、文件名、日志字段和英文标识符最容易被误改。

建议：

  • 开启屏幕 OCR，让当前窗口或显示器里的准确路径作为参考信息进入 ASR 和可选 LLM。
  • 把常用路径、文件名、产品名、字段名加入热词。
  • 对含路径、命令、日志字段的输出做人工确认。
  • 不要只靠切换到某个模型解决；当前复测中多个模型都会改错技术路径。

热词没有明显效果

热词不是强制替换表，而是给 ASR 和可选 LLM 提供上下文。

建议：

  • 每行一个词。
  • 使用真实常见写法。
  • 不要把整段长文本当热词。
  • 专有名词、人名、产品名、英文缩写最适合。
  • 如果是表达风格问题，使用“常用提示词 / 场景说明”更合适。

自动热词候选没有候选

可能原因：

  • 自动热词候选未开启。
  • 本地历史为空。
  • LLM API 未配置。
  • 历史文本中没有高质量候选词。

处理方式：

  1. 在热词页开启自动热词候选。
  2. 使用几次语音输入积累本地历史。
  3. 在 API配置页配置并测试 LLM。
  4. 点击生成候选。

屏幕 OCR 结果有很多空格

从 0.1.62 起，VoxType 会在发送给当前 ASR 服务和可选大模型前，合并中文字符之间的多余空格。例如 屏 幕 OCR 上 下 文 会整理为 屏幕 OCR 上下文。英文缩写、快捷键、路径和数字间距会尽量保留。

如果测试预览仍然明显异常，先确认 Windows 已安装中文 OCR 语言能力，并尽量让参考文字清晰、不要被遮挡。屏幕包含敏感内容时，可在选项页切换为仅当前窗口或关闭屏幕 OCR 上下文；关闭后不影响录音、ASR 或粘贴主链路。

更新异常

如果应用内更新失败，可以到 GitHub Releases 手动下载最新安装包：

https://github.com/zkwi/VoxType/releases

安装新版本前通常不需要卸载旧版本。若安装器提示文件占用，退出托盘中的 VoxType 后重试。

日志和诊断报告

选项页和托盘菜单都可以打开日志；选项页可复制脱敏诊断报告。

反馈问题时建议提供：

  • VoxType 版本。
  • Windows 版本。
  • 问题发生步骤。
  • 是否能在记事本复现。
  • 脱敏诊断报告。

不要发送真实 API Key、热词、prompt、识别正文、屏幕 OCR 正文、自动热词历史、未脱敏日志或包含 Windows 用户名路径的截图。