在 VSCode 中配置 SSH 并实现 X11 转发：服务器程序远程桌面显示
在 VSCode 中配置 SSH 并实现 X11 转发（Windows、macOS、Linux）
你需要在VSCode中配置支持X11转发的SSH连接，实现远程运行带图形界面的程序、窗口能映射到本地显示的效果，核心需要完成本地X11服务搭建、远程服务器SSH配置开启X11、VSCode的SSH插件配置三步，下面分Windows/macOS/Linux三大系统详细说明（Windows是最常用且步骤稍多的场景，重点讲解）。
前提准备
VSCode已安装Remote - SSH插件（微软官方的，插件ID：
ms-vscode-remote.remote-ssh）；本地能通过SSH正常连接远程Linux服务器（账号、密码/密钥已配置）；
远程服务器是Linux系统（X11是Linux/Unix的图形转发协议，Windows服务器不适用）。
一、Windows系统（本地）配置步骤
Windows本身没有内置X11服务，需要先安装X11服务器软件，推荐轻量易用的Xming或VcXsrv（VcXsrv是开源免费的，更推荐）。
步骤1：安装并配置VcXsrv（本地X11服务）
下载VcXsrv：官网下载，直接安装（下一步到底即可）；
启动VcXsrv：桌面找到XLaunch，按向导配置：
第1步：选择Multiple windows（多窗口，推荐），点击Next；
第2步：选择Start no client（仅启动X11服务，不启动默认程序），点击Next；
第3步：取消勾选Native opengl（关键！勾选会导致部分图形程序闪退），勾选Disable access control（允许远程服务器连接本地X11，否则会权限拒绝），点击Next；
第4步：直接点击Finish，桌面右下角会出现VcXsrv的图标（X形状），表示X11服务启动成功。
关键：VcXsrv需要一直后台运行，关闭则X11转发失效；可将XLaunch添加到Windows开机启动，避免每次手动打开。
步骤2：配置Windows系统环境变量（告诉SSH本地X11地址）
SSH需要通过环境变量DISPLAY知道本地X11服务的地址，Windows下配置：
右键「此电脑」→「属性」→「高级系统设置」→「环境变量」；
在用户变量中，点击「新建」，添加变量：
变量名：
DISPLAY变量值：
localhost:0.0（固定值，对应VcXsrv的默认监听端口）；
点击确定保存，重启VSCode让环境变量生效（重要）。
步骤3：远程Linux服务器开启X11转发（核心配置）
需要修改服务器的SSH配置文件sshd_config，确保X11相关选项开启，操作如下：
远程登录服务器，执行命令编辑配置文件（需要root权限）：
sudo vi /etc/ssh/sshd_config找到以下配置项，修改为对应值（如果注释掉了，先删除
#取消注释）：X11Forwarding yes # 开启X11转发，必须为yes X11UseLocalhost no # 关键！Windows下必须设为no，否则会端口映射失败 X11DisplayOffset 10 # 可选，默认值即可，避免端口冲突 AllowTcpForwarding yes # 开启TCP转发，X11依赖此选项 PermitTunnel yes # 可选，增强转发兼容性保存并退出vi（按
Esc，输入:wq回车）；重启服务器的sshd服务，让配置生效：
# CentOS/RHEL/Fedora sudo systemctl restart sshd # Ubuntu/Debian sudo service ssh restart验证服务器是否安装X11基础库（如果远程没有图形库，运行图形程序会报错）：
# Ubuntu/Debian sudo apt install -y x11-apps # 包含xeyes、xclock等测试工具 # CentOS/RHEL/Fedora sudo dnf install -y xorg-x11-apps
步骤4：VSCode配置SSH连接（开启X11转发）
打开VSCode，按
F1，输入Remote-SSH: Open SSH Configuration File，选择用户级配置文件（如C:\Users\你的用户名.ssh\config，推荐）；在配置文件中，为你的远程服务器添加/修改配置，必须加上
ForwardX11 yes和ForwardX11Trusted yes：# 示例配置（按需修改Host、HostName、User、IdentityFile） Host my-server # 自定义连接名，VSCode中显示的名称 HostName 192.168.1.100 # 远程服务器IP/域名 User root # 远程登录账号 Port 22 # SSH端口，默认22 IdentityFile C:\Users\你的用户名\.ssh\id_rsa # 可选，密钥登录的私钥路径，密码登录可省略 ForwardX11 yes # 核心！开启X11转发 ForwardX11Trusted yes # 信任X11转发，避免权限问题 ConnectTimeout 30 # 可选，连接超时时间保存配置文件，按
F1输入Remote-SSH: Connect to Host，选择上面的my-server，输入密码/确认密钥，连接远程服务器；连接成功后，VSCode右下角会显示「SSH: my-server」，表示已进入远程开发环境。
步骤5：测试X11转发是否生效
在VSCode中打开远程终端（终端→新建终端，默认是远程服务器的终端）；
执行测试命令
xeyes（会弹出一个跟着鼠标动的眼睛窗口），或xclock（时钟窗口）：xeyes如果本地弹出对应的图形窗口，说明X11转发配置成功；如果报错，看文末「常见问题排查」。
二、macOS系统（本地）配置步骤
macOS内置了X11服务的基础组件，但需要安装XQuartz（苹果官方的X11实现），步骤比Windows简单：
安装XQuartz：官网下载，安装后必须重启Mac（核心，否则X11服务不生效）；
启动XQuartz：启动台找到XQuartz，打开后会自动运行X11服务，无需额外配置；
远程服务器配置：和Windows步骤3完全一致（
sshd_config中X11Forwarding yes，X11UseLocalhost no）；VSCode SSH配置：和Windows步骤4一致，配置文件中加上
ForwardX11 yes和ForwardX11Trusted yes；测试：远程终端执行
xeyes，本地会弹出图形窗口，直接生效。
三、Linux系统（本地）配置步骤
Linux系统本身原生支持X11，无需安装额外X11服务，步骤最简：
本地确保安装了X11基础库（一般桌面版Linux都自带，服务器版执行
sudo apt install x11-apps/sudo dnf install xorg-x11-apps）；远程服务器配置：仅需将
sshd_config中X11Forwarding yes开启即可（X11UseLocalhost可设为yes，也可no）；VSCode SSH配置：添加
ForwardX11 yes和ForwardX11Trusted yes；测试：远程终端执行
xeyes，本地直接弹出图形窗口。
四、常见问题排查（配置失败必看）
问题1：执行xeyes报错Error: Can't open display: localhost:10.0或DISPLAY is not set
原因1：本地X11服务未启动（Windows：VcXsrv没开；macOS：XQuartz没开）；
原因2：Windows未配置
DISPLAY环境变量，或未重启VSCode；原因3：远程服务器
sshd_config中X11UseLocalhost设为yes（Windows必须设为no）；解决：逐一检查上述三点，重启对应服务/VSCode。
问题2：执行xeyes报错No protocol specified或Permission denied
原因1：Windows的VcXsrv未勾选
Disable access control；原因2：VSCode SSH配置未加
ForwardX11Trusted yes；原因3：本地
DISPLAY环境变量值错误（必须是localhost:0.0）；解决：重新配置VcXsrv，补全VSCode的SSH配置项。
问题3：VSCode连接远程时卡住，或X11窗口卡顿
原因1：网络延迟高（X11是基于TCP的图形转发，对网络有一定要求）；
原因2：VcXsrv勾选了
Native opengl；解决：取消
Native opengl，使用有线网络，或降低远程图形程序的分辨率。
问题4：远程服务器执行图形程序，本地无窗口但无报错
原因：远程服务器的
DISPLAY环境变量未被正确映射（VSCode的SSH插件会自动设置，无需手动改）；解决：在远程终端执行
echo $DISPLAY，查看是否有值（如localhost:10.0），如果为空，重新连接VSCode的SSH。
总结
VSCode配置带X11的SSH核心要点：
本地必须有X11服务：Windows装VcXsrv（关OpenGL+开免访问控制）、macOS装XQuartz、Linux原生支持；
远程服务器关键配置：
sshd_config中X11Forwarding yes + X11UseLocalhost no（Windows必设no），重启sshd；VSCode SSH配置：必须添加
ForwardX11 yes和ForwardX11Trusted yes，Windows需配置本地DISPLAY=localhost:0.0并重启VSCode；测试用
xeyes/xclock，能弹出图形窗口即配置成功，后续可远程运行PyQt、Matplotlib、GCC图形调试等带界面的程序。