26.10.09 14:26

🔧 故障排查指南

FastMediaSorter v2 的最新故障排查指南。当问题与所选的构建路径（Standard、Lite、Photos、Legacy 或 XR / noLegal）有关时，请使用 FLAVOR_MATRIX.md 中的权威版本对照表。

连接问题

❌ “无法连接到 SMB 服务器”

可能原因：

  1. 网络不对 - 手机必须与 NAS 在同一个 Wi-Fi 上
  2. 地址格式不对 - 两种格式都试一下：
    • \\192.168.1.100\share
    • smb://192.168.1.100/share
  3. 防火墙拦截 - 检查 NAS 的防火墙设置
  4. SMB 版本不匹配 - 有些 NAS 仍然要求 SMB v2/v3 兼容模式；如果服务器只开放了老旧的 SMB 设置，请更新服务器

解决方法：

❌ “SFTP 连接超时”

可能原因：

  1. 端口不对（默认：22）
  2. SSH 服务未运行
  3. 防火墙拦截

解决方法：

1. 先在电脑上用 SSH 客户端测试：
   ssh username@192.168.1.100
2. 检查 SSH 服务是否在运行
3. 核对设置中的端口

❌ “Google Drive 登录失败”

解决方法：

  1. 清除应用数据：设置 → 应用 → FastMediaSorter → 清除数据
  2. 重新安装应用
  3. 检查 Google 账号设置 → 安全性 → 第三方应用

❌ “OneDrive 登录失败”

解决方法：

  1. 检查 Microsoft 账号状态
  2. 清除应用数据：设置 → 应用 → FastMediaSorter → 清除数据
  3. 检查 Microsoft 账号设置 → 隐私 → 应用和服务

❌ “Dropbox 登录失败”

解决方法：

  1. 检查 Dropbox 账号状态
  2. 清除应用数据：设置 → 应用 → FastMediaSorter → 清除数据
  3. 检查 Dropbox 账号设置 → 安全性 → 已连接的应用

性能问题

❌ “应用运行缓慢/卡顿”

对于大文件夹（5000+ 文件）：

  1. 编辑文件夹（按资源）→ 启用 “Disable thumbnails”
  2. 使用筛选减少显示的文件数量
  3. 关闭其他应用以释放内存

对于网络文件夹：

  1. 检查 Wi-Fi 信号强度
  2. 减小缩略图缓存大小
  3. 如非必要，将 “Scan subdirectories” 设为关闭

❌ “缩略图无法加载”

本地文件：

网络文件：

文件操作错误

❌ “复制失败：Permission denied”

本地文件：

网络文件：

❌ “无法删除文件”

可能原因：

  1. 文件已在其他应用中打开
  2. 没有写入权限
  3. 文件受系统保护

解决方法：

❌ “移动操作失败”

跨协议移动（例如 本地 → SMB）：

解决方法：

应用崩溃

❌ “打开播放器时应用崩溃”

常见原因：

  1. 视频文件损坏
  2. 不支持的编解码器
  3. 文件过大（>4GB）

解决方法：

❌ “媒体文件无法播放或没有声音”

问题： 视频加载了但显示黑屏，或播放时没有声音。

解决方法：

  1. 点按顶部工具栏中的 ⓘ（Info）按钮
  2. 点按 “Open in External Player”
  3. 选择一个专门的播放器

这会使用 Secondary Player 功能，将不受支持的编解码器交给其他应用处理。

❌ “应用启动时崩溃”

解决方法：

  1. 清除应用缓存：设置 → 应用 → FastMediaSorter → 清除缓存
  2. 若仍然发生：清除应用数据（⚠️ 会丢失设置）
  3. 最后手段：重新安装应用

界面/显示问题

❌ “触控区域不起作用”

检查是否已启用： 设置 → 播放器 → “Show touch zones hint on first run” = 开

使其可见： 设置 → 播放器 → “Always show touch zones overlay” = 开

❌ “命令面板按钮太小”

解决方法： 设置 → 播放器 → “Compact player buttons” = 关

这会让所有按钮和间距的尺寸翻倍。

❌ “深色主题不起作用”

应用跟随系统主题：

数据问题

❌ “收藏不见了”

收藏保存在本地：

预防措施：

❌ “回收站文件夹不断变大”

删除的文件会进入 .trash/ 文件夹，并一直保留在那里，直到你手动清空。

解决方法：

  1. 设置 → 管理 → File deletion and trash
  2. 或手动删除 .trash/ 文件夹

仍然有问题？

检查日志

  1. 设置 → 管理 → “Show detailed errors” = 开
  2. 重现问题
  3. 检查 logcat 输出

报告 Bug

请附上以下信息：

提交： GitHub Issues

翻译与 EPUB 问题

❌ “翻译不起作用或卡住”

可能原因：

  1. 模型缺失： 应用未能下载 OCR 模型。
  2. 没有网络： 首次运行需要联网下载模型。
  3. 存储空间已满： 没有空间存放模型（约 50 MB）。

解决方法：

  1. 检查网络连接。
  2. 进入 设置 → 媒体 → 其他
  3. 将 “Enable Translation” 关闭再重新打开。
  4. 尝试将 Source Language 切换为 “Auto”。

❌ “EPUB 电子书无法打开”

可能原因：

  1. DRM 保护： 应用只支持无 DRM 的 EPUB。
  2. 文件损坏： 文件可能不完整。
  3. 文件过大： 网络较慢时，超过 100MB 的文件可能会超时。

解决方法：

  1. 确认该文件能在其他阅读器中打开。
  2. 如果是网络/云文件，先尝试手动下载它。
  3. 确保文件扩展名正好是 .epub。

网络直播流问题

直播流无法启动 / 播放一秒后就停止

可能原因：

  1. 该网址已失效，或被重定向到了另一种协议。
  2. 服务器要求身份验证（不支持）。
  3. 明文 http:// 被 VPN 或企业网络拦截。

解决方法：

目录导入的加载动画不停止/卡住

应用对目录下载采用了快速超时机制。如果加载动画卡住超过约 15 秒，很可能是主机无法访问。请检查你的网络连接后重试。对话框会在超时时自动关闭 - 不会无限期卡住。

HLS / DASH / RTSP 显示 “unsupported” 信息

在 Standard、Legacy 和 XR / noLegal 中，这三种协议均受支持，因此该信息指向的是该流本身或其编解码器，而不是构建版本的问题。Lite 和 Photos 根本没有 Streams 界面，所以在那里一开始就无法添加任何流。

菜单或设置中看不到 Streams 选项

ICY 正在播放的元数据不显示

ICY 元数据需要一个会发送 Icy-MetaData: 1 头的 Icecast/Shoutcast 流。没有 ICY 头的普通 http mp3 流不会在底部迷你控制条中显示电台/曲目信息。这是服务器端的限制。

内容问题

❌ “看不到文本或 PDF 文件”

解决方法：

  1. 检查 设置 → 媒体 → 文档
  2. 确保 “Support Text Files” 和 “Support PDF Files” 已启用。
  3. 检查主界面上的筛选器（漏斗图标），确保它们已被选中。
  4. 重新扫描该文件夹（下拉刷新）。

已知限制

最后更新： 2026-06-05
版本： 当前公开文档集