Sway

Sway（缩写自 SirCmpwn's Wayland compositor[1]）是一款专为 Wayland 设计的合成器，旨在与 i3 完全兼容。根据官网所述：

Sway 是 Wayland 的合成器，也是 x11 的 i3 窗口管理器的替代品。它可以根据您现有的 i3 配置工作，并支持 i3 的大部分特性以及一些附加功能

若您喜欢视觉效果，也可以试试 swayfx^AUR，这是一个带有视觉效果的 Sway 分支。

Sway 的另一个分支 sway-scroll-git^AUR 具有滚动布局（如同 PaperWM 和 niri^包）。还支持动画效果、窗口内容缩放和概览模式。

安装

安装 sway^包。由于依赖关系紧密，请在更新 sway 时始终更新 wlroots。

注意：所有专有显卡驱动程序都不受支持，包括 NVIDIA。在 NVIDIA 驱动程序版本 495 之后，需要启用内核级显示模式设置并在运行 sway 时附加 --unsupported-gpu 参数。

您还可以安装 swaylock^包、 swayidle^包和 swaybg^包，用以锁定屏幕、设定空闲管理和设置壁纸。

默认的应用程序启动器为 wmenu^包，默认的终端模拟器是 foot。在启动 sway 之前，建议安装它们或在配置文件中设置新的启动器和终端。您可在 Sway wiki 的迁移指南上找到一些 i3 实用程序的其他 Wayland 兼容替代品。

启动

Sway 在启动之前需要访问您的硬件设备（如键盘、鼠标和显卡），这些硬件设备的集合称为 seat，如同 sd-login(3) § DEFINITION OF TERMS 的 seat 小节所述。

在 Arch Linux 上，Sway 可以使用以下任一方式访问您的 seat。

systemd-logind(8) 和 polkit^包
seatd^包，会作为 wlroots0.20^包的依赖与 Sway 一起安装

若 polkit 已安装在您的系统上， Sway 应会自动访问你的 seat。

若 polkit 未安装在您的系统上，并且您想使用 seatd 来替代，请将您添加到 seat 用户组并启用/启动 seatd.service，然后重新登录。

您可以选择以下方法之一来启动 Sway。

手动启动

要启动 Sway，只需在 Linux 终端执行 sway。

自动启动

与 X 类似，可以通过将以下内容添加到 shell 初始化文件来启动 Sway（请参阅命令行解释器#登录 Shell）：

if [ -z "$WAYLAND_DISPLAY" ] && [ -n "$XDG_VTNR" ] && [ "$XDG_VTNR" -eq 1 ] ; then
   exec sway
fi

有关更多详细信息，请参阅 Xinit#登录时自动启动 X。

使用显示管理器启动

Sway 会话位于 /usr/share/wayland-sessions/sway.desktop。它可以被 GDM 和 SDDM 等现代显示管理器自动识别。

也可以将 systemd 用户服务作为一个显示管理器去运行 sway。

您还可以使用基于文本的显示管理器，请参阅显示管理器#控制台。

配置

若您已在使用 i3，则可以将 i3 配置文件复制到 ~/.config/sway/config，该文件开箱即用。否则，请将位于 /etc/sway/config 的示例配置文件复制到 ~/.config/sway/config。有关配置的信息参见 sway(5)。

注意：用户配置文件中应当包含 include /etc/sway/config.d/* 一行，以便从引置文件（drop-in files）中读取并应用配置。sway^包提供了一个引置文件 50-systemd-user.conf，其会将多个环境变量导入 systemd 用户会话和 dbus。一些应用需要这些环境变量以正常运行（如xdg-desktop-portal-wlr^包）。

键盘布局

默认情况下，sway 从 US QWERTY 键盘布局开始。配置多个键盘布局：

~/.config/sway/config

input * {
    xkb_layout "us,de,ru"
    xkb_variant "colemak,,typewriter"
    xkb_options "grp:win_space_toggle,caps:none"
}

input <identifier> xkb_model "pc101"

更多细节请参阅 xkeyboard-config(7) 与 sway-input(5)。

在启动 sway 时，也可以使用环境变量（XKB_DEFAULT_LAYOUT、XKB_DEFAULT_VARIANT 等）配置键盘布局。配置选项优先于环境变量。

打字延迟和速率

要更改打字延迟和速率，您可以在 input 节添加以下行：

~/.config/sway/config

input <identifier> repeat_delay 300
input <identifier> repeat_rate 30

状态栏

Sway 附带了一个默认状态栏，名为 swaybar ，可在纯 Wayland 环境中运行。swaybar 可以调用 shell 脚本或其他程序来在状态栏中显示信息。有关详细信息，请参阅 sway-bar(5) 与 swaybar-protocol(7)。

提示：swaybar 对托盘图标的支持并不完整，请考虑使用 waybar^包等替代方案，在 bar 节设置 swaybar_command waybar 即可启用。

i3status 是在 Wayland 下获取实用的默认状态栏的一个选项，您只需在 sway 配置的末尾添加以下代码段：

~/.config/sway/config

bar {
    status_command i3status
}

欲为 i3status 启用色彩输出，请在 i3status 配置中调整以下部分：

~/.config/i3status/config

general {
    colors = true
    interval = 5
}

Output

sway 的 output 命令可以为不同的显示输出指定详细配置，包括但不限于壁纸、缩放、位置等。如有需要，您可将不同的 output 命令整合到一行，例如：

~/.config/sway/config

output HDMI-A-1 mode 1920x1080 pos 1920 0 bg ~/wallpaper.png stretch

output 有多种方式匹配显示输出。可以使用其指定的输出名称，也可以使用 "*" 匹配所有显示输出，或是使用显示器的不同名称（由品牌、型号和序列号组成的字符串），例如：

~/.config/sway/config

output "Some Company ABC123 0x00000000" pos 1920 0

可以使用以下命令获取输出名称和一些其他信息：

$ swaymsg -t get_outputs

要深入了解配置和附加选项，请参阅 sway-output(5)。

壁纸

sway 用专用程序处理壁纸，最简单的例子是 swaybg^包，其可直接由 sway 管理。若要运行 output ... bg 命令，请安装 swaybg^包。

可以将以下行附加在 sway 配置的任意位置，其会在所有显示器上设置背景图像：

~/.config/sway/config

output "*" bg /path/to/image fill

当然，/path/to/image 应当被替换为存在的图像路径。

如果只需要纯色背景，可以按如下方式设置：

output * bg #000000 solid_color

请参阅 Sway wiki 以了解更多用于管理壁纸的工具。

HiDPI

注意：Xwayland 也会被缩放，且会降低分辨率[2]。欲以原始分辨率运行 Xwayland 下的程序，则需禁用缩放。您可使用一些工具临时禁用缩放，如使用 swaymsg：

swaymsg output "*" scale 1

欲恢复到自动设定则设为 0。

自动设定

Sway 默认使用整数倍缩放。若满足以下条件[3]：

屏幕通过 EDID（ Extended Display Identification Data，外部显示设备标识数据）提供有效的物理显示信息。

DPI（每英寸像素数）至少为 192。

屏幕分辨率的高至少为 1200 像素。

那么 Sway 会使用 2 倍缩放。一些设备（如 Framework Laptop 16）的 DPI 近似（但不是）192，在这种情况下，您可能需要手动配置分数倍缩放。

手动设定

在配置文件里用 output 命令设置缩放倍数。可以设置分数倍缩放，不过 HiDPI 屏幕通常为 2。

~/.config/sway/config

output <名称> scale <倍数>

可以使用以下命令获知显示器名称：

$ swaymsg -t get_outputs

撕裂

Sway 默认会同步帧更新（vsync，垂直同步）以使输出画面的每一帧都帧完整而不撕裂，但是会带来一些延迟。在一些使用场景（如游戏）下禁用垂直同步可以使输出更为顺畅：

~/.config/sway/config

output <name> allow_tearing yes
output * max_render_time off

输入设备

可以调整特定输入设备的配置。例如，若要为所有触摸板启用点击以单击和自然滚动，请使用以下配置：

~/.config/sway/config

input type:touchpad {
    tap enabled
    natural_scroll enabled
}

要为特定触摸板设定配置，请使用 swaymsg -t get_inputs 获取设备标识符并用其代替上述配置中的 type:touchpad。

注意：命令 swaymsg -t get_inputs 的输出可能会使用\来转义/等符号（如 "2:14:ETPS\/2_Elantech_Touchpad"），配置时需要删除\。

关于更多文档和选项（如加速度或完全禁用输入），请参阅 sway-input(5)。

若您使用数位板，请参阅 Graphics tablet#Sway（英语：Graphics tablet#Sway）。

触摸屏映射

在多显示器环境中，触摸屏的触摸输入目标可以仅被映射到该触摸屏。

~/.config/sway/config

set $display1      "Dell Inc. DELL P2414H VHVTW542165L"
set $display2      "Dell Inc. DELL P2418HT MYDM775F152L"
set $display2-touch "8146:24835:Melfas_LGD_AIT_Touch_Controller"

input $display2-touch map_to_output $display2

自定义快捷键

键盘上的特殊按键可用于执行命令，如控制音量、屏幕亮度和媒体播放：

~/.config/sway/config

# 将特定按键绑定到 pactl 以调整 PulseAudio 音量
bindsym --locked XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym --locked XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%
bindsym --locked XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle
bindsym --locked XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle

# 将特定按键绑定到 playerctl 以控制媒体
bindsym --locked XF86AudioPlay exec playerctl play-pause
bindsym --locked XF86AudioPause exec playerctl play-pause
bindsym --locked XF86AudioPrev exec playerctl previous
bindsym --locked XF86AudioNext exec playerctl next
bindsym --locked XF86AudioStop exec playerctl stop

# 将特定按键绑定到 brightnessctl 以控制屏幕亮度
bindsym --locked XF86MonBrightnessDown exec brightnessctl set 5%-
bindsym --locked XF86MonBrightnessUp exec brightnessctl set 5%+

# 将特定按键绑定到 grim 以截图
bindsym Print exec grim

# 将特定按键绑定到 wmenu-run 以启动应用程序
bindsym XF86Search exec wmenu-run

有关详细信息和替代实用程序，请参阅：

提示：bindsym 的 --locked 参数用于允许在锁屏下执行快捷键。

提示：wev^包工具提供类似于 xorg-xev^包的功能，但运行于 Wayland。

注意：Systemd 会处理一些特殊按键，如电源键和盖子打开/关闭事件。这可能会干扰在 sway 中配置的快捷键。请参阅 loginctl(1) 与 logind.conf(5) 以获取有关如何在 systemd 中配置它们的详细信息。

图形指示条

在调整某些百分比值设置（如亮度或音量）时，可以显示一个图形指示条。在 Sway 中提供此工具的一个不错的选择是 wob^包（或 wob-git^AUR），其是 Wayland 上 layer-shell 协议的实现，提供了流行的 X 工具 xob^AUR 的部分功能。有关使用示例，请参阅项目网站。

工作区概览

如果您在工作区开启了很多窗口，导致难以分辨，那么 sov^AUR 可以派上用场。它是一个叠加层，可以显示所有工作区的概览，使 sway 导航更容易。其可以显示程序名称、窗口标题，支持多 output 配置。关于详细信息，请参阅项目网站。

空闲管理

Sway 有一个名为 swayidle^包的专用空闲管理守护程序来处理空闲会话。可以用不同的方法来启动和参数化守护程序。最简单的方法是使用 sway 本身的配置。swayidle 接受大量参数来配置 timeout（超时，又名“空闲”）、resume（恢复，超时后从空闲中恢复）、before-sleep（睡眠前）等事件，请参阅 swayidle(1) 了解更多细节和事件的进一步解释。然后，可以为每个事件分配一个操作。要为一个事件分配多个操作，只需重复触发器即可。

以下配置可使 swayidle 在 30 分钟后锁定屏幕，并在 5 秒后将其关闭：

~/.config/sway/config

exec swayidle -w \
	timeout 1800 'swaylock -f' \
	timeout 1805 'swaymsg "output * power off"' \
		resume 'swaymsg "output * power on"'

要更快地关闭锁定屏幕，例如在10秒后，请为锁定管理器设置进程列表，并相应地执行 swaymsg "output * power off" ，如下：

timeout 10 'if pgrep -x swaylock; then swaymsg "output * power off"; fi' resume 'if pgrep -x swaylock; then swaymsg "output * power on"; fi'

要在屏幕锁定前挂起和暂停播放媒体，请将以下配置添加到 swayidle 命令：

before-sleep 'playerctl pause;swaylock -f'

注意：Systemd 也处理一些空闲事件，这些事件可能与在 sway 中配置的事件冲突。请参阅 loginctl(1) 和 logind.conf(5) 以获取关于如何配置它们的详细信息。

若您不希望在 Firefox、Chrome 或 VLC 播放视频时触发 swaylock，您可以用 idlehack-git^AUR 监听 dbus 的 screensaver inhibit（阻止屏保）请求并调用 swayidle-inhibit。Firefox、Chrome 和 VLC 等程序会发出该事件以阻止系统空闲。

恢复时屏幕内容短暂显示

使用 before-sleep swaylock 可能会使系统从睡眠中恢复时屏幕内容短暂显示。欲缓解该问题，您可使 logind 忽略盖子（lid）事件并改用 Sway 处理盖子和电源按钮事件。

/etc/systemd/logind.conf

[Login]
HandlePowerKey=ignore
HandlePowerKeyLongPress=ignore
HandleSuspendKey=ignore
HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore

~/.config/sway/config

bindswitch --locked lid:toggle exec swaylock --daemonize && systemctl sleep

exec swayidle -w \
          timeout 60  'if pgrep swaylock; then systemctl sleep; fi' \
          timeout 150 'swaylock --daemonize' \
          timeout 155 'systemctl sleep'

使用 --locked 选项以在屏幕锁定时合盖休眠系统。若要使笔记本在合盖后依然工作，使用 unbindswitch lid:toggle。可以使用 pgrep swaylock 以使电脑被意外唤醒后再次休眠。

logind 集成 bug 较多且难以维护。另见 [4]。

悬浮窗口和窗口分配

要启用悬浮窗口或窗口分配，请打开应用程序，然后使用 app_id、class、instance 和 title 属性来启用悬浮窗口/窗口分配。以下命令可以列出所有打开的窗口的属性：

$ swaymsg -t get_tree

欲获取所有打开的窗口的 app_id，请执行：

$ swaymsg -t get_tree | grep "app_id"

仅获取当前选中窗口的 app_id，请执行：

$ swaymsg -t get_tree | jq -r '..|try select(.focused == true)'

X11 窗口没有 app_id 属性，要匹配它们，您可以使用 class、window_type、window_role 和/或 instance 等属性。请在 swaymsg -t get_tree 命令的输出中查找相关属性并为窗口创建足够详细的规则。

~/.config/sway/config

for_window [app_id="galculator"] floating enable
for_window [window_type="dialog"] floating enable
for_window [window_role="dialog"] floating enable
assign [app_id="firefox"] 3
assign [class="^Urxvt$" instance="^htop$"] 9

这类似于在X11中使用 xorg-xprop^包查找 class 或 wm_name 属性。

使用多个显示器时，悬浮的 scratchpad（暂存器）窗口可能会变得很大，覆盖多个显示器。可以使用以下命令将悬浮窗口居中并调整为当前显示器大小的 80%：

$ swaymsg move position center; swaymsg resize set 80ppt 80ppt

剪贴板

参见剪贴板。

Xresources

在 Sway 中使用 ~/.Xresources 需要把它拷贝到~/.Xdefaults。

Xwayland

请参阅 Wayland#Xwayland 以了解详细信息和可用软件包的概述。

默认情况下 Xwayland 处于启用状态。

欲完全禁用 Xwayland 并运行“纯”Wayland 会话，请使用以下配置以禁用 Xwayland：

~/.config/sway/config

xwayland disable

若您想一眼知晓哪些窗口使用 Xwayland，可以使用以下配置：

~/.config/sway/config

for_window [shell="xwayland"] title_format "[XWayland] %title"

注意：一些程序需要特殊的环境变量或配置选项才能在原生 Wayland 下运行，而另一些程序（包括大多数专有应用程序）根本不支持 Wayland。目前，建议保持启用 Xwayland，以便使用旧版应用程序。

使用另一个 wlroots 渲染器

要使用另一个渲染器如 Vulkan，请参阅 Wayland#在基于 wlroots 的混成器上使用另一个渲染器。

程序自启动

参见 i3#自启动程序章节，并将配置文件名调整为适用于 Sway 的版本。

提示和技巧

启动时启用 NumLock

Sway 在启动时默认禁用 NumLock。欲使其自动启用，请将键盘的 xkb_numlock 输入配置设置为 enable。例如，欲使所有键盘如此，请将以下行添加到 Sway 配置：

~/.config/sway/config

input type:keyboard xkb_numlock enabled

任何情况下，都可以通过键盘上的相关按键来切换 NumLock 状态。

提示：如需，也可以用 xkb_capslock 以相同方式设置 CapsLock。

注意：用通配符启用这些可能会导致在重新加载 Sway 配置文件时 Firefox 崩溃，参见 Bugzilla 1652820，请尝试指定特定键盘而非通配符。

当前键盘布局

可以按如下方式通过 jq^包检索当前键盘布局，其中 kbd_identifier 需要替换为键盘的标识符：

$ swaymsg -t get_inputs | jq -r '.[] | select(.identifier == "kbd_identifier") | .xkb_active_layout_name'

组合键

组合键（compose key）和其它按键结合使用可用于输入键盘不支持的字符。例如将 PrintScreen 设为组合键：

$ swaymsg 'input * xkb_options compose:prsc'

可在 Xorg/Keyboard configuration#Configuring compose key（英语：Xorg/Keyboard configuration#Configuring compose key）查看可用的组合。组合也可以在 XCompose 文件（英语：Xorg/Keyboard configuration#Key combinations）中配置，需要重新启动应用程序才能使更改生效。

背光切换

若要使用某按键（如 Pause）关闭（和打开）显示器，请在 Swayconfig 中绑定以下脚本：

#!/bin/sh
read lcd < /tmp/lcd
    if [ "$lcd" -eq "0" ]; then
        swaymsg "output * power on"
        echo 1 > /tmp/lcd
    else
        swaymsg "output * power off"
        echo 0 > /tmp/lcd
    fi

也可以直接使用 toggle 选项，只是使用多显示器时需要明确指定 output：

$ swaymsg "output output_name power toggle"

屏幕捕获和屏幕共享

请查看屏幕捕获#Wayland.

色温调节

请查看背光#Wayland.

色彩管理

可以将以下行添加到 Sway 配置以使用色彩管理配置文件：

~/.config/sway/config

output * 色彩管理配置文件 icc /path/to/your/color_profile.icc

用键盘控制 swaynag

Swaynag 是 sway 附带的默认警告/提示程序，仅支持用户用鼠标与之交互。诸如 swaynagmode^AUR 之类的帮助程序可通过键盘快捷键启用交互。

Swaynagmode 的工作原理是首先启动 swaynag，然后侦听触发操作的信号，例如选择下一步按钮、关闭提示或接受所选按钮。这些信号会被另外的带有控制参数的 swaynagmode 脚本实例（如 swaynagmode --select right 和 swaynagmode --confirm）发送。

默认情况下，Swaynagmode 在初始化时触发 sway 的 nag 模式，在退出时返回 default。这样，您就可以在 sway 配置中轻松定义快捷键：

~/.config/sway/config

set $nag exec swaynagmode
mode "nag" {
  bindsym {
    Ctrl+d    mode "default"

    Ctrl+c    $nag --exit
    q         $nag --exit
    Escape    $nag --exit

    Return    $nag --confirm

    Tab       $nag --select prev
    Shift+Tab $nag --select next

    Left      $nag --select next
    Right     $nag --select prev

    Up        $nag --select next
    Down      $nag --select prev
  }
}

注意：从 sway 版本 1.2 开始，模式名称区分大小写。

您可将 sway 配置为通过配置命令 swaynag_command swaynagmode 使用 swaynagmode。

更改光标主题和大小

要设置光标主题和大小，请使用以下配置：

~/.config/sway/config

seat seat0 xcursor_theme 光标主题 光标大小

其中光标主题可以设置或替换为特定名称（如 default、Adwaita 或 Simple-and-Soft），以及光标大小值如 48。

要查看二者的值，可以使用 echo $XCURSOR_SIZE 和 echo $XCURSOR_THEME。

更改配置后需要重新加载 Sway 以使更改生效。

注意：Wayland 光标可由应用程序确定，这意味着应用程序可能不会遵循 $XCURSOR_SIZE 和 $XCURSOR_THEME 的值。

使用 systemd 管理仅用于 Sway 的守护程序

Systemd 提供 graphical-session.target 和 graphical-session-pre.target 用户单元。

Services can be made PartOf= either unit to let them run as long as or before, respectively, any graphical session is running and terminate them cleanly when exiting it, whether Xorg or Wayland.

If Sway is the only window manager on a machine, then graphical-session.target may be sufficient even for Sway-specific services (like swayidle^包 or kanshi); but otherwise, a more specific sway-session.target file can be used (such as the one provided by sway-contrib^包).

Additionally, services started by systemd need to be informed of the necessary environment variables; this is taken care of by a file in /etc/sway/config.d/ provided by sway^包, which should be processed if the note at the top of #Configuration has been followed. (But those environment variables should also be unset when exiting Sway, otherwise it or other services may fail to start after the first exit.)

All this can be done using sway-systemd-git^AUR or uwsm^包 (which also take care of #Working with systemd-oomd), or manually.

注意：sway-services-git^AUR has unit startup order issues. [5]

手动配置

将以下行添加到 Sway 的配置文件中（例如，将该行追加到 ~/.config/sway/config或将新文件添加到 /etc/sway/config.d/）：

~/.config/sway/config

...
...
...
exec_always systemctl --user start sway-session.target

This ensures that sway-session.target is activated whenever Sway starts, and after it has created the Wayland socket etc. Make sure to place that line after any commands that affect how systemd services would be started, which generally includes the include /etc/sway/config.d/* directive.

Then, arrange for the target to be stopped before Sway exits. Note that systemctl --user stop sway-session.target will not work, as the command returns before the services are done shutting down; consider creating a unit that Conflicts= with that, and starting it instead [6].

Finally, link the desired services to sway-session.target or graphical-session.target:

If an existing service file exists, you can enable it, or (such as if that would not link to the right unit) run systemctl --user add-wants sway-session.target foo.service.

You can find an example of creating a brand new service file at kanshi#Manage kanshi with systemd.

Working with systemd-oomd

systemd-oomd(8) tracks resource usage by and kills entire Cgroups at once, not processes. This means that, by default, a single memory-hungry service will cause the entire Sway session to be terminated.[7]

The solution is to start each application in its own cgroup. Some of the packages recommended in #Manage Sway-specific daemons with systemd, like uwsm^包 or sway-systemd-git^AUR, already take care of this. But it can also be accomplished manually by ensuring that applications are started via systemd-run (see systemd-run(1)).

Instead of using a swaymsg exec -- foo command, create a script:

~/.local/share/sway_exec_wrapper

#!/usr/bin/env sh
exec systemd-run --user --ignore-failure --scope --unit "app-$1-$(uuidgen)" -- "$@"

and use swaymsg exec ~/.local/share/exec_wrapper -- foo.

提示：If #Manage Sway-specific daemons with systemd has been followed, add -p PartOf=graphical-session.target to let the application exit cleanly when exiting Sway.

The --ignore-failure option is used, because a graphical application's unclean exit should not cause the system state to become "degraded"; --scope so that the initial process can fork without the entire application being closed and for Sway to assign the first window to the correct workspace. The --unit parameter is named according to systemd's recommendations.

启动后更改屏幕分辨率/布局

您可使用 GUI 程序 nwg-displays^包、wdisplays^包、swayrandr-git^AUR 或终端程序 wlr-randr^包来更改屏幕分辨率和方向、排列显示器以及设定缩放。

创建无外设（Headless）输出

创建与物理 video 接口无关的输出（HEADLESS-1、HEADLESS-2等）：

$ swaymsg create_output

显示新输出的说明：

$ swaymsg -pt get_outputs | grep -A 10 HEADLESS

使用 output 命令配置新的输出，例如：

~/.config/sway/config

output HEADLESS-1 {
pos 1920,0
mode 1280x720@75Hz
}

将修饰键（modifier）修改为 CapsLock 并保留 Super

要将修饰键更改为 CapsLock 并在 US 键盘布局上继续使用 Super，请创建 ~/.config/xkb/symbols/custom，具有以下内容：

~/.config/xkb/symbols/custom

xkb_symbols "basic" {
    include "us"
    name[Group1]= "English (US Custom)";
    key <CAPS> { [ Hyper_L ] };
    modifier_map Mod4 { Hyper_L };
    key <LWIN> { [ Super_L ] };
    modifier_map Mod5 { Super_L };
};

对于其他语言，请编辑第二行和第三行，并在 Sway 配置文件开头附加引用该键盘布局：

~/.config/sway/config

input * xkb_layout custom
set $mod Mod4
set $super Mod5

通过 VNC 远程访问无外设（Headless） Sway 会话

以下示例教程讲述了通过 SSH 启动并通过 VNC 远程访问无外设 Sway 会话。

wayvnc^包是一个 VNC 服务器，适用于基于 wlroots 的 Wayland 混成器，可以用于承载无外设 Sway 会话。

要启动一个无外设 Sway 会话，请将 WLR_BACKENDS 设为 headless，可选将 WLR_LIBINPUT_NO_DEVICES 设为 1（参见 wayvnc FAQ）：

$ WLR_BACKENDS=headless WLR_LIBINPUT_NO_DEVICES=1 sway

提示：在命令结尾添加 & 以使其后台运行。

现在，请运行 wayvnc 以启动 VNC 服务器：

$ WAYLAND_DISPLAY=wayland-1 wayvnc

注意：默认情况下，wayvnc^包仅会监听本机 5900 端口（localhost:5900），可以另行配置（参见 man wayvnc）。您可能会想按照 OpenSSH#转发其他端口所述转发端口。请注意 wayvnc^包默认不加密且不验证身份！

输出热插拔钩子

若您想在一个输出连接（或断开连接）时搞点事情，可以阅读 kanshi。

疑难解答

应用程序启动器

提示：Sway wiki 包含一个已知应用程序启动器列表。

以下应用程序启动器已知和 Sway 集成良好：

wmenu^包 or bemenu^包 are largely drop-in replacements for dmenu.

rofi now supports Wayland natively, but wofi^包 is still a good alternative.

fuzzel^包 is an application launcher similar to rofi's drun mode.

Any dmenu replacement can be combined with j4-dmenu-desktop^包's --dmenu option to make an equivalent of i3-dmenu-desktop(1).

krunner(1) (from plasma-workspace^包) can be used stand-alone.

You can also build your own with a floating terminal and fzf^包.

dmenu^包 and other non-Wayland launchers also function well in Sway, but run under Xwayland and suffer from an issue where they can become unresponsive if focus is moved to a native Wayland window.

If Xwayland is enabled and bemenu^包 does not run under Wayland by default (thus being subject to the above issues), set the BEMENU_BACKEND=wayland environment variable.

虚拟化

Sway 可以在 VirtualBox 和 VMware ESXi 中使用。

要使 Sway 在 QEMU 中工作，必须以 -vga qxl 参数启动QEMU。另见 QEMU#qxl。

无法从 tty 启动 Sway

对于 ESXi，您需要在 Hardware Configuration > Video card settings 下启用 3D 支持。另见 VMware#在 Intel、Optimus 和 AMD 上启用 3D 图形加速。

光标不可见

当使用某些图形驱动程序（例如VMSVGA图形控制器或专有的 NVIDIA 驱动）时，光标可能会变得不可见。可以使用软件光标来解决此问题，具体讨论参见 Issue 3814：

$ export WLR_NO_HARDWARE_CURSORS=1

未检测到 sway socket

使用 swaymsg 时（如 swaymsg -t get_outputs）有时会返回以下消息：

sway socket not detected.
ERROR: Unable to connect to

当在终端多路复用器（如 GNU Screen 或 tmux）内运行时，swaymsg 无法连接到 SWAYSOCK 中提供的套接字。

要查看当前 SWAYSOCK 的值，请执行：

$ env | grep -F "SWAYSOCK"

SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock

欲解决该问题，您可以尝试连接到一个正在运行的 sway 进程的套接字：

$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock

欲避免此错误，请在终端多路复用器之外运行该命令。

无法连接 Wayland 服务器

Tmux 会为每个会话创建环境变量（执行 tmux show-environment 以查询），因此，若您想要使用 tmux-resurrect 或 tmux-continuum 重新恢复一个已有的 tmux 会话，或 tmux 服务器在 sway 启动前就在运行，环境变量就会过期。

将以下内容添加到 .tmux.conf，之后您可以在恢复会话前使用 update-environment 更新环境变量：

set-option -g update-environment "DISPLAY WAYLAND_DISPLAY SWAYSOCK SSH_AUTH_SOCK"

无法获取 socket 路径

从 swaymsg -t 命令请求在tty上的消息可能会返回以下消息：

Unable to retrieve socket path

SWAYSOCK 环境变量在启动Sway后设置，因此解决此错误的一个方法是在Sway内部的终端中请求 swaymsg -t [message]。

按键设置和键盘布局

默认情况下，如果您使用多个键盘布局（如 input * xkb_layout "us,ru"），在切换到某个次要布局时可能会导致快捷键失效。

得益于 Pull 3058 ，现在您只需在相应的 bindsym 行中添加 --to-code，如下：

bindsym --to-code {
  $mod+$left focus left
  $mod+$down focus down
  $mod+$up focus up
  $mod+$right focus right
}

亦可创建一个变量 set $mybind bindsym --to-code，然后将所有的 bindsym 替换为 $mybind，如下：

$mybind $mod+w thing

Java 应用程序

当打开一些基于Java的应用程序（如 JetBrains的 IntelliJ、CLion 或 PyCharm）时，可能会显示空白画面。欲解决该问题，可以将环境变量 _JAVA_AWT_WM_NONREPARENTING 设为 1 来启动应用程序。

若您从应用程序启动器（如 rofi 或 dmenu）启动应用程序，则可以修改应用程序的桌面项。

OpenJDK 11 和 Sway 1.5 已经修复了一些 Java 应用程序的问题。然而，对于某些应用程序，需要进行额外的配置才能使用更新版本的 OpenJDK。对于 Android Studio，您需要设置 STUDIO_JDK=/usr/lib/jvm/java-11-openjdk/[8]。

JRE 硬编码了一个窗口管理器列表，但该列表不包含 Sway，若您遇到灰色面板、菜单无焦点或窗口尺寸调整错误等问题，可以尝试伪装成其它窗口管理器。

边框上的滚动

如果在应用程序边框上使用鼠标滚轮导致Sway崩溃，您可以为 app_id（例如Firefox）使用border none 来禁用边框。

“cannot open display” 错误

如果一个程序启动后出现“cannot open display”（无法打开显示器）并崩溃，那么该应用程序很可能是 X11 程序。您可以使用 Xwayland 兼容层在 Wayland 下运行 X11 程序，详见 #Xwayland。

WINE 中鼠标不工作

运行程序时，WINE 需要设定一个主显示器（primary monitor），但是 Wayland 没有主显示器的概念，这会引发问题（如 “clicks not registering”）。您可以使用 xrandr 为 Xwayland 指定主显示器，只需向您的 Sway 配置添加以下内容：

~/.config/sway/config

...
exec_always xrandr --output XWAYLAND0 --primary
...

若如此做，因为 Sway 的一个 bug，您需要将屏幕显示偏移量设为 0,0。

需要注意 XWAYLAND0（或其它 XWAYLAND 显示名称）可能不代表您的显示器，其后缀数字也可能在不同会话中变化。可以使用以下配置，其可将第一个 XWAYLAND 显示设定为主显示器：

exec_always xrandr --output $(xrandr | grep -m 1 XWAYLAND | awk '{print $1;}') --primary

您可按需调整此配置，使用不带参数的 xrandr 命令可以查看各

注意：Xwayland 会把新连接的显示器识别为全新的显示器，这包括了关闭后又重新打开的显示器。若您设置的“主显示器”也被关闭后又打开，其将不再被视为主显示器。

NVIDIA GPU 上游戏闪烁

即便官方不支持 NVIDIA 之类的专有驱动，但依然可以使用，甚至可以用来玩游戏。若如此做，您可能会看到屏幕上半区闪烁，可以尝试将 wlroots0.19^AUR 替换为 wlroots-nvidia^AUR，也可以手动用补丁编译您自己的版本。

System freezes when toggling output power on hybrid NVIDIA setups

On hybrid-GPU laptops with an external monitor connected to the NVIDIA GPU, using swaymsg "output * power off" (e.g. via swayidle^包) can deadlock nvidia-modeset, freezing the whole desktop. Confirm with journalctl -b -1 -g "blocked for more than": a task sway state:D ... blocked on a semaphore likely last held by task nvidia-modeset line means this is the cause. Workaround: avoid powering off NVIDIA-attached outputs, e.g. target only the integrated GPU's output or suspend the system instead. See wlroots#2474.

屏幕捕获/WebRTC 不工作

确保您的配置包含以下内容：

include /etc/sway/config.d/*

然而，AUR 的部分 -git 软件包不提供 /etc/sway/config.d，此时您需要添加：

exec dbus-update-activation-environment DISPLAY I3SOCK SWAYSOCK WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

参见