brightness：Mac 命令行控制屏幕亮度

简介

brightness 是一个 macOS 命令行工具，用于通过终端控制屏幕亮度。这对于自动化脚本、远程控制或系统集成非常有用。

我需要它的场景是想把亮度调节接进自己的快捷脚本里。系统自带的调节方式是键盘上的功能键或者控制中心，都得手动操作，没法在脚本里调用。而有了命令行接口就可以做很多事：写一个脚本按时间段自动切换亮度，或者跟其他动作绑在一起——比如切到专注模式时同时把亮度降下来。远程通过 SSH 连到自己的 mac 时也只能靠命令行来调。

安装方法

使用 Homebrew 安装

# 安装 brightness
brew install brightness

# 验证安装
which brightness
brightness -l

两条验证命令的作用不同，都值得跑一下。which brightness 确认二进制装到了哪里、且在 PATH 里能找到；brightness -l 是真正的功能验证，它会列出检测到的显示器和当前亮度值，能跑通说明工具确实能跟显示器通上话。这一步很关键，因为下面会提到在某些机型上安装成功但调用失败的情况。

使用方法

基本语法

brightness [亮度值]

参数说明

亮度值范围：0.0 到 1.0
- 0.0：最暗（接近关闭）
- 0.5：50% 亮度
- 1.0：最亮

常用命令

# 查看当前亮度
brightness -l

# 设置亮度为 50%
brightness 0.5

# 设置亮度为最暗
brightness 0.0

# 设置亮度为最亮
brightness 1.0

参数用的是 0 到 1 的小数而不是百分比，写 50 是无效的。-l 是列出信息的选项，跟设置亮度的用法互斥。

设成 0.0 时屏幕是最暗但不是关闭，还能看清内容，不用担心把自己的屏幕彻底调黑了找不回来。真要恢复，键盘上的亮度键仍然可以正常用，两者不冲突。

多显示器的情况下，这个工具默认作用于所有检测到的显示器，-l 的输出里能看到各个显示器的编号，需要单独控制某一个可以用 -d 加编号指定。

常见错误及解决方案

错误：failed to set brightness of display (error -536870201)

这个报错的特征是命令能执行、也能读到当前亮度，但设置动作被系统拒绝了。原因在于苹果自研芯片的机型换了显示控制的底层实现，工具走的那套旧接口在新架构上返回了拒绝。所以它不是权限问题，加 sudo 也没用。

出现在 mac m3 系统上,我的解决方法是单独下载这个二进制的资源，不使用 homebrew 安装的

之所以换个二进制就能解决，是因为 Homebrew 仓库里的版本可能落后于上游对新机型的适配，或者构建时的目标架构不匹配。直接用一份适配过的二进制绕开了这个问题。另一个思路是从源码自己编译最新版，效果类似。

需要说明的是，如果目标是外接显示器而不是内置屏，这个工具本来就不一定适用——外接显示器的亮度通常要走 DDC/CI 协议来控制，那是另一套机制，得用文末列的 ddcctl 或者 MonitorControl。搞不清楚是哪种情况时，先用 -l 看看它到底识别到了哪些显示器。

https://download.csdn.net/download/weixin_40013817/92232545

宜东到 bin 目录

下载下来的二进制放在下载目录里是没法直接当命令用的，需要挪到 PATH 包含的目录下面。下面这条命令把三件事串起来做完了：复制、赋可执行权限、移除下载隔离标记。

拆开看每一段。第一段 cp 复制到 /usr/local/bin，这个目录是 mac 上放用户自装命令的惯例位置，默认就在 PATH 里。第二段 chmod +x 加上可执行权限，从浏览器下载的文件通常没有这个权限位，不加会报权限被拒。第三段 xattr -d com.apple.quarantine 移除隔离标记，这是从网络下载的文件都会被打上的属性，带着它执行会被系统的门禁机制拦下，提示无法验证开发者。

连接符的差别也说一下。前两段之间用 &&，表示前一步成功才继续，复制失败就不会往下走。xattr 那段后面用的是 ;，也就是不管成功失败都继续执行最后的 ls——这里是故意的，因为如果文件本来就没有隔离标记，xattr -d 会报错，用 && 的话后面就断了。命令里的 2>/dev/null 也是同样目的，把这个无害的报错丢掉不显示。

最后那个 ls -l 是验证，输出里应该能看到权限位中带 x。

路径里的 wfly 是我的用户名，照抄要换成自己的。

sudo cp /Users/wfly/Downloads/brightness /usr/local/bin/brightness && sudo chmod +x /usr/local/bin/brightness && xattr -d com.apple.quarantine /usr/local/bin/brightness 2>/dev/null; ls -l /usr/local/bin/brightness

简介