常见问题

🔑 API 与密钥配置

API 密钥填错了？

MioSub 使用两种 API：

• Gemini API Key：用于翻译和润色（Google AI Studio 获取）
• OpenAI API Key：仅用于云端 Whisper 转录（OpenAI 平台获取）

如果你把 Gemini 密钥填到了 OpenAI 的位置（或反过来），会出现 500 Internal Server Error 或 contents is required 等错误。

解决方案：检查设置页面，确认两个密钥分别填在正确的位置。

使用 Gemini API 时报错？

如遇到以下问题：

403 Forbidden / 413 Request Entity Too Large / Unexpected token '<' / Failed to fetch / 504 Gateway Timeout / 429 Quota Exceeded 等

• 如使用的是第三方中转站：通常是中转站临时故障，或余额不足，或网络连接问题，请检查余额或稍后再重试。
• 如使用的是官方API：请检查是否超过了API请求限制，或是否正确配置了API密钥，或检查有无访问 Gemini 2.5 Flash/3 Flash/3 Pro的权限，或检测是否能连接到API服务。

提示「配额用尽」或「请求频率受限」？

使用 API 时可能遇到配额或频率限制错误，常见表现：

• insufficient_quota — API 余额不足
• 429 Too Many Requests — 请求频率过高
• 请求频率受限 / 配额用尽 — 中文错误提示

解决方案：

1. 检查 API 余额：登录对应平台（Google AI Studio / OpenAI）查看剩余额度
2. 降低并发数：在设置中减小「翻译并发数」，避免短时间内发送过多请求
3. 如果使用第三方 API 代理：检查代理商的余额和限额配置
4. 等待后重试：频率限制通常在几分钟后自动解除

提示「Invalid URL」？

自定义 API 端点的 URL 格式不正确。请确保：

• URL 以 http:// 或 https:// 开头
• 不包含多余的空格或特殊字符
• 末尾不要加 /（MioSub 会自动拼接路径）

🎬 视频处理

下载视频失败怎么办？

常见原因：

• 网络问题：确保能正常访问 YouTube/Bilibili
• 链接格式错误：使用标准视频链接，不支持播放列表
• 版权限制：B站番剧、付费内容无法下载
• 路径含特殊字符：Windows 用户名包含中文可能导致下载路径异常（详见路径问题）

解决方案：

1. 检查网络连接
2. 使用单个视频链接（非播放列表）
3. 如果错误信息包含乱码路径，参考下方路径问题的解决方案
4. Bilibili 提示 412 Precondition Failed：这是 B 站的反爬机制触发，通常在短时间内多次下载时出现。等待几分钟后重试，或使用其他工具下载视频再导入 MioSub

YouTube 下载到了错误语言的音轨？

部分 YouTube 视频提供了 AI 配音的多语言音轨。MioSub 在某些情况下可能下载到非原始语言的音轨（例如下载到德语配音而非英语原声）。

解决方案：

1. 请先更新到最新版本再尝试重新下载。
2. 如果问题持续，先用其他工具下载视频，再导入 MioSub 处理
3. 也可以加群（群号：1082480420）寻求帮助，并提供视频链接和日志

处理超长视频（>2 小时）时崩溃或失败？

超长视频处理需要大量内存，可能导致应用崩溃。

常见表现：

• 应用突然闪退，无错误提示
• 提示内存不足（OOM）
• 说话人分析或转录步骤失败

解决方案：

1. 更新到最新版本：v3.0.11+ 已优化长视频内存管理
2. 关闭其他占用内存的程序：确保有足够可用内存
3. 调低分段时长：将长视频分割为多个较短的片段分别处理

处理速度很慢？

可能原因：

• 使用的是 CPU 版 Whisper，速度较慢
• 网络延迟导致 API 调用缓慢

优化建议：

1. 使用较小的 Whisper 模型（Base 或 Small）
2. 配置 GPU 加速
3. 使用 Whisper API 而非本地模型

本地 Whisper 转录时 GPU/CUDA 报错？

使用 GPU 加速的本地 Whisper 时，可能遇到退出码 3221226505 并伴随 CUDA 相关错误信息。

常见原因：

• NVIDIA 显卡驱动版本过旧，不支持当前 CUDA 版本
• 显存不足（尤其使用 Large 模型时）
• 系统中存在多个 CUDA 版本冲突

解决方案：

1. 更新显卡驱动：前往 NVIDIA 官网 下载最新驱动
2. 使用较小的模型：将 Large 换为 Medium 或 Small 以减少显存占用
3. 回退到 CPU 模式：在设置中取消勾选 GPU 加速，使用 CPU 转录
4. 如果问题持续，使用云端 Whisper API 作为替代
5. 也可以加群（群号：1082480420）寻求帮助，并提供具体的错误信息、日志和硬件配置等

提示「音频解码失败」或音频提取报错？

处理某些视频时可能出现音频解码失败或 FFmpeg 提取错误（如退出码 2880417800 或 254）。

常见原因：

• 视频文件损坏或编码格式不受支持
• 视频容器格式异常（如非标准封装的 MKV/WebM）
• 系统临时目录空间不足
• 视频无音频轨道，通常是下载不完整导致

解决方案：

1. 尝试重新下载或转码视频：重新下载视频，或使用转码工具转为标准 MP4 格式后再导入
2. 检查磁盘空间：确保系统盘（临时目录所在盘）有足够剩余空间
3. 更新到最新版本：新版本持续改进音频提取的兼容性
4. 也可以加群（群号：1082480420）寻求帮助，并提供具体的错误信息、日志等

云端 Whisper 转录报错？

使用 OpenAI Whisper API 进行云端转录时，可能遇到以下错误：

📝 字幕与翻译

翻译结果始终是中文，无论选什么目标语言？

这是一个已确认并修复的 Bug。在 v3.0.13 之前的版本中，部分内部提示词和 API 参数硬编码了「简体中文」，导致即使选择了其他目标语言，输出仍然是中文。

解决方案：

1. 更新到 v3.0.14 或更高版本（此问题已彻底修复）
2. 如果使用一键生成模式，确认向导中的目标语言设置正确

术语表确认弹窗在编辑时突然消失？

如果你在术语表确认弹窗中编辑术语时，弹窗突然关闭且编辑内容丢失，这是因为按下了 Esc 键或点击了弹窗外部区域。

解决方案：

1. 更新到最新版本：此问题已修复，弹窗不再响应 Esc 和背景点击
2. 编辑术语后，请点击每个术语旁的「保存」按钮确认修改
3. 最后选择术语表，并点击底部的「确认添加」按钮完成整个流程

字幕时间轴不准确？

解决方案：

1. 启用 强制对齐功能 获得毫秒级精度
2. 在编辑器中手动微调时间轴
3. 检查是否源视频音频有问题
4. 也可以加群（群号：1082480420）反馈，并提供视频样本和生成的字幕以供分析（如果方便的话）

翻译质量不理想？

优化建议：

1. 选择正确的场景预设：动漫、电影、科技等不同风格
2. 使用术语表：确保专有名词翻译一致
3. 尝试润色功能：选中字幕后使用「润色翻译」
4. 添加批注：在编辑器中为特定字幕添加翻译指导批注，润色时会参考
5. 也可以加群（群号：1082480420）反馈，并提供视频样本和生成的字幕以供分析（如果方便的话）

🗂️ 文件与路径

路径含中文或特殊字符导致失败？

Windows 系统中，如果用户名、文件路径或临时目录包含中文或其他非 ASCII 字符，可能导致转录、下载等功能失败。

常见表现：

• 本地 Whisper 转录失败（退出码 3221226505）
• yt-dlp 下载失败，错误信息中出现乱码路径
• ffmpeg 处理报错

解决方案：

1. 更新到 v3.0.12 或更高版本（已修复大部分路径编码问题）
2. 如果仍有问题，尝试将视频文件移动到纯英文路径下再处理
3. 将 Whisper 模型存放在纯英文路径中
4. 将App安装或解压到纯英文目录中

提示「模型文件不存在」？

本地 Whisper 模型文件被移动、删除或所在的外部硬盘已断开。

解决方案：

1. 在设置中重新选择模型文件路径
2. 如果模型被误删，重新下载模型文件
3. 如果模型在外部硬盘上，确保硬盘已连接

处理过程中提示「文件未找到」？

视频文件在处理过程中被移动、重命名或删除。

解决方案：

• 处理期间不要移动或删除源视频文件
• 确保视频文件所在的磁盘有足够空间

🖥️ 软件使用

软件打不开 / 闪退？

Windows：

1. 确认系统是 Windows 10 或更高版本
2. 尝试以管理员身份运行
3. 检查是否被杀毒软件误拦截
4. 重新下载完整安装包

macOS：

1. 参考下方 macOS 相关 章节
2. 确保使用 v3.0.13 或更高版本（早期版本存在启动崩溃问题）

如何更新软件？

v3.0 支持自动更新检测。当有新版本时，应用会提示你更新。

如果自动更新失败（尤其是 macOS 用户）：

1. 访问 Releases 页面
2. 下载最新版本的安装包
3. 直接覆盖安装即可，设置会保留

设置丢失或无法保存？

可能原因：

• 配置目录被意外删除
• 便携版（Portable）运行在没有写入权限的目录

解决方案：

1. 重启应用，通常会自动重建配置目录
2. 确保应用所在目录有写入权限
3. 如果使用便携版，避免放在系统保护目录（如 C:\Program Files）

🍎 macOS 相关

macOS 提示「无法打开，因为无法验证开发者」或「此电脑不能读取你连接的磁盘」？

这是 macOS Gatekeeper 的安全提示。由于 MioSub 是开源软件，暂未购买 Apple 开发者证书进行签名。

方法一：右键打开（推荐）

1. 在 Finder 中找到 MioSub.app
2. 按住 Control 键并点击应用图标（或右键点击）
3. 在弹出菜单中选择「打开」
4. 在弹出的对话框中再次点击「打开」

首次打开后，系统会记住你的选择，之后可以正常双击打开。

方法二：系统偏好设置

1. 尝试打开应用（会被阻止）
2. 打开「系统偏好设置」>「安全性与隐私」>「通用」
3. 在底部会看到被阻止的应用，点击「仍要打开」

方法三：终端命令

打开终端，执行以下命令移除隔离（quarantine）属性：

# 移除 quarantine 属性（推荐）
xattr -d com.apple.quarantine /Applications/MioSub.app

# 或者清除所有扩展属性
xattr -cr /Applications/MioSub.app

macOS 本地 Whisper 转录闪退？

在 macOS 上使用本地 Whisper 转录时，应用可能闪退并报错 dylib not found 或 exit code -11（SIGSEGV）。

常见原因：

• whisper.cpp 动态库（.dylib）缺失或架构不匹配（Intel vs Apple Silicon）
• macOS 安全策略阻止加载未签名的动态库

解决方案：

1. 更新到 v3.0.13 或更高版本（已修复 dylib 打包和加载问题）
2. 确认下载了与你 Mac 架构匹配的版本（Intel: x64，Apple Silicon: arm64）
3. 如果仍有问题，使用云端 Whisper API 作为替代方案

🔄 升级与兼容

从 v2.x 升级后配置丢失？

v3.0 的配置文件位置和格式发生了变化，v2.x 的设置不会自动迁移。

解决方案： 参考 迁移指南 了解手动迁移步骤。

macOS / Linux 版本在哪下载？

v3.0 新增了 macOS 和 Linux 支持。前往 Releases 页面 下载：

• macOS：.dmg 文件
• Linux：.AppImage 文件

📧 还有问题？

如果以上内容没有解决你的问题：

1. 查看 Issue：GitHub Issues 可能已有解答
2. 提交 Issue：描述问题 + 错误截图 + 日志文件
3. 加入社区：在 QQ群（群号：1082480420）中交流