Ubuntu 屏幕亮度调节完整解决方案（含 X11 会话切换

Ubuntu 屏幕亮度调节完整解决方案（含 X11 会话切换）

适用：Ubuntu 20.04 / 22.04 / 24.04，外接显示器或笔记本内置屏，X11 与 Wayland 环境
目标：把"太亮、调不动、重启复原、Wayland 下失效"等问题一次性解决

---

答案 x11 和 xrandr --output HDMI-0 --brightness 0.3

一、先搞懂为什么会"调不动"——显示子系统基础

在动手之前，必须先理解一件事：Linux 下调亮度有"硬件"和"软件"两条完全不同的路，而能不能用取决于你跑在 X11 还是 Wayland 上。这也是绝大多数人卡住的根本原因。

1.1 X11 与 Wayland 的区别

• X11（老架构）：应用程序直接通过 X 服务器控制显卡，第三方工具可以随意修改屏幕的 gamma / 亮度（xrandr --brightness 就是走的这条路）。
• Wayland（新架构）：出于安全和稳定性的考虑，显示合成器（GNOME 的 Mutter）独占了对屏幕的最终控制权，不允许普通程序改 gamma。所以 xrandr --brightness、redshift 这类"软件变暗"命令在 Wayland 下要么报错，要么"退出码 0 但屏幕毫无变化"。

版本默认情况：

• Ubuntu 22.04 默认是Wayland 不是 X11（"Ubuntu"会话即 Xorg）。
• Ubuntu 23.04 起默认改为 Wayland，24.04 也是 Wayland 优先。
• 也就是说，你用的如果是较新版本却没特意切过，很可能正跑在 Wayland 上，软件调暗自然失效。

1.2 硬件亮度 vs 软件亮度

• 硬件亮度：直接命令显示器降背光。内置屏走 ACPI/DRM 背光（/sys/class/backlight），外接屏走 DDC/CI 协议（ddcutil）。这是"物理变暗"，最省电、观感最自然。
• 软件亮度：在显卡输出层面乘一个系数（xrandr --brightness / gamma）。它叠加在硬件亮度之上，所以能比硬件最暗更暗，但会轻微损失画质、增加一点耗电。

理解这两点后，下面的方案就不会再让你迷路了。

---

二、第一步：确认并切换到 X11 会话

如果你的目标包含"用 xrandr 软件压暗"，必须保证处于 X11。先确认：

1. echo $XDG_SESSION_TYPE

复制代码

• 显示 x11 → 已经在 X11，可跳过本章。
• 显示 wayland → 继续下面的切换操作。

2.1 方法一：登录界面手动切换（推荐，最直观）

1. 注销当前用户（或重启电脑），回到 GDM 登录界面。
2. 点击你的用户名，先不要输入密码。
3. 在密码框右下角会出现一个齿轮图标 ⚙（有的版本在左下角），点击它。
4. 在弹出的列表里选择 “Ubuntu on Xorg”（Ubuntu 22.04 里也可能就叫 “Ubuntu”；24.04 明确叫 “Ubuntu on Xorg”）。
5. 输入密码登录。
6. 重新验证：echo $XDG_SESSION_TYPE 应显示 x11。

注意：切到 X11 后，之前已经打开的程序（如 CodeBuddy、浏览器）仍然跑在旧会话环境下，需要完全退出再重开才能继承新的 X11 环境。

2.2 方法二：强制默认 X11（找不到齿轮时用）

部分精简版登录界面不显示齿轮，可以直接改 GDM 配置强制禁用 Wayland：

1. sudo sed -i 's/#WaylandEnable=false/WaylandEnable=false/' /etc/gdm3/custom.conf
2. sudo systemctl restart gdm3

复制代码

执行后登录管理器会重启（屏幕会闪一下，已开程序会被关闭），重新登录即为 X11。

2.3 方法三：临时验证（不改系统）

如果你只是想临时试一下 X11 下的效果，也可以在登录界面选 Xorg 会话登录一个测试用户，确认能调暗后再决定是否永久切换。

---

三、安装亮度调节工具

Ubuntu 仓库（需先 sudo add-apt-repository universe 并 sudo apt update）提供以下工具，按需安装：

工具	类型	适合场景	安装
brightnessctl	命令行	笔记本内置屏背光	sudo apt install brightnessctl
ddcutil	命令行	外接显示器 DDC/CI	sudo apt install ddcutil
brightness-controller	GUI 滑块	内置屏图形调节	sudo apt install brightness-controller
redshift / redshift-gtk	GUI+护眼	色温护眼（X11 有效）	sudo apt install redshift redshift-gtk
xrandr	命令行	软件亮度叠加（X11）	自带，无需装

重要提醒：xrandr 和 ddcutil 才是本文真正解决问题的核心，GUI 工具在 Wayland 下大多受限，建议优先掌握命令行。

---

四、三层调节方案详解

4.1 第一层：硬件亮度（外接屏用 ddcutil）

外接显示器（HDMI / DP / DVI）的背光不受系统 ACPI 管理，必须走 DDC/CI。

检测显示器：

1. sudo ddcutil detect

复制代码

会列出 I2C 总线号和显示器型号。

调节亮度（VCP 码 10 = 亮度，16 = 对比度）：

1. sudo ddcutil setvcp 10 50 # 亮度设为 50（范围 0~100）
2. sudo ddcutil setvcp 16 40 # 对比度压低，整体更柔和
3. sudo ddcutil getvcp 10 # 验证，会显示 current / max value

复制代码

典型问题：

• 若 detect 找不到显示器，可能是视频线不支持 DDC（部分 VGA/转接头不行），或需要在 BIOS/显示器菜单开启 “DDC/CI”。
• 若设到很低仍觉得刺眼，说明该显示器硬件最低亮度偏高，需叠加第二层。

4.2 第二层：软件亮度（xrandr，X11 专属）

这一层能突破硬件下限，是"还是太亮"时的最终手段。

① 找对你的输出名（最关键的一步）

1. xrandr -q | grep -E "connected"

复制代码

会列出真实输出名，例如 HDMI-0、DP-1、eDP-1。务必用这里看到的名字，不要信 xrandr --listmonitors 里可能显示的 HDMI-1 之类的别名。

② 压暗：

1. xrandr --output HDMI-0 --brightness 0.3 # 0.1 最暗 ~ 1.0 最亮

复制代码

把它和硬件亮度相乘：例如 ddcutil 50% × xrandr 0.3 ≈ 实际 15% 亮度，足以应对绝大多数"刺眼"场景。

③ 验证是否生效： 屏幕应立即变暗；若退出码 0 但毫无变化，99% 是你仍在 Wayland（回到第二章切换）。

4.3 第三层：护眼（不改变亮度数值）

如果"太亮"其实是"偏蓝刺眼"，调亮度治标不治本，应该调色温：

• GNOME 自带 Night Light：设置 → 显示器 → Night Light，开启并拉暖。Wayland/X11 都生效，最推荐。
• 显示器 OSD：开"低蓝光 / 阅读 / 护眼模式"，观感比单纯降亮度舒服得多。
• Redshift（X11）：redshift-gtk -l 纬度:经度，自动随日出日落调色温。Wayland 下不可用。

---

五、实战踩坑全记录（避坑必读）

以下是真实调试中踩过的坑，对照可省去大量时间：

坑 1：brightnessctl 调成了键盘灯
执行 sudo brightnessctl set 10%- 后提示 Updated device 'input6::numlock'，说明它改的是 numlock 指示灯（leds 类），不是屏幕。原因：你的屏是外接 HDMI，背光不在系统里，要用 ddcutil。解法：指定 backlight 设备 brightnessctl -d intel_backlight set 50%，或直接改用 ddcutil。

坑 2：输出名 HDMI-1 不存在
xrandr --output HDMI-1 --brightness 0.3 报 output HDMI-1 not found。原因：--listmonitors 显示的 HDMI-1 是监视器别名，真实 RandR 输出名是 HDMI-0（以 xrandr -q 为准）。改成 HDMI-0 即可。

坑 3：Wayland 下 xrandr 静默失效
xrandr --brightness 0.3 退出码 0，但屏幕纹丝不动。这是 Wayland 合成器忽略 RandR 亮度的典型表现，不是命令写错。必须切到 X11（第二章）才能生效。

坑 4：在 CodeBuddy 内置终端里操作无效
在 IDE 集成终端里跑 xrandr 可能连不到真实 X 显示（沙箱/远程环境问题），表现为 Need crtc to set gamma on 或 not found。解法：按 Ctrl+Alt+T 打开系统原生终端再操作。

坑 5：重启后输入法/亮度复原
亮度是临时命令，重启即丢；若 fcitx5 没设自启也会"消失"。见第六章持久化。

---

六、持久化与便捷化

6.1 开机自动调暗（亮度）

把软件亮度写进 ~/.xprofile（没有就新建），每次登录自动执行：

1. echo 'xrandr --output HDMI-0 --brightness 0.3' >> ~/.xprofile

复制代码

硬件亮度（ddcutil）因需 sudo 且涉及 I2C 权限，建议保留手动命令或写带 NOPASSWD 的脚本。

6.2 设别名，少打字

1. echo "alias dim='xrandr --output HDMI-0 --brightness'" >> ~/.bashrc
2. echo "alias bright='sudo ddcutil setvcp 10'" >> ~/.bashrc
3. source ~/.bashrc
4. # 之后：dim 0.3 bright 50

复制代码

6.3 输入法（fcitx5）自启

若同时配了中文输入法，建用户级自启项 ~/.config/autostart/fcitx5.desktop，并设 X-GNOME-AutoRestart=true，避免重启后输入法消失。

---

七、故障排查速查表

现象	优先检查	命令
完全调不动	会话类型	echo $XDG_SESSION_TYPE（非 x11 就切）
改了没反应	输出名	xrandr -q | grep connected
调成键盘灯	设备类	brightnessctl -l 看有无 backlight
外接屏无效	DDC 支持	sudo ddcutil detect
IDE 里不行	终端环境	改用 Ctrl+Alt+T 原生终端
重启复原	持久化	写 ~/.xprofile / 自启项

---

八、一句话总结

外接 HDMI 屏最稳组合 = ddcutil setvcp 10 调硬件亮度 + xrandr --output HDMI-0 --brightness 0.3 软件压暗（必须 X11、原生终端、用真实输出名）；护眼再叠加 Night Light 或显示器低蓝光模式。 把这两条写进启动脚本，重启也不怕。