yabai 实战指南：基于二进制空间分区（BSP）的 macOS 平铺窗口管理器安装、配置与命令解析

yabai 实战指南基于二进制空间分区BSP的 macOS 平铺窗口管理器安装、配置与命令解析【免费下载链接】yabaiA tiling window manager for macOS based on binary space partitioning项目地址: https://gitcode.com/gh_mirrors/ya/yabai本指南以 yabai 项目官方 README 为骨架结合仓库内的完整文档doc/yabai.asciidoc、示例配置examples/yabairc、examples/skhdrc与源码src/yabai.c系统讲解 yabai 的定位、安装前提、系统权限、注意事项以及基于命令行接口的窗口/空间/显示器管理、规则与信号等进阶用法。读完本文你将掌握 yabai 的完整配置流程、常用命令语义与选择器语法能够从零开始搭建一套可落地的 macOS 平铺窗口工作流。一、yabai 是什么macOS 平铺窗口管理器yabai 是一个窗口管理工具其设计目标是作为 macOS 内置窗口管理器的扩展而工作。它允许你通过一个直观的命令行接口自由地控制窗口Windows、空间Spaces和显示器Displays并可以选用 skhd 或其他第三方软件自定义键盘快捷键。yabai 的主要功能是平铺式窗口管理Tiling Window Management它使用二进制空间分区Binary Space PartitioningBSP算法自动修改窗口布局把屏幕空间不断二分给新窗口让用户专注于窗口内容本身避免手动拖拽排列带来的干扰。从源码结构看仓库中的 src/window_manager.c、src/space_manager.c 与 src/display_manager.c 分别承担窗口、空间、显示器三个核心对象的管理而 src/event_loop.c 驱动整个事件循环——这正是扩展 macOS 原生窗口管理器这一设计在实现层面的体现。除平铺管理外yabai 还提供一系列增强特性Focus-follows-mouse鼠标移动时自动聚焦窗口禁用空间切换动画通过skip_window_focus_animation等配置绕过系统动画突破 16 个空间上限可创建超过 macOS 默认 16 个空间的限制窗口透明度opacity控制、窗口动画window animation、窗口阴影shadow控制规则rules自动管理窗口、信号signals事件响应、scratchpad 暂存窗口等高级能力详见 doc/yabai.asciidoc。当前仓库对应 yabai 版本7.1.25见 src/yabai.c 中的 MAJOR/MINOR/PATCH 定义。二、安装与配置从零开始2.1 安装方式概览官方 wiki 提供了多种安装方法的简要与详细说明同时也解释了如何彻底卸载 yabai。本仓库内可用于安装的辅助资源包括scripts/install.sh安装最新预编译 release 的脚本依赖curl、shasum、tar、cp、cut。它接受两个可选参数二进制安装目录缺省为/usr/local/bin和 man 手册安装目录缺省为/usr/local/share/man/man1并且会校验目标目录存在且可写任何一项不满足都会报错退出。makefile从源码构建的入口。注意从源码或安装 HEAD 版本构建后必须对二进制进行代码签名codesign否则更新或重新构建后辅助功能Accessibility与自动化Automation权限会丢失。仓库 scripts/ 目录下的codesign脚本即为签名辅助脚本。doc/yabai.1系统 man 手册页构建/安装后可执行man yabai查看。doc/yabai.asciidoc完整命令参考文档是配置与命令用法的权威依据。2.2 示例配置文件yabairc仓库 examples/yabairc 提供了一份可直接参考的全局配置脚本。它通过yabai -m config批量设置全局选项加载后输出yabai configuration loaded..。以下是该文件的完整内容与逐项说明参数语义取自 doc/yabai.asciidoc 的 Global Settings 与 Space Settings# 全局设置 yabai -m config \ external_bar off:40:0 \ # 外置状态栏占位off 表示不额外留白main|all:top:bottom menubar_opacity 1.0 \ # macOS 菜单栏透明度0.0 时永久隐藏菜单栏 mouse_follows_focus off \ # 聚焦窗口时是否把鼠标移到其中心 focus_follows_mouse off \ # 鼠标悬停自动聚焦autofocus|autoraise|off display_arrangement_order default \ # 显示器排序方式default|vertical|horizontal window_origin_display default \ # 新窗口归属显示器default|focused|cursor window_placement second_child \ # 新窗口成为分割树的第一个或第二个叶子节点 window_insertion_point focused \ # 新窗口插入位置focused|first|last window_zoom_persist on \ # 布局变化时保持窗口 zoom 状态 window_shadow on \ # 窗口阴影需要部分关闭 SIP skip_window_focus_animation off \ # 跳过跨空间聚焦时的系统动画 window_animation_duration 0.0 \ # 窗口帧动画时长0.0 不播放动画 window_animation_easing ease_out_circ \ # 动画缓动函数见 asciidoc 的 EASING 定义 window_opacity_duration 0.0 \ # 激活/非激活透明度过渡时长需要 SIP active_window_opacity 1.0 \ # 聚焦窗口不透明度需要 SIP normal_window_opacity 0.90 \ # 非聚焦窗口不透明度需要 SIP window_opacity off \ # 全局透明度开关需要 SIP insert_feedback_color 0xffd75f5f \ # window --insert 预览框颜色0xAARRGGBB split_ratio 0.50 \ # 分割时左右/上下窗口占比 split_type auto \ # 分割轴vertical|horizontal|auto auto_balance off \ # 布局变化时自动平衡所有窗口面积 top_padding 12 \ # 空间顶部内边距 bottom_padding 12 \ # 空间底部内边距 left_padding 12 \ # 空间左侧内边距 right_padding 12 \ # 空间右侧内边距 window_gap 06 \ # 窗口间距 layout bsp \ # 当前空间布局bsp|stack|float mouse_modifier fn \ # 鼠标拖拽修饰键cmd|alt|shift|ctrl|fn mouse_action1 move \ # 修饰键左键动作move|resize mouse_action2 resize \ # 修饰键右键动作move|resize mouse_drop_action swap \ # 拖放窗口到另一窗口中心时的动作swap|stack配置文件中还注释了一段与 scripting addition 相关的自动恢复脚本当 Dock.app 重启后可自动重新加载脚本扩展# yabai -m signal --add eventdock_did_restart actionsudo yabai --load-sa # sudo yabai --load-sa注意使用sudo yabai --load-sa需要预先配置 sudo 免密执行该命令具体见官方 wiki 的 Configure Scripting Addition 一节。提示配置文件默认路径由-c参数指定若文件带有可执行位yabai 会通过/usr/bin/env sh -c config_file执行否则通过/usr/bin/env sh config_file解释执行见 doc/yabai.asciidoc 中--config选项说明。2.3 键盘快捷键skhdyabai 本身只提供 CLI快捷键需借助 skhd 等第三方软件绑定。仓库 examples/skhdrc 提供了大量可直接启用的参考绑定例如# 聚焦窗口 # alt - h : yabai -m window --focus west # 交换受管窗口 # shift alt - h : yabai -m window --swap north # 移动受管窗口 # shift cmd - h : yabai -m window --warp east # 平衡窗口大小 # shift alt - 0 : yabai -m space --balance # 让浮动窗口铺满屏幕 / 左半屏 # shift alt - up : yabai -m window --grid 1:1:0:0:1:1 # shift alt - left : yabai -m window --grid 1:2:0:0:1:1 # 快速聚焦桌面 / 最近桌面 # cmd alt - x : yabai -m space --focus recent # cmd alt - 1 : yabai -m space --focus 1 # 发送窗口到桌面并跟随焦点 # shift cmd - z : yabai -m window --space next; yabai -m space --focus next # 聚焦显示器 # ctrl alt - z : yabai -m display --focus prev # 移动浮动窗口 # shift ctrl - a : yabai -m window --move rel:-20:0 # 调整窗口大小 # shift alt - a : yabai -m window --resize left:-20:0 # 设置插入点 / 切换 zoom / 切换 split / 浮动居中 # ctrl alt - h : yabai -m window --insert west # alt - d : yabai -m window --toggle zoom-parent # alt - e : yabai -m window --toggle split # alt - t : yabai -m window --toggle float --grid 4:4:1:1:2:2 # 切换 sticky / 画中画 # alt - p : yabai -m window --toggle sticky --toggle pip其中创建桌面、移动窗口并跟随焦点的组合还演示了结合jq解析 JSON 的脚本化用法需要brew install jq# shift cmd - n : yabai -m space --create \ # index$(yabai -m query --spaces --display | jq map(select(.is-native-fullscreen false))[-1].index) \ # yabai -m window --space ${index} \ # yabai -m space --focus ${index}三、系统要求Requirements安装前请仔细阅读下表要求并在提交 issue 前逐一确认满足| 要求 | 说明 | | -: | :- | | 操作系统Intel x86-64 | 支持 Big Sur 11.0.0、Monterey 12.0.0、Ventura 13.0.0、Sonoma 14.0.0、Sequoia 15.0 以及 Tahoe 26.0 | | 操作系统Apple Silicon | 支持 Monterey 12.0.0、Ventura 13.0.0、Sonoma 14.0.0、Sequoia 15.0 以及 Tahoe 26.0 | | 辅助功能Accessibility API | yabai 必须获得辅助功能权限启动时会请求授权授权后必须重启应用| | 屏幕录制Screen Recording |仅当需要启用窗口动画时才需要屏幕录制权限必要时 yabai 会请求授权授权后必须重启应用 | | 系统偏好设置macOS 11.x、12.x | 在 Mission Control 面板中必须启用 Displays have separate Spaces显示器具有单独的空间 | | 系统设置macOS 13.x、14.x、15.x、26.x | 在 Desktop Dock 选项卡 → Mission Control 面板中必须启用 Displays have separate Spaces |需要强调的是Displays have separate Spaces 是 yabai 正确管理多显示器空间的前提遗漏此项会导致跨显示器的空间/窗口行为异常。四、注意事项与使用限制Caveats官方 README 同时列出了以下必须了解的注意事项| 注意事项 | 说明 | | -: | :- | | 系统完整性保护 SIP可选 | 可以部分关闭 SIP以便 yabai 向 Dock.app 注入 scripting addition从而以更高权限控制窗口。这使 yabai 能够控制窗口服务器的连接并解锁更多高级功能 | | 代码签名 | 从源码构建或安装 HEAD 版本时必须对二进制进行 codesign否则更新或重建后辅助功能与自动化权限会丢失 | | Finder 桌面 | 部分用户会用未公开的 defaults 命令禁用 Finder Desktop 窗口这会导致空空间聚焦失效使用 yabai 时应避免。重新启用可执行defaults write com.apple.finder CreateDesktop -bool true| | NSDocument 类应用 | 使用 macOS 原生标签页tab的窗口如 Terminal、Finder在创建标签页时行为不正确参见仓库 issues #68。应避免在这些应用中创建标签页改用不使用 NSDocument 标签系统的替代方案或用规则将这些窗口设为浮动 | | 系统偏好设置macOS 11.x、12.x | 在 Mission Control 面板中应关闭 Automatically rearrange Spaces based on most recent use根据最近使用情况自动重新排列空间以保证依赖空间顺序的命令可靠工作 | | 系统设置macOS 13.x、14.x、15.x、26.x | 在 Desktop Dock → Mission Control 中应关闭 Automatically rearrange Spaces based on most recent use | | 系统设置macOS 14.x、15.x、26.x | 在 Desktop Dock → Desktop Stage Manager 面板中Show Items On Desktop在桌面上显示项目应保持启用以保证多显示器配置下显示与空间聚焦命令可靠工作 | | 系统设置macOS 14.x、15.x、26.x | Click wallpaper to reveal Desktop点按墙纸以显示桌面应设置为 Only in Stage Manager仅在台前调度中以保证显示与空间聚焦命令可靠工作 |关于 scripting addition 与 SIP 的补充说明从源码层面看yabai 的 CLI 选项src/yabai.c包含--load-sa与--uninstall-sa前者将 scripting addition 安装并加载到 Dock.app路径为/Library/ScriptingAdditions/yabai.osax必要时自动更新后者卸载该扩展需以 root 运行。两者都要求部分关闭 SIP。此外--install-service/--start-service/--restart-service/--stop-service/--uninstall-service用于将 yabai 注册为 launchd 服务plist 路径为~/Library/LaunchAgents/com.asmvik.yabai.plist实现登录自启与常驻运行。五、命令行接口深度解析yabai 的核心交互方式是消息传递客户端把参数封装成消息通过 Unix 套接字路径形如/tmp/yabai_%s.socket%s为用户名发送给常驻的 yabai 实例并读取响应见 src/yabai.c 的client_send_message实现实例侧还通过/tmp/yabai_%s.lock锁文件保证单实例运行。处理失败时返回非零退出码。5.1 全局选项选项说明--load-sa安装并加载 scripting addition 到 Dock.app路径/Library/ScriptingAdditions/yabai.osax需要部分关闭 SIP--uninstall-sa卸载 scripting addition需以 root 运行--install-service/--uninstall-service写入 / 移除 launchd 服务文件~/Library/LaunchAgents/com.asmvik.yabai.plist--start-service/--restart-service/--stop-service启用并启动 / 重启 / 停止并卸载服务实例-m, --message msg向运行中的 yabai 实例发送消息配置、查询、操作命令均走此入口-c, --config config_file使用指定配置文件执行-V, --verbose输出调试信息到 stdout-v, --version输出版本号并退出-h, --help输出选项说明并退出5.2 选择器语法Selectors消息命令大量使用选择器来定位窗口、空间、显示器理解它们是用好 yabai 的前提定义见 doc/yabai.asciidocDIR_SELnorth | east | south | westWINDOW_SELprev | next | first | last | recent | mouse | largest | smallest | sibling | first_nephew | second_nephew | uncle | first_cousin | second_cousin以及stack.prev、stack.next、stack.first、stack.last、stack.recent、stack.index等堆栈选择器或直接使用window idSPACE_SELprev | next | first | last | recent | mouse | mission-control index (1-based) | labelDISPLAY_SELprev | next | first | last | recent | mouse | 方向 | arrangement index (1-based) | label通用取值BOOL_SELon|off、FLOAT_SEL0 value 1.0、LAYERbelow | normal | above | auto5.3 配置域Configyabai -m config global setting # 获取或设置全局设置 yabai -m config [--space SPACE_SEL] setting # 获取或设置某空间的设置全局设置包括debug_output、external_bar、menubar_opacity、mouse_follows_focus、focus_follows_mouse、display_arrangement_order、window_origin_display、window_placement、window_insertion_point、window_zoom_persist、window_shadow、window_opacity系列、window_animation_duration、window_animation_easing、insert_feedback_color、split_ratio、mouse_modifier、mouse_action1、mouse_action2、mouse_drop_action等详见 doc/yabai.asciidoc 的 Global Settings 小节2.2 节已给出核心项的取值与含义。空间级设置Space Settings包括layoutbsp | stack | float设置所选空间的布局split_typevertical | horizontal | autovertical 沿 y 轴分割、horizontal 沿 x 轴分割、auto 根据宽高比自动决定top_padding/bottom_padding/left_padding/right_padding空间四边内边距整数window_gap窗口间距整数auto_balanceon | off | x-axis | y-axis变化时自动平衡窗口树使各窗口面积相等。5.4 窗口、空间与显示器操作窗口Window语法yabai -m window [WINDOW_SEL] COMMAND--focus/--close/--minimize/--deminimize聚焦 / 关闭 / 最小化 / 还原窗口--display DISPLAY_SEL、--space SPACE_SEL把窗口发送到指定显示器 / 空间--swap WINDOW_SEL交换两个窗口的位置--warp WINDOW_SEL重新插入窗口并分割目标窗口--stack WINDOW_SEL把窗口堆叠到另一窗口之上--insert DIR_SEL|stack设置选中窗口的分割模式与当前模式相同时撤销--grid rows:cols:start-x:start-y:width:height按自定义网格设置窗口 frame--move abs|rel:dx:dy、--resize top|left|bottom|right|...|abs:dx:dy、--ratio rel|abs:dr移动、缩放、调整分割比例--toggle float|sticky|pip|shadow|split|zoom-parent|zoom-fullscreen|windowed-fullscreen|native-fullscreen|expose|LABEL切换窗口属性sticky、pip、shadow、LABEL 需要部分关闭 SIP--sub-layer LAYER、--opacity FLOAT_SEL、--raise/--lower窗口层级、透明度与前后排序均需部分关闭 SIP--scratchpad [LABEL|recover]为窗口分配暂存scratchpad标识scratchpad 窗口自动视为浮动的非受管窗口recover可强制把所有 scratchpad 窗口置前需部分关闭 SIP。空间Space语法yabai -m space [SPACE_SEL] COMMAND--focus、--switch聚焦空间--switch让给定空间替换当前空间跨显示器时表现为--swap同显示器时表现为--focus--create/--destroy/--move/--swap/--display创建、销毁、移动、交换空间或把空间送往另一显示器均需部分关闭 SIP--equalize/--balance重置 / 平衡分割比例可按轴限定--mirror x-axis|y-axis翻转窗口树--rotate 90|180|270旋转窗口树--padding abs|rel:top:bottom:left:right、--gap abs|rel:gap调整内边距与间距--toggle padding|gap|mission-control|show-desktop、--layout bsp|stack|float、--label [LABEL]切换设置、设置布局、为空间打标签标签可作SPACE_SEL别名。显示器Display语法yabai -m display [DISPLAY_SEL] COMMAND--focus DISPLAY_SEL聚焦给定显示器--space SPACE_SEL让给定空间在选中显示器上可见但不改变焦点需部分关闭 SIP--label [LABEL]为显示器打标签可作DISPLAY_SEL别名。5.5 查询Queryyabai -m query COMMAND [PROPERTIES] [ARGUMENT]--displays、--spaces、--windows分别查询显示器、空间、窗口信息可用--display、--space、--window约束范围也可用逗号分隔的字段名列表筛选输出属性。查询结果以 JSON 返回Displayid、uuid、index、label、frame{x,y,w,h}、spaces、has-focusSpaceid、index、label、type、display、windows、first-window、last-window、has-focus、is-visible、is-native-fullscreenWindowid、pid、app、title、frame、role、subrole、display、space、layer、opacity、split-type、split-child、stack-index、can-move、can-resize、has-focus、has-shadow、is-native-fullscreen、is-visible、is-minimized、is-hidden、is-floating、is-sticky、is-grabbed等。需要留意的是部分窗口属性只有在 yabai 持有该窗口的AX-reference辅助功能引用时才能获取。AX-reference 只能在窗口所在空间激活时获取对 yabai 启动时已存在于非激活空间的窗口会通过 workaround 尽量探测少数窗口无法探测时查询结果将不完整且窗口命令对其无效。可通过has-ax-reference字段识别此类窗口待其所在空间激活后 yabai 会自动建立引用。5.6 规则Rules规则用于让新产生的窗口自动获得指定行为语法yabai -m rule COMMAND--add [--one-shot] [ARGUMENT]添加规则作用于其后创建的窗口--one-shot规则生效一次后自动删除--apply [RULE_SEL | ARGUMENT]把已有规则应用到当前已知窗口无参数则应用全部--remove RULE_SEL、--list删除 / 列出规则。规则参数ARGUMENT包括app[!]REGEX、title[!]REGEX、role[!]REGEX、subrole[!]REGEX按应用名 / 窗口标题 / 辅助功能角色 / 子角色匹配!表示取反使用 POSIX 扩展正则display[^]DISPLAY_SEL、space[^]SPACE_SEL把窗口送到指定显示器 / 空间^表示跟随焦点manageBOOL_SEL是否受管平铺主要用来让窗口浮动stickyBOOL_SEL、sub-layerLAYER、opacityFLOAT_SEL粘性 / 层级 / 透明度需部分关闭 SIPmouse_follows_focusBOOL_SEL覆盖全局mouse_follows_focusnative-fullscreenBOOL_SEL窗口进入原生全屏gridrows:cols:start-x:start-y:width:height按网格设置窗口 framescratchpadLABEL分配暂存窗口标识需部分关闭 SIP。匹配语义所有匹配的规则按注册顺序依次应用后注册的规则覆盖先注册的同属性值若同时设置display与space以space为准。5.7 信号Signals信号Signal是响应已处理事件的简单机制参数通过环境变量传递语法yabai -m signal COMMAND--add eventEVENT actionACTION [labelLABEL] [app[!]REGEX] [title[!]REGEX] [activeyes|no]--remove SIGNAL_SEL、--list删除 / 列出信号。常见事件与传入的环境变量节选自 doc/yabai.asciidoc事件传入环境变量可用的过滤器application_launched/application_terminated/application_activated/application_deactivated/application_visible/application_hidden$YABAI_PROCESS_IDapp部分支持 activeapplication_front_switched$YABAI_PROCESS_ID、$YABAI_RECENT_PROCESS_ID—window_created/window_destroyed/window_focused/window_moved/window_resized/window_minimized/window_deminimized/window_title_changed$YABAI_WINDOW_IDapp、title部分支持 activespace_created$YABAI_SPACE_ID、$YABAI_SPACE_INDEX—space_changed$YABAI_SPACE_ID、$YABAI_SPACE_INDEX、$YABAI_RECENT_SPACE_ID、$YABAI_RECENT_SPACE_INDEX—display_added/display_removed/display_moved/display_resized$YABAI_DISPLAY_ID及_INDEX—display_changed$YABAI_DISPLAY_ID、$YABAI_DISPLAY_INDEX、$YABAI_RECENT_DISPLAY_ID、$YABAI_RECENT_DISPLAY_INDEX—mission_control_enter/mission_control_exit$YABAI_MISSION_CONTROL_MODE—dock_did_change_pref/dock_did_restart/menu_bar_hidden_changed/system_woke——信号动作ACTION通过/usr/bin/env sh -c执行任意命令——2.2 节中重启 Dock 后自动sudo yabai --load-sa即为此机制的典型用法。六、许可与免责声明yabai 采用MIT 许可证见 LICENSE.txt这是一种简短宽松的许可协议仅要求保留版权与许可声明被许可的作品、修改版本及更大规模的衍生作品可以以不同条款分发且无需附带源码。官方 README 同时明确声明免责条款请自行斟酌使用Use at your own discretion作者对安装、测试或以任何形式使用本软件过程中可能发生的任何机器损坏不承担责任用户须了解部分关闭系统完整性保护SIP可能带来的风险作者不就是否应该关闭 SIP作任何建议。版本变更历史可查阅 CHANGELOG.md。结语从 README 到源码yabai 呈现出一条清晰的设计主线以 CLI 消息为交互入口以 BSP 算法为核心布局引擎以 Accessibility/屏幕录制/SIP 权限为能力边界。建议的落地路径是先按第三章核对系统要求并授予辅助功能权限再以 examples/yabairc 为模板初始化全局配置随后用 examples/skhdrc 绑定高频操作最后按需深入 doc/yabai.asciidoc 探索规则、信号与查询等进阶能力——这套组合足以构成一套稳定、高效的 macOS 键盘驱动窗口管理工作流。【免费下载链接】yabaiA tiling window manager for macOS based on binary space partitioning项目地址: https://gitcode.com/gh_mirrors/ya/yabai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考