Quartz 4

🔍 搜索

Moonlight Windows 客户端安装、配对与使用指南

8 min read

Moonlight Windows 客户端安装、配对与使用指南

适用版本：Moonlight v6.1.0（moonlight-qt） 服务端：Sunshine（Linux） 场景：局域网低延迟桌面投屏

一、下载与安装

官方下载地址

https://github.com/moonlight-stream/moonlight-qt/releases

安装包选择

安装包说明
MoonlightSetup.exe标准安装包（推荐大多数用户）
MoonlightPortable-x64.zip便携版，解压即用，无需安装
MoonlightPortable-ARM64.zipARM64 设备（Surface/骁龙 PC）

版本说明：v6.1.0 要求 Windows 10 1809 或更高版本。 也可通过 Chocolatey 安装：choco install moonlight-qt

安装步骤

  1. 下载 MoonlightSetup.exe
  2. 双击运行，按提示点击 Next 完成安装
  3. 桌面或开始菜单找到 Moonlight 启动

二、首次配对流程

前置确认

  • Linux 端 Sunshine 服务正在运行（Web UI 可访问）
  • 两台机器在同一局域网（同一路由器下）
  • Linux 防火墙未拦截相关端口（无防火墙或已开放，见附录）

步骤一：添加 Linux 主机

方式 A：自动发现（推荐）

启动 Moonlight，等待几秒，如果 Sunshine 的 mDNS 服务正常，Linux 主机会自动出现在列表中。

方式 B：手动输入 IP

如果主机没有自动出现，点击右上角 + 按钮，输入 Linux 机器的局域网 IP：

192.168.3.104

点击 OK，主机图标出现在列表中（显示为锁定状态，表示未配对）。

步骤二：PIN 码配对

注意：PIN 码有效期约 30 秒，建议提前在 Linux 浏览器打开 Web UI 的 PIN 页面，再点 Moonlight 中的主机。

Moonlight 端操作：

点击主机图标，弹出 PIN 码提示，记下 4 位数字：

Please enter the following PIN on the target PC: 1234

Linux 端操作（Sunshine Web UI）：

在 Linux 浏览器打开（接受证书警告）：

https://localhost:47990

用设置的用户名密码登录后，点击左侧菜单 “PIN”，输入 Moonlight 显示的 4 位码，点击 “Send”。

确认配对成功：

  • Sunshine Web UI 显示绿色 “Success!”
  • Moonlight 中主机图标上的锁形图标消失
  • 此后点击主机进入应用/桌面列表

配对失败排查

现象原因解决
PIN 弹窗消失，操作超时超过 30 秒未输入重新点击主机图标，提前打开 Web UI PIN 页
Error 4: Request Timed Out防火墙拦截配对端口参见附录开放端口
Failed to pair to server版本不兼容升级 Sunshine 至最新版
配对成功但再次连接提示未授权配对记录损坏Sunshine Web UI → Client Devices 删除设备，重新配对

三、日常连接与使用

启动投屏

配对成功后，点击主机图标，进入应用列表：

  • Desktop：投屏 Linux 完整桌面（日常使用选这个）
  • 其他应用：在 Sunshine Web UI → Applications 中手动添加

点击 Desktop 开始串流，稍等片刻进入 Linux 桌面画面。

常用快捷键

快捷键功能
Ctrl + Alt + Shift + Q退出串流（Linux 桌面继续运行）
Ctrl + Alt + Shift + X全屏 / 窗口模式切换
Ctrl + Alt + Shift + Z释放 / 锁定鼠标捕获
Ctrl + Alt + Shift + S显示性能统计浮层（诊断延迟）
手柄：Start + Select + L1 + R1退出串流

四、画质与性能设置（Settings）

分辨率

场景推荐
1080p 显示器1920×1080
1440p 显示器2560×1440
不确定选 “Native”（跟随客户端屏幕）

帧率

场景推荐
日常桌面操作30 或 60 FPS
流畅交互60 FPS
低延迟优先60 FPS（不必追求 120）

码率（局域网有线）

分辨率 + 帧率推荐码率
1080p 30fps10–20 Mbps
1080p 60fps20–40 Mbps
1440p 60fps40–80 Mbps

局域网带宽充裕，可适当调高码率提升文字清晰度和色彩准确度。

视频解码

  • 保持默认硬件解码（Hardware）
  • 如果画面花屏或崩溃，临时切换到软件解码（Software）诊断

编解码器选择

编解码器说明
H.264兼容性最好，所有 GPU 均支持，首选
HEVC (H.265)同等质量码率更低，需要客户端 GPU 支持硬件解码
AV1质量最优，需要服务端 GPU 支持（Intel Arc 或新款 NVIDIA/AMD）

本机服务端为 Intel UHD 630，推荐选 H.264，HEVC 解码可能有兼容性问题。

其他推荐设置

设置项建议值说明
V-Sync开减少画面撕裂
Frame Pacing开帧率更平稳，减少微卡顿
音频Stereo确保服务端有可用音频输出

五、性能诊断

按 Ctrl + Alt + Shift + S 打开性能统计浮层：

Render Latency   : Linux 渲染耗时（ms）
Encoder Latency  : Sunshine 编码耗时（ms）
Network Latency  : 网络传输耗时（ms）
Decoder Latency  : Moonlight 解码耗时（ms）
Total Latency    : 总延迟（全链路）

诊断依据：

指标偏高排查方向
Network Latency 高检查网络，优先改用有线连接
Encoder Latency 高降低码率或分辨率；服务端 GPU 负载过高
Decoder Latency 高检查客户端是否开启硬件解码

六、常见问题排查

找不到主机

  1. 确认 Sunshine 正在运行： 
    XDG_RUNTIME_DIR=/run/user/1000 systemctl --user status sunshine.service
  2. 改用手动输入 IP 方式添加
  3. 确认两台机器在同一子网（无 VLAN 隔离）

连接失败（黑屏）

  • Linux 必须已登录图形界面（有显示器或已登录 GDM）
  • 确认 Sunshine 捕屏方式正确（X11 环境设 capture = x11）
  • 重启 Sunshine 服务后重试

无声音

Linux 服务端常见问题，参见进阶配置文档中的音频配置节。

快速排查：

# 确认 Sunshine 可访问 PipeWire/PulseAudio
XDG_RUNTIME_DIR=/run/user/1000 systemctl --user status sunshine.service
# 查看日志中是否有 audio 相关错误
XDG_RUNTIME_DIR=/run/user/1000 journalctl --user -u sunshine.service | grep -i audio

画面卡顿

  1. 改用有线网络
  2. 降低码率（先试试 20 Mbps 1080p 60fps）
  3. 关闭客户端侧其他高带宽任务
  4. 查看性能统计浮层定位瓶颈

附录：Sunshine 所需端口（Linux 防火墙配置）

如果 Linux 开启了 UFW 防火墙，需要开放以下端口：

# TCP 端口
sudo ufw allow 47984/tcp   # HTTP
sudo ufw allow 47989/tcp   # 配对
sudo ufw allow 47990/tcp   # Web UI
sudo ufw allow 48010/tcp   # RTSP
 
# UDP 端口（视频/音频流）
sudo ufw allow 47998/udp
sudo ufw allow 47999/udp
sudo ufw allow 48000/udp
sudo ufw allow 48002/udp   # 麦克风
 
# mDNS 自动发现
sudo ufw allow 5353/udp

本机当前防火墙状态：未启用（inactive），无需配置。

附录：Moonlight 撤销配对设备

在 Sunshine Web UI（https://localhost:47990）：

  1. 左侧菜单点击 “Client Devices”（或 “Devices”）
  2. 找到对应的 Windows 设备
  3. 点击删除图标，确认撤销
  4. 在 Moonlight 侧重新发起配对即可

Graph View

Backlinks