# KDE Wayland 虚拟屏：krfb-Virtualmonitor + Sunshine 串流


## 我的环境

- CachyOS（Arch 系）
- KDE Plasma 6 + Wayland
- NVIDIA RTX 2070 Mobile，专有驱动 570
- Sunshine v2025.x

## 实施步骤

### 1. 安装依赖

```bash
sudo pacman -S krfb kscreen
```

`krfb` 提供 `krfb-virtualmonitor` 命令，`kscreen` 提供 `kscreen-doctor` 用来调分辨率/刷新率。

### 2. 创建虚拟屏

```bash
krfb-virtualmonitor --resolution 2560x1440 --name sunshine-vm --password pass --port 5905 &
```

参数说明：

- `--resolution`：虚拟屏的初始分辨率。给大一点（比如 2560x1440 或 3840x2160），之后可以用 `kscreen-doctor` 切到你实际需要的分辨率
- `--name`：随便取，后面 `kscreen-doctor` 会用到
- `--password` / `--port`：VNC 密码和端口。你用 Moonlight 不需要 VNC 访问，但这两个参数是必填的，随便填就行

运行后打开「系统设置 → 显示和监控」，你应该能看到新出现的虚拟显示器。

验证一下：

```bash
kscreen-doctor -o | grep -A5 Virtual
```

### 3. 配置 Sunshine

关键一步：Sunshine 的默认捕获模式是 `kms`，它看不到 `krfb-virtualmonitor` 创建的输出（因为那是 Wayland 层的，不是 DRM/KMS 层的）。需要切成 `kwin` 模式。

Sunshine Web UI → Configuration → Advanced → Force Capture Method → 选 `kwin`。

然后重启 Sunshine：

```bash
systemctl --user restart sunshine
```

### 4. 设置刷新率

`krfb-virtualmonitor` 没有 `--refresh` 参数，默认 60Hz。要改刷新率：

```bash
# 单位是 mHz，120Hz = 120000
kscreen-doctor output.Virtual-sunshine-vm.addCustomMode.1920.1080.120000.full

# 应用
kscreen-doctor output.Virtual-sunshine-vm.mode.1920x1080@120
```

注意：`addCustomMode` 里写的是点数（`1920.1080.120000`），`mode` 里写的是 `1920x1080@120`。两个格式不要搞混。

验证：

```bash
kscreen-doctor -o | grep -A10 Virtual
```

输出里应该能看到 `*` 标记的当前模式和刷新率。

### 5. 可选：用 systemd user service 管理虚拟屏

如果你不想每次手动启动虚拟屏，可以写成 user service 开机自启。

```ini
# ~/.config/systemd/user/krfb-virtualmonitor.service
[Unit]
Description=Virtual display for Sunshine streaming
After=graphical-session.target
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/krfb-virtualmonitor --resolution 2560x1440 --name sunshine-vm --password pass --port 5905
ExecStartPost=/bin/sh -c 'sleep 3 && /usr/bin/kscreen-doctor output.Virtual-sunshine-vm.addCustomMode.1920.1080.120000.full && /usr/bin/kscreen-doctor output.Virtual-sunshine-vm.mode.1920x1080@120'
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical-session.target
```

```bash
systemctl --user daemon-reload
systemctl --user enable --now krfb-virtualmonitor.service
```

**必须是 user service**。system service 拿不到 `$WAYLAND_DISPLAY` 和 `$XDG_RUNTIME_DIR`，`krfb-virtualmonitor` 没法连接到 KWin。

`ExecStartPost` 里的命令做了三件事：等 3 秒让 KDE 注册虚拟屏 → 注册自定义模式（`addCustomMode`）→ 切换到该模式（`.mode.`）。**`addCustomMode` 只是注册，不会自动切**，必须再跟一行 `.mode.`。

如果要同时设置缩放：

```ini
ExecStartPost=/bin/sh -c 'sleep 3 && /usr/bin/kscreen-doctor output.Virtual-sunshine-vm.addCustomMode.2560.1440.120000.full && /usr/bin/kscreen-doctor output.Virtual-sunshine-vm.mode.2560x1440@120 && /usr/bin/kscreen-doctor output.Virtual-sunshine-vm.scale.1.5'
```

`--resolution`、`addCustomMode`、`.mode.` 三处的分辨率保持一致即可。缩放值按需改（`1.5` = 150%）。

> **Fractional scaling**：如果你用 `1.5` 这类非整数缩放，需要先在系统设置的「显示和监控」里打开「允许分数缩放」（Allow fractional scaling），否则 `kscreen-doctor` 会拒绝。或者在 `~/.config/kwinrc` 设 `XwaylandScaleOverride=150` 后重启 kwin。

如果你不想让虚拟屏一直占着资源，也可以联动 Sunshine 的 service 做到按需启停：

```ini
# ~/.config/systemd/user/sunshine.service.d/override.conf
[Unit]
Wants=krfb-virtualmonitor.service
After=krfb-virtualmonitor.service
```

这样 Sunshine 启动时自动拉起虚拟屏，Sunshine 退出时虚拟屏跟着停。

## 屏幕切换

Moonlight 客户端自带快捷键 `Shift + Ctrl + Alt + F1` ~ `F12` 切换虚拟桌面/屏幕。

连上 Moonlight 后按下这个组合键，就能在物理屏和虚拟屏之间切换。

如果你有两个以上屏幕（比如笔记本内屏 + 外接显示器 + 虚拟屏），F1/F2/F3 分别对应不同的输出。

## 参考链接

- [Reddit: Sunshine on KDE Wayland with krfb-virtualmonitor](https://www.reddit.com/r/MoonlightStreaming/comments/1tg1dnc/guide_sunshine_on_kde_wayland_virtual_display/)
- [KDE Discuss: How to create a virtual monitor](https://discuss.kde.org/t/how-to-create-a-virtual-monitor-display/2725)
- [krfb-virtualmonitor man page](https://linuxcommandlibrary.com/man/krfb-virtualmonitor)


---

> 作者: Nite  
> URL: https://www.nite07.com/zh-cn/posts/kde-virtual-display-sunshine/