Escrcpy 偏好设置完全指南：从通用配置到设备、音频与摄像的 scrcpy 参数详解
【免费下载链接】escrcpy📱 Display and control your Android device graphically with scrcpy.项目地址: https://gitcode.com/GitHub_Trending/es/escrcpy
Escrcpy 是一款基于 scrcpy 的 Android 图形化投屏与控制桌面应用，而「偏好设置」正是驱动整个应用与底层 scrcpy 命令行协同工作的核心配置面板。本篇指南以 docs/zhHans/guide/preferences.md 为骨架，逐项讲解通用、视频、设备、窗口、音频、录制、输入与摄像八大类配置的实际含义，并结合仓库中的偏好模型源码（desktop/src/models/preference/）还原每一项在底层对应的 scrcpy 命令行参数、默认值与可选项。读完本文，你将能根据实际场景精准配置 Escrcpy，并理解每一项设置最终如何转化为 scrcpy 的启动参数。
偏好设置的结构与工作方式
在 Escrcpy 中，偏好设置并非孤立的表单，而是一套完整的「配置声明 → 表单渲染 → 持久化 → 参数组装」链路：
- 配置声明：
desktop/src/models/preference/目录下按common（通用）、video（视频）、device（设备）、window（窗口）、audio（音频）、record（录制）、input（输入）、camera（摄像）、launch（启动）等模块拆分，由 preference/index.js 统一汇总。每个配置项都带有label（i18n 文案键）、field（对应的 scrcpy 命令行参数）、type（渲染组件类型）、value（默认值）等元信息。 - 表单渲染：配置页 preference/index.vue 通过 preference-form/index.vue 按
type动态渲染Select、Switch、InputNumber、Input、PathInput、ColorPicker以及专用的VideoCodecSelect、AudioCodecSelect、DisplaySelect等组件（组件清单见 preference-form/components），因此新增配置项只需声明模型，无需改表单代码。 - 持久化与作用域：设置通过 store/preference 管理，配合 scope-select 区分全局作用域与设备作用域（部分参数可针对单台设备覆盖）。
- 参数组装：配置项中
field字段本身就是 scrcpy 的命令行参数名（如--max-size、--video-bit-rate），最终由 middleware/scrcpy 组装进 scrcpy 启动命令。这也解释了为什么下面几乎所有小节都能精确到「某个界面开关 = 某个 scrcpy 参数」。
通用配置（General）
通用配置定义应用本身的运行方式，模型定义见 preference/common/index.js：
| 配置项 | 类型 | 默认值 / 可选值 | 说明 |
|---|---|---|---|
| 主题风格（theme） | Select | system | 可选light/dark/system，跟随系统时为system |
| 语言选择（language） | Select | 当前系统语言 | 可选zh-CN、zh-TW、ja-JP、en-US、ru-RU、ar |
| 应用关闭行为（appCloseCode） | Select | -1 | -1询问、0退出、1最小化到托盘 |
| 文件存储路径（savePath） | PathInput | 桌面目录 | 目录选择器（openDirectory），用于存放截图、录屏等文件 |
| ADB 路径（adbPath） | PathInput | 内置默认路径 | 通过getDefaultAdbPath()自动探测，可手动指定 adb 可执行文件 |
| Scrcpy 路径（scrcpyPath） | PathInput | 内置默认路径 | 通过getDefaultScrcpyPath()自动探测 |
| Gnirehtet 路径（gnirehtetPath） | PathInput | 内置默认路径 | 通过getDefaultGnirehtetPath()自动探测 |
| Scrcpy 参数（scrcpyAppend） | Input（多行） | 空 | 以自由文本形式向 scrcpy 追加任意自定义参数，适合界面未覆盖的高级选项 |
| Gnirehtet 参数（gnirehtetAppend） | Input（多行） | 空 | 同上，追加给 gnirehtet 的额外参数 |
| 环境变量（environmentVariables） | Input（多行） | 空 | 为子进程注入自定义环境变量 |
| 自动连接设备（autoConnect） | Switch | true | 启动后自动尝试连接已发现的设备 |
| 自动执行镜像（autoMirror） | Switch | 关闭 | 连接设备后自动开始投屏镜像 |
| Gnirehtet 修复（gnirehtetFix） | Switch | 关闭 | 对 gnirehtet 反向后缀问题进行修复 |
| 调试模式（debug） | Switch | 关闭 | 开启后输出更详细的调试日志，便于排查问题 |
| 悬浮控制栏（floatControl） | Switch | 关闭 | 在设备画面外层叠加悬浮控制按钮 |
| 边栏隐藏（edgeHidden） | Switch | 关闭 | 窗口边缘悬停隐藏/呼出相关行为（源码中带有 tips 提示） |
| 开机自启（autoLaunch） | Switch | 关闭 | 应用随系统登录自动启动 |
| 并发上限（concurrencyLimit） | InputNumber | 5 | 取值范围 1～100，限制同时进行的镜像/操作任务数量 |
此外文档还列出了「使用系统终端」与「首选终端」两项：它们与项目的终端模块（terminal 页面 及 electron/modules/terminal）联动，控制命令执行时是调用应用内置终端还是系统外部终端。
视频（Video Control）
视频类配置直接映射到 scrcpy 的视频相关参数，模型定义见 preference/video/index.js：
| 界面项 | 对应参数 | 类型 | 说明 |
|---|---|---|---|
| 禁用视频传输 | --no-video | Switch | 只传输音频/控制通道，不传输视频流；值为false时不附加该参数 |
| 最大分辨率 | --max-size | InputNumber | 限制传输画面的最长边像素，值越小越省带宽 |
| 视频比特率 | --video-bit-rate | Input | 单位bps，控制视频码率 |
| 刷新频率 | --max-fps | InputNumber | 单位fps，限制采集帧率上限 |
| 视频编解码器 | --video-code | VideoCodecSelect | 预置「编码器 + 解码器」组合，如h264 & OMX.qcom.video.encoder.avc、h264 & c2.android.avc.encoder、h265 & OMX.qcom.video.encoder.hevc等，高通的 OMX 编码器与通用 C2 编码器均可选 |
| 显示方向 | --display-orientation | Select | 可选0°、90°、180°、270°及flip-0°、flip-90°、flip-180°、flip-270°（翻转方向） |
| 旋转角度 | --angle | InputNumber | 单位deg，对画面做额外角度旋转（源码中带 tips 说明） |
| 屏幕裁剪 | --crop | Input | 按宽:高:x:y格式裁剪设备画面 |
| 显示器选择 | --display-id | DisplaySelect | 多屏设备指定显示器编号，可过滤/手动输入 |
| 视频缓冲区 | --video-buffer | InputNumber | 单位ms，视频解码缓冲时长，值越大越流畅但延迟越高 |
| 接收端（v4l2）缓冲区 | --v4l2-buffer | InputNumber | 单位ms，Linux v4l2 接收端缓冲时长 |
值得说明的是：模型中还隐藏了--video-source（display/camera）、--video-codec、--video-encoder等进阶字段（hidden: true），它们由「视频编解码器」这类定制组件在后台拆分处理，或为未来版本保留，界面暂不直接暴露。
设备（Device）
设备类配置控制 Android 设备端的电源与显示行为，模型定义见 preference/device/index.js：
| 界面项 | 对应参数 | 说明 |
|---|---|---|
| 显示触摸点 | --show-touches | 在设备画面中显示触摸位置指示点 |
| 保持唤醒状态 | --stay-awake | 投屏期间阻止设备休眠 |
| 控制时关闭屏幕 | --turn-screen-off | 开始投屏后立即关闭设备屏幕 |
| 控制结束后关闭屏幕 | --power-off-on-close | 退出投屏时关闭设备屏幕 |
| 禁用控制时自动亮屏 | --no-power-on | 投屏过程中不自动点亮设备屏幕 |
| 屏幕关闭超时 | --screen-off-timeout | InputNumber，单位s，控制屏幕自动关闭的超时时间 |
| 保持活跃 | --keep-active | 维持设备处于活跃状态（避免连接被系统回收） |
关于「模拟辅助显示器」：它对应设备显示器管理能力，与 utils/device/display 模块相关，用于在多显示器或虚拟显示器场景下模拟辅助屏，具体行为以设备与 scrcpy 版本支持为准。
窗口（Window）
窗口类配置控制投屏窗口的尺寸、位置与显示样式，模型定义见 preference/window/index.js：
| 界面项 | 对应参数 | 说明 |
|---|---|---|
| 窗口宽度 | --window-width | InputNumber（模型中hidden: true，主要交由窗口排布功能管理） |
| 窗口高度 | --window-height | 同上 |
| 窗口 X 坐标 | --window-x | 同上 |
| 窗口 Y 坐标 | --window-y | 同上 |
| 无边框模式 | --window-borderless | 去掉系统窗口边框 |
| 全屏模式 | --fullscreen | 以全屏方式启动投屏窗口 |
| 窗口置顶 | --always-on-top | 窗口始终保持在最上层 |
| 禁用屏幕保护 | --disable-screensaver | 投屏期间阻止宿主机屏保/休眠 |
| 窗口背景色 | --background-color | ColorPicker 颜色选择器，设置窗口底色 |
模型源码中四个尺寸/坐标字段均为hidden: true，这是因为 Escrcpy 提供了更强大的可视化窗口排布功能（多窗口网格、自动排布、布局保存），详见 docs/zhHans/guide/window-arrangement.md，这也是实际控制窗口位置的主要入口。
音频（Audio）
音频类配置映射 scrcpy 音频相关参数，模型定义见 preference/audio/index.js：
| 界面项 | 对应参数 | 说明 |
|---|---|---|
| 禁用音频传输 | --no-audio | 不传输设备音频 |
| 保留设备音频 | --audio-dup | 音频在投屏到电脑的同时，设备扬声器继续发声（不静音设备） |
| 音频源选择 | --audio-source | 下拉选项非常完整：default、playback、mic、mic-unprocessed、mic-camcorder、mic-voice-recognition、mic-voice-communication、voice-call、voice-call-uplink、voice-call-downlink、voice-performance，覆盖录音、通话上下行等 Android 音频源 |
| 音频编解码器 | --audio-code | AudioCodecSelect，预置opus & c2.android.opus.encoder、aac & c2.android.aac.encoder、aac & OMX.google.aac.encoder及raw原始音频 |
| 音频比特率 | --audio-bit-rate | Input，单位bps |
| 音频缓冲区 | --audio-buffer | InputNumber，单位ms |
| 音频输出缓冲区 | --audio-output-buffer | InputNumber，单位ms，宿主机播放侧缓冲 |
与视频类似，模型中还隐藏了--audio-codec、--audio-encoder两个拆分字段，用于在定制音频编解码器选择时分别下发编解码器与编码器。
录制（Recording）
录制配置用于控制录屏行为，模型定义见 preference/record/index.js，包含：
- 录制视频格式：选择录制的容器格式（如 mp4/mkv）；
- 录制视频方向：录制流的画面方向，可与播放方向解耦；
- 录制时长：设定自动停止录制的时长上限；
- 禁用视频回放：录制时不在本地实时预览；
- 禁用音频回放：录制时不在本地播放音频。
这组配置与 scrcpy 的录制参数一一对应，详细的录制参数语义（格式、时长、回放开关）可参考仓库中的 scrcpy 录制参考文档。
输入（Input）
输入类配置控制鼠标、键盘与游戏手柄在投屏画面中的注入方式，模型定义见 preference/input/index.js：
- 鼠标模式：选择鼠标事件注入为触摸还是遥控器（如 disabled / 触控 / 遥控两种模式）；
- 鼠标绑定：自定义鼠标按键与 Android 操作的绑定关系；
- 键盘模式：选择键盘注入方式（SDK / AOA / UHID 等）；
- 键盘注入方式：决定按键事件在按下、抬起还是询问时注入，对应 preference-form 的 select-keyboard-inject 组件；
- 游戏手柄设置：启用/配置游戏手柄事件注入。
每种输入方式的原理与限制，可分别参考 鼠标、键盘 与 游戏手柄 参考文档。
摄像（Camera）
摄像类配置用于将 Android 设备摄像头作为视频源进行投屏，模型定义见 preference/camera/index.js：
- 摄像头源选择：选择前摄 / 后摄 / 外接摄像头；
- 摄像头尺寸：设置摄像头采集分辨率；
- 摄像头比例：设置画面宽高比（如 4:3、16:9）；
- 摄像头帧率：设置采集帧率上限，对应 preference-form 的 select-camera-fps 组件；
- 配套的缩放相关组件见 slider-camera-zoom。
摄像头投屏需要设备与 scrcpy 版本支持，详细约束可参考 摄像头参考文档。
配置的生效、持久化与进阶使用
- 参数优先级：界面配置项、
scrcpyAppend自定义参数与环境变量最终都会汇入 scrcpy 启动命令（组装逻辑位于 electron/middleware/scrcpy）。当某项未设置时，模型中的value: undefined表示「不附加该参数」，从而交给 scrcpy 使用其内置默认值；unset: [false]则表示布尔开关在关闭时干脆不传参，避免覆盖 scrcpy 默认行为。 - 作用域覆盖：借助 scope-select，部分配置可以按「全局 / 单设备」分级生效，适合为不同设备保存不同参数组合。
- 与窗口排布协同：窗口的宽高与坐标虽已内置为 scrcpy 参数，但 Escrcpy 推荐使用可视化排布（见 window-arrangement.md）来管理多窗口布局，设置页保留底层参数以便需要精确控制的场景。
小结
正如文档开头标注的「持续完善中」，Escrcpy 的偏好设置随着 scrcpy 能力演进不断扩充，但整体设计保持了一致性：每一个界面配置项都对应一个明确的 scrcpy 命令行参数。借助 preference 模型目录 这份「参数字典」，你可以快速反查任意设置项底层的真实参数与默认值，也可以在scrcpyAppend中直接写入界面未覆盖的高级参数，实现界面之外的精细化调优。本指南所覆盖的八类配置已完整承接 preferences.md 的全部条目，并补充了源码级的参数映射与默认值，可作为日常配置与二次开发的双向参考。
【免费下载链接】escrcpy📱 Display and control your Android device graphically with scrcpy.项目地址: https://gitcode.com/GitHub_Trending/es/escrcpy
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
