故障排除

连接故障排除流程图

scrcpy 最常见的问题与客户端和 Android 设备之间的连接有关。下图显示了连接流程和潜在的故障点。

显示故障排除

显示问题通常涉及视频编码/解码或渲染方面的问题。下图显示了视频管道和潜在的故障点。

常见的显示问题

问题	可能原因	解决方案
黑屏	视频解码器未初始化	使用 `--encoder` 选项尝试不同的编码器
MediaCodec 异常	不兼容的编码器	使用 `--encoder` 指定不同的编码器（例如，`--encoder=h264`）
低帧率	高分辨率伴随不足的带宽	使用 `--max-size` 降低分辨率或使用 `--bit-rate` 降低比特率
Wayland 渲染问题	SDL 默认使用 X11	设置 `SDL_VIDEODRIVER=wayland` 环境变量
KWin 合成器崩溃	Plasma 桌面兼容性问题	在 KWin 中禁用“阻止合成”

来源：FAQ.md181-211

控制故障排除

输入控制问题涉及键盘和鼠标事件从客户端到 Android 设备的翻译和注入。

来源：FAQ.md152-179

常见的控制问题

问题	可能原因	解决方案
无输入工作	缺少权限	在开发者选项中启用“USB 调试（安全设置）”
特殊字符无效	仅 ASCII 文本注入	将键盘模式更改为 HID，使用 `--keyboard=physical`
鼠标点击未注册	输入模拟不允许	在开发者选项中检查“允许模拟输入”权限
键盘布局问题	物理键盘模拟限制	使用 `--keyboard=physical` 和适当的选项

来源：FAQ.md152-179

客户端-服务器连接诊断

在排除连接问题时，理解客户端-服务器通信路径至关重要。

来源：FAQ.md9-133 FAQ.md214-225

OTG 问题

随插即用 (OTG) 功能允许 scrcpy 使用 USB HID 模式而不是 ADB 来控制设备。

Windows OTG 故障排除

在 Windows 上使用 --otg、--keyboard=aoa 或 --mouse=aoa 选项时，驱动程序问题很常见。解决这些问题的步骤包括

检查设备是否在设备管理器中显示
安装设备的正确 USB 驱动程序
连接前确保设备处于附件模式

常见错误：“找不到任何 USB 设备”通常表示驱动程序问题。

来源：FAQ.md136-149

高级故障排除

ADB 版本冲突

如果您遇到类似错误

adb server version (41) doesn't match this client (39); killing...

这表示使用了多个 ADB 版本。解决方案

使用 `ADB` 环境变量指定 ADB 路径
确保 scrcpy 和其他工具之间的 ADB 版本一致

设置 ADB 路径的示例

来源：FAQ.md94-121

设备断开连接问题

如果 scrcpy abrupt stops with "Device disconnected" messages，请检查

USB 线缆质量和连接
USB 端口供电
Android 设备 USB 设置

这通常是硬件或连接问题，而不是软件问题。

来源：FAQ.md124-133

常见错误消息及解决方案

错误消息	可能的原因	解决方案
"找不到任何 ADB 设备"	ADB 未检测到设备	检查 USB 调试、驱动程序、线缆连接
"设备未授权"	设备上未授予权限	在设备上接受 USB 调试提示
"多个 ADB 设备"	已连接多个设备	使用 `-s`、`-d` 或 `-e` 选项指定设备
"主线程 [main,5,main] 发生异常"	MediaCodec 错误	使用 `--encoder` 选项尝试不同的编码器
"adb 服务器版本不匹配"	ADB 版本冲突	使用一致的 ADB 版本或设置 `ADB` 环境变量
"'adb reverse' 失败"	TCP/IP 连接限制	正常的后备行为，应自动工作
"找不到任何 USB 设备"（使用 OTG 时）	Windows 上的驱动程序问题	安装正确的 USB 驱动程序并检查设备管理器

来源：FAQ.md10-235

系统化调试方法

对于上面未涵盖的问题，请遵循此系统化的调试方法

检查版本：始终使用最新的 scrcpy 版本
检查日志：使用 `--verbose` 选项运行 scrcpy 以获取详细日志
隔离组件：测试问题是客户端还是服务器端
验证要求：确保所有依赖项都已正确安装
测试最小配置：使用最少的选项运行 scrcpy 以隔离问题
检查设备兼容性：检查问题是否是特定于设备的

来源：FAQ.md5-8