scrcpy 设备控制选项深度解析屏幕电源管理与 Android 应用启动实战【免费下载链接】scrcpyDisplay and control your Android device项目地址: https://gitcode.com/GitHub_Trending/sc/scrcpyscrcpy 提供了一组直接作用于 Android 设备本身而非仅作用于镜像窗口的命令行选项涵盖保持唤醒、调整熄屏超时、息屏运行、触摸指示、电源行为控制以及启动应用等场景。本文基于 scrcpy 官方文档 doc/device.md结合客户端 C 源码app/src与 Android 端 Java 源码server/src/main/java完整梳理这些选项的用法、底层实现原理以及不经过 scrcpy 时的纯 ADB 手动替代命令帮助读者在投屏、演示、后台录制等场景中灵活控制设备状态。Stay awake保持设备唤醒--stay-awake短选项-w用于在 scrcpy 运行期间防止设备在插电状态下因超时而熄灭scrcpy --stay-awake scrcpy -w关键行为与限制关闭 scrcpy 时会恢复初始状态设备不会永久被改为永不熄屏仅对插电设备生效如果设备仅通过 TCP/IP 连接未插电该选项无效这是 Android 系统的固有行为。源码级原理该选项的本质是修改 Android 的全局设置stay_on_while_plugged_in。从源码结构看客户端在 app/src/server.c#L363-L365 中将参数stay_awaketrue传给 Android 端服务器后者在 server/src/main/java/com/genymobile/scrcpy/CleanUp.java 中完成实际的设置变更启动时通过Settings.getAndPutValue将stay_on_while_plugged_in写入AC | USB | WIRELESS三种充电位的组合值即7并记录旧值退出清理时若旧值与新值不同才回写恢复并打印Restoring stay awake日志。手动等效命令不走 scrcpy可以直接用 ADB 修改同一设置项# 查看当前值 adb shell settings get global stay_on_while_plugged_in # 对 AC/USB/无线充电器全部启用 adb shell settings put global stay_on_while_plugged_in 7 # 关闭 adb shell settings put global stay_on_while_plugged_in 0其中7是三种充电类型位掩码1 AC、2 USB、4 无线的叠加与CleanUp.java中BATTERY_PLUGGED_AC | BATTERY_PLUGGED_USB | BATTERY_PLUGGED_WIRELESS的取值一致。Screen off timeout调整自动熄屏延时Android 屏幕会在一段时间无操作后自动熄灭。在 scrcpy 运行期间可以临时更改这个延时scrcpy --screen-off-timeout300 # 300 秒5 分钟退出 scrcpy 时初始值会被恢复。秒与毫秒的单位换算需要注意一个易踩的坑screen_off_timeout这一 Android 系统设置项的原始单位是毫秒而 scrcpy 命令行参数使用秒。源码中该换算发生在 app/src/server.c#L366-L370if (params-screen_off_timeout ! -1) { assert(params-screen_off_timeout 0); uint64_t ms SC_TICK_TO_MS(params-screen_off_timeout); ADD_PARAM(screen_off_timeout% PRIu64, ms); }即客户端把秒转换为毫秒后传给服务器。参数合法性校验在 app/src/cli.c 的parse_screen_off_timeout中完成取值范围被限制在 0 至约0x7FFFFFFF / 1000秒保证乘以 1000 后不会溢出 31 位整数。Android 端解析逻辑见 server/src/main/java/com/genymobile/scrcpy/Options.java#L396-L400小于-1的值会抛出IllegalArgumentException。手动等效命令# 查看当前值毫秒 adb shell settings get system screen_off_timeout # 设置新值单位毫秒 adb shell settings put system screen_off_timeout 30000恢复逻辑与 stay-awake 类似同样在 CleanUp.java 中仅在旧值与新值不同时才记录待恢复值退出时回写并打印Restoring screen off timeout。Turn screen off息屏状态下镜像有时希望设备屏幕保持关闭仅在 PC 上查看镜像例如夜间挂机、隐藏设备侧画面scrcpy --turn-screen-off scrcpy -S # 短选项也可以在任何时候通过快捷键切换按MODo关闭屏幕按MODShifto重新点亮完整快捷键见 doc/shortcuts.md。启动时息屏的实现时序从源码看客户端在控制链路就绪后发送SC_CONTROL_MSG_TYPE_SET_DISPLAY_POWERon false控制消息相关代码位于 app/src/scrcpy.c#L889-L895// If the device screen is to be turned off, send the control message after // everything is set up if (options-control options-turn_screen_off) { struct sc_control_msg msg; msg.type SC_CONTROL_MSG_TYPE_SET_DISPLAY_POWER; msg.set_display_power.on false;注意两个前提该选项依赖控制功能开启--no-control下会报错Cannot request to turn screen off if control is disabled见 app/src/cli.c且在 OTG 模式下同样被禁止。Android 端服务器侧还有一个脏技巧源码中注释为 dirty hack设备首次点亮是异步的因此 server/src/main/java/com/genymobile/scrcpy/control/Controller.java#L202-L210 中会确保息屏消息先被缓存、待设备真正点亮后再执行避免消息因设备尚未上电而失效。POWER 键的特殊处理在 Android 上物理POWER键的行为是点亮屏幕。出于配合息屏使用的便利性scrcpy 通过镜像发送的POWER键右键菜单或MODp会在小延迟后尽力重新熄灭屏幕best effort而物理POWER键仍会正常点亮。这一尽力熄灭逻辑的源码位于 Controller.java#L341-L347private boolean injectKeycode(int action, int keycode, int repeat, int metaState) { if (keepDisplayPowerOff action KeyEvent.ACTION_UP (keycode KeyEvent.KEYCODE_POWER || keycode KeyEvent.KEYCODE_WAKEUP)) { assert displayId ! Device.DISPLAY_ID_NONE; scheduleDisplayPowerOff(displayId); } ... }即当keepDisplayPowerOff状态激活时POWER或WAKEUP键抬起后会调度一次延迟熄屏。息屏 防休眠组合如果还想防止设备整体休眠进入深度睡眠会导致镜像中断可以组合使用scrcpy --turn-screen-off --stay-awake scrcpy -Sw # 短选项组合手动等效命令从 Android 15 开始也可以直接用 shell 命令控制屏幕电源0为主显示# 关闭屏幕 adb shell cmd display power-off 0 # 点亮屏幕 adb shell cmd display power-on 0Show touches物理触摸指示做演示时可能希望在物理设备上显示手指触摸点。Android 在开发者选项中提供了该功能scrcpy 可在启动时开启它并在退出时恢复原值scrcpy --show-touches scrcpy -t # 短选项注意它只显示物理触摸手指在设备屏幕上的触摸不显示通过 scrcpy 注入的鼠标/键盘触摸。源码上CleanUp.java 在启动阶段调用Settings.getAndPutValue(TABLE_SYSTEM, show_touches, 1)并记录旧值仅当旧值不是1时才在退出清理阶段将其恢复为0避免覆盖用户原有的开启状态。手动等效命令# 查看当前值 adb shell settings get system show_touches # 开启 adb shell settings put system show_touches 1 # 关闭 adb shell settings put system show_touches 0Power off on close退出时熄灭屏幕默认情况下scrcpy 退出时会恢复屏幕电源状态。若希望关闭 scrcpy 时直接让设备屏幕熄灭例如演示结束即黑屏scrcpy --power-off-on-close实现上该布尔选项随CleanUp清理进程传递参数powerOffScreen退出时 CleanUp.java 会调用Device.powerOffScreen(targetDisplayId)而非恢复亮屏。与 turn-screen-off 相同该选项同样要求控制功能开启。Power on on start禁止启动时自动点亮默认行为是启动 scrcpy 时若设备屏幕已熄灭服务器会注入一次POWER键将设备点亮保证镜像内容可见。该自动点亮逻辑见 Controller.java#L202-L210// on start, power on the device if (powerOn displayId 0 !Device.isScreenOn(displayId)) { Device.pressReleaseKeycode(KeyEvent.KEYCODE_POWER, displayId, Device.INJECT_MODE_ASYNC);如果希望保留息屏状态例如配合--turn-screen-off或后台挂机可以禁用这一行为scrcpy --no-power-on对应 Android 端选项解析为 Options.java#L429-L431 中的power_on键默认为true。Start Android app启动设备应用列出已安装应用scrcpy --list-apps按包名启动应用scrcpy --start-apporg.mozilla.firefox启动动作的链路客户端在控制通道建立后发送SC_CONTROL_MSG_TYPE_START_APP消息应用名最长 255 字节见 app/src/scrcpy.c#L928-L942 与 app/src/control_msg.c 的序列化实现。该消息携带的name字段并非只接受纯包名——前缀修饰符的处理逻辑在 Android 端完成。前缀修饰符前缀先强制停止再启动保证应用处于干净状态scrcpy --start-apporg.mozilla.firefox?前缀按应用名称匹配前缀匹配、大小写不敏感免去查包名的麻烦scrcpy --start-app?firefox注意获取应用名称需要在设备上枚举全部应用可能耗时数秒因此文档建议优先直接传包名。两个前缀可以组合顺序固定为?scrcpy --start-app?firefox这些用法的完整帮助文本可在 app/src/cli.c#L881-L895 的--start-app选项描述中看到与本文示例一致。该选项同样要求控制功能开启--no-control时会被拒绝。与虚拟显示组合--start-app与 虚拟显示 配合可以把应用跑在一个独立的新显示上实现多任务并行式使用scrcpy --new-display1920x1080 --start-apporg.videolan.vlc此时--start-app指定的应用会出现在新建的 1920x1080 虚拟显示中而不干扰主屏幕。小结选项短选项作用对应系统设置/机制--stay-awake-w插电时不熄屏退出恢复stay_on_while_plugged_inglobal--screen-off-timeout秒-临时修改熄屏延时退出恢复screen_off_timeoutsystem毫秒--turn-screen-off-S启动即息屏MODo 切换SET_DISPLAY_POWER控制消息--show-touches-t显示物理触摸点退出恢复show_touchessystem--power-off-on-close-退出时直接熄屏CleanUp 进程powerOffScreen--no-power-on-禁止启动时自动点亮跳过注入KEYCODE_POWER--start-appname-启动应用支持?前缀START_APP控制消息--list-apps-列出已安装应用服务器枚举包名从 CleanUp.java 的整体设计可以看到一条统一的原则所有启动时修改设备状态的选项都会先通过getAndPutValue原子地读取旧值并写入新值仅当新旧值不同时才在退出清理阶段回写——这样既保证了运行时行为又不会污染设备的原有配置。理解了这条主线再对照 doc/shortcuts.md 的运行时快捷键就能覆盖 scrcpy 对设备状态的全部控制手段。【免费下载链接】scrcpyDisplay and control your Android device项目地址: https://gitcode.com/GitHub_Trending/sc/scrcpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考