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。先确认：
echo$XDG_SESSION_TYPE- 显示
x11→ 已经在 X11，可跳过本章。 - 显示
wayland→ 继续下面的切换操作。
2.1 方法一：登录界面手动切换（推荐，最直观）
- 注销当前用户（或重启电脑），回到 GDM 登录界面。
- 点击你的用户名，先不要输入密码。
- 在密码框右下角会出现一个齿轮图标 ⚙（有的版本在左下角），点击它。
- 在弹出的列表里选择“Ubuntu on Xorg”（Ubuntu 22.04 里也可能就叫 “Ubuntu”；24.04 明确叫 “Ubuntu on Xorg”）。
- 输入密码登录。
- 重新验证：
echo $XDG_SESSION_TYPE应显示x11。
注意：切到 X11 后，之前已经打开的程序（如 CodeBuddy、浏览器）仍然跑在旧会话环境下，需要完全退出再重开才能继承新的 X11 环境。
2.2 方法二：强制默认 X11（找不到齿轮时用）
部分精简版登录界面不显示齿轮，可以直接改 GDM 配置强制禁用 Wayland：
sudosed-i's/#WaylandEnable=false/WaylandEnable=false/'/etc/gdm3/custom.confsudosystemctl 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。
检测显示器：
sudoddcutil detect会列出 I2C 总线号和显示器型号。
调节亮度（VCP 码 10 = 亮度，16 = 对比度）：
sudoddcutil setvcp1050# 亮度设为 50（范围 0~100）sudoddcutil setvcp1640# 对比度压低，整体更柔和sudoddcutil getvcp10# 验证，会显示 current / max value典型问题：
- 若
detect找不到显示器，可能是视频线不支持 DDC（部分 VGA/转接头不行），或需要在 BIOS/显示器菜单开启 “DDC/CI”。 - 若设到很低仍觉得刺眼，说明该显示器硬件最低亮度偏高，需叠加第二层。
4.2 第二层：软件亮度（xrandr，X11 专属）
这一层能突破硬件下限，是"还是太亮"时的最终手段。
① 找对你的输出名（最关键的一步）
xrandr-q|grep-E"connected"会列出真实输出名，例如HDMI-0、DP-1、eDP-1。务必用这里看到的名字，不要信xrandr --listmonitors里可能显示的HDMI-1之类的别名。
② 压暗：
xrandr--outputHDMI-0--brightness0.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（没有就新建），每次登录自动执行：
echo'xrandr --output HDMI-0 --brightness 0.3'>>~/.xprofile硬件亮度（ddcutil）因需 sudo 且涉及 I2C 权限，建议保留手动命令或写带 NOPASSWD 的脚本。
6.2 设别名，少打字
echo"alias dim='xrandr --output HDMI-0 --brightness'">>~/.bashrcecho"alias bright='sudo ddcutil setvcp 10'">>~/.bashrcsource~/.bashrc# 之后：dim 0.3 bright 506.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 或显示器低蓝光模式。把这两条写进启动脚本，重启也不怕。