- 文档
- 教程
【免费下载链接】linux-command
Linux命令大全搜索工具，内容包含Linux命令手册、详解、学习、搜集。https://git.io/linux
xrandr 是 Linux 桌面环境下管理屏幕分辨率、刷新率与多显示器布局的核心命令行工具，它基于 X Window 系统的 RandR（Rotate and Resize，旋转与缩放）扩展实现运行时动态调整屏幕。本篇指南以本项目 command/xrandr.md 文档为骨架，完整讲解其语法、选项与真实输出解读，并覆盖克隆屏幕、扩展分屏、指定分辨率刷新率等高频实战场景，读完即可用一条命令解决显示器配置问题。
RandR 扩展与 xrandr 的关系
RandR（Rotate and Resize，旋转与缩放）是一个 X Window 系统扩展，它允许客户端动态调整屏幕：缩放（改变分辨率）、旋转、翻转，而无需重启 X Server。xrandr 正是官方针对该扩展提供的命令行配置工具，所有通过 xrandr 完成的调整最终都会转化为对 RandR 扩展的请求，由 X Server 与显卡驱动协同完成实际显示输出切换。
在绝大多数发行版（Debian/Ubuntu、Fedora、Arch 等）中，xrandr 随x11-xserver-utils等基础软件包默认安装，可通过xrandr --version确认版本。注意：该工具面向 X11 会话（$DISPLAY环境变量），Wayland 会话下需使用 wlr-randr、kanshi 等替代方案，这是使用前需要明确的适用前提。
语法结构
xrandr(选项)(参数)- 选项（option）：以
--开头的操作指令，用于指定对哪个输出设备执行何种操作； - 参数：显示设备编号（输出名称），例如
VGA-1、HDMI-1、DP-1等，由 X Server 根据实际连接的物理接口生成。
不携带任何选项直接执行xrandr，则进入查询模式：列出所有输出设备、连接状态、当前与可用的分辨率模式，这是每次配置前的第一步。
选项详解
原文档给出了核心选项，下表在完整继承的基础上补充了取值范围与行为说明：
| 选项 | 作用 | 说明 |
|---|---|---|
--auto | 以系统最大/最佳分辨率输出 | 对指定输出启用其首选模式（preferred mode），即硬件推荐的分辨率与刷新率 |
--off | 将指定输出设备设置为关闭 | 关闭后该显示器黑屏且不再参与桌面布局，常用于多屏时停用不需要的屏幕 |
--output | 指定操作的目标输出设备 | 后面必须跟设备名称，如--output HDMI-1 |
--mode | 设置分辨率 | 值为查询结果中列出的模式名，如--mode 1920x1080 |
--rate | 设置刷新率 | 值为该分辨率下支持的刷新率，如--rate 60，须与--mode配合使用 |
--right-of | 放置在主显示器右侧 | 后跟另一输出名称，如--right-of VGA1 |
--left-of | 放置在主显示器左侧 | 与--right-of方向相反 |
--above | 放置在主显示器上方 | 竖直方向布局 |
--below | 放置在主显示器下方 | 竖直方向布局 |
常用补充选项
在标准 xrandr 手册中，以下选项与上述核心选项同属日常高频用法，配合使用可完成更完整的桌面布局管理：
--rotate normal|left|right|inverted：旋转屏幕（正常 / 左旋 90° / 右旋 90° / 倒置 180°），适配竖屏显示器；--reflect normal|x|y|xy：镜像翻转画面，可用于投影拼接场景；--primary：将指定输出设为主显示器（桌面图标与任务栏所在屏幕）；--same-as：与另一输出克隆（镜像）显示；--pos x,y：直接指定输出在虚拟桌面中的坐标位置；--scale x,y：缩放输出画面，例如--scale 1.5x1.5可将低分辨率内容放大输出；--dpi：设置屏幕 DPI 值；--brightness：设置亮度（0.0～1.0）；--gamma：设置伽马校正值；--fb widthxheight：设置整个虚拟桌面的帧缓冲尺寸；--dryrun：只打印将要执行的改动而不实际生效，适合配置前演练；--verbose：输出详细调试信息。
参数：显示设备编号
xrandr 的参数是显示设备编号，即各输出接口的名称标识。它们不是任意起的名，而是由 X Server 根据硬件探测结果生成的，常见形式包括：
VGA-1/VGA-0：模拟 VGA 接口；HDMI-1/HDMI-2：HDMI 接口；DP-1：DisplayPort 接口；DVI-I-1：DVI 接口；LVDS-1/eDP-1：笔记本内置屏幕；DP-1-1/DP-1-2：部分多路输出的独显（如 NVIDIA 用 DP 口扩展出的子接口）。
确切名称请以xrandr查询输出的第一列（如HDMI-1 connected ...）为准，错误名称会提示cannot find output。
实战一：列出可用设备及其模式（查询模式）
配置的第一步永远是查询。直接执行：
xrandr典型输出（原文档实例）：
Screen 0: minimum 320 x 200, current 3200 x 1080, maximum 8192 x 8192 VGA-1 disconnected (normal left inverted right x axis y axis) HDMI-1 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 531mm x 299mm 1920x1080 59.93 + 60.00* 50.00 59.94 1920x1080i 60.00 50.00 59.94 1680x1050 59.88 …输出字段解读
- 第一行 Screen 0：虚拟屏幕（framebuffer）的整体约束，
current 3200 x 1080表示当前虚拟桌面尺寸，minimum/maximum是驱动允许的范围，最大分辨率受显卡与驱动上限约束（本机为 8192×8192）； VGA-1 disconnected：该接口存在但未连接任何显示器；HDMI-1 connected primary：已连接且被标记为主显示器；1920x1080+0+0中的+0+0是该输出在虚拟桌面中的左上角坐标；531mm x 299mm：物理屏幕尺寸（用于计算真实 DPI）；(normal left inverted right x axis y axis)：当前旋转/翻转状态为正常（normal）；- 模式列表：每一行是一种可用模式（分辨率），行内数字为支持的刷新率，
*标记当前正在使用的刷新率，+标记硬件首选（preferred）刷新率。例如1920x1080 59.93 + 60.00* 50.00 59.94表示该分辨率下当前使用 60.00Hz（*），硬件首选 59.93Hz（+），还可切换 50.00 / 59.94Hz。
实战二：指定分辨率与刷新率
在确认目标显示器支持的模式后，可以精确指定分辨率和刷新率：
xrandr --output HDMI-1 --mode 1920x1080 --rate 60--output HDMI-1锁定操作对象；--mode 1920x1080切换分辨率；--rate 60在 1920×1080 下将刷新率设置为 60Hz。
--rate必须配合--mode一起使用，且目标刷新率必须存在于该分辨率的支持列表中（见查询输出），否则命令会报错。常见的误用场景是"只调刷新率不调分辨率"，此时应显式带上--mode。
实战三：克隆屏幕
克隆（镜像）模式让所有显示器显示完全相同的内容，常用于演示与投影场景：
xrandr --output HDMI-1 --auto该命令将 HDMI-1 以其首选模式（--auto的语义）开启。若要多个屏幕克隆，可逐个对每个输出执行--auto，或者使用补充选项--same-as将副屏指定为与主屏相同：
xrandr --output HDMI-1 --auto --output VGA-1 --same-as HDMI-1注意：克隆模式下各屏分辨率以性能最低的显示器为基准，桌面尺寸会被压缩到公共交集。
实战四：多显示器扩展分屏
扩展模式（extend）让多个显示器组成一个更大的虚拟桌面，是办公多屏的默认形态。原文档示例：
xrandr --output VGA1 --auto --output HDMI1 --auto --right-of VGA1含义：VGA1 与 HDMI1 均启用最佳分辨率，且HDMI1 位于 VGA1 右侧，两块屏幕共同构成横向扩展的桌面。
方向控制选项的完整对应关系：
| 选项 | 摆放关系 |
|---|---|
--right-of 名称 | 当前输出在"名称"所指输出的右侧 |
--left-of 名称 | 当前输出在"名称"所指输出的左侧 |
--above 名称 | 当前输出在"名称"所指输出的上方 |
--below 名称 | 当前输出在"名称"所指输出的下方 |
多屏扩展布局可以一条命令串起来配置全部输出，例如三屏布局：
xrandr --output HDMI-1 --primary --mode 2560x1440 --rate 144 \ --output DP-1 --mode 1920x1080 --left-of HDMI-1 \ --output DP-2 --mode 1920x1080 --right-of HDMI-1竖屏场景还可叠加旋转：
xrandr --output HDMI-2 --mode 1080x1920 --rotate left --left-of HDMI-1实战五：多显示器中关闭不需要的输出
当显示器未使用或希望桌面只保留主屏时，将多余输出关闭：
xrandr --output HDMI-1 --off --output HDMI-2 --auto该命令同时关闭 HDMI-1、以最佳模式开启 HDMI-2。相比先开再关，一条命令串行指定所有输出的状态可避免中间态闪烁。--off只影响输出设备本身，不会卸载驱动或破坏配置，重新执行--auto即可恢复。
位置坐标与虚拟桌面的底层原理
从源码实现角度看，xrandr 每次调用最终都会向 X Server 提交一组 RandR 请求，核心是：
- 枚举输出与模式（对应查询模式）；
- 为每个输出挑选 mode（分辨率+刷新率）；
- 计算输出在虚拟桌面中的位置（
--right-of等选项会被换算成具体的 x/y 偏移量写入 CRTC 配置）； - 将配置应用并完成模式切换。
查询输出中的1920x1080+0+0与--pos、--right-of等选项本质都在操作同一个虚拟桌面的坐标系统：所有输出的可显示区域在"帧缓冲"上互不重叠地平铺，Screen 0第一行的current 3200 x 1080即这些区域的包围盒尺寸。这也是为什么把某块屏幕放在另一块左侧（--left-of）会扩大虚拟桌面宽度——它真实地改变了 framebuffer 的布局。
相关命令与排错参考
以下命令与本仓库中其它 X Window 管理工具配合，可构成完整的显示环境调试链路（均可在本项目 command 目录中找到对应文档）：
- modetest：libdrm 的 DRM/KMS 模式测试工具，直接操作内核 DRM 层，可在 X Server 未启动或驱动异常时验证显示控制器与连接器状态（例如对 Rockchip 等嵌入式平台执行
modetest -M rockchip -s 211@108:1200x1920 -v）； - xset：设置 X 系统用户偏好，如蜂鸣器、屏幕保护等，可配合调整显示相关行为；
- xhost：控制哪些 X 客户端能访问 X 服务器，远程显示（
ssh -X场景）出问题时可用其排查访问控制； - startx：启动 X 会话，若 xrandr 无法执行，通常是 X 会话未正常启动，可先用 startx 确认会话状态。
常见问题快速定位：
xrandr: cannot find output "xxx"：输出名称拼写错误或该接口未连接，先执行无参数xrandr核对名称；Configure crtc N failed/BadMatch：请求的分辨率/刷新率组合不被当前驱动或显示器 EDID 支持，换用查询结果中列出的模式，或检查线缆/转接头；- 无参数输出但分辨率列表为空：多为显示器 EDID 读取失败，可尝试
--newmode手动建立 modeline（高级用法，需精确的时序参数）； - xrandr 命令找不到：确认运行在 X11 会话且安装了
x11-xserver-utils包。
小结
xrandr 凭借"查询—选择模式—布局输出"三步式工作流，成为 Linux 桌面下最直接、可脚本化的显示配置工具。核心要点可归纳为：
- 无参数运行
xrandr获取真实输出名称与模式列表，*为当前值、+为首选值； - 单屏用
--output+--mode+--rate，多屏用--right-of/--left-of/--above/--below组合布局； --auto是快速恢复最佳配置的保险按钮，--off用于停用多余屏幕；- 所有操作实时生效、无需重启 X，一条命令即可完成整套多屏环境配置，且可通过 command/xrandr.md 与仓库内其它 X 工具文档形成完整的排错知识库。
- 文档
- 教程
【免费下载链接】linux-command
Linux命令大全搜索工具，内容包含Linux命令手册、详解、学习、搜集。https://git.io/linux
相关推荐
xrdp多显示器配置：扩展桌面与分辨率管理
xrdp多显示器配置：扩展桌面与分辨率管理 引言：打破单屏局限，构建高效远程工作空间 你是否在远程办公时受限于单一显示器的视野？是否因频繁切换窗口导致工作效率下
后端网络通信Polybar RandR扩展：多显示器配置管理的终极指南
Polybar RandR扩展：多显示器配置管理的终极指南 🚀 想要在多个显示器上完美部署状态栏？Polybar的RandR扩展为你提供了强大的多显示器配置管
桌面应用SerenityOS chres 命令详解：通过 IPC 与 WindowServer 切换显示分辨率
SerenityOS chres 命令详解：通过 IPC 与 WindowServer 切换显示分辨率 chres 是 SerenityOS 用户态中用于改变显
操作系统内核驱动
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
