Windows Qt Creator + WSL 开发 Linux 应用环境准备指南
本文档详细说明如何在 Windows 系统下使用 Qt Creator 配合 WSL（Windows Subsystem for Linux）搭建 Linux 应用程序开发环境，包括基础工具安装、SSH 远程连接配置、Qt Creator 设备与套件设置以及图形界面显示支持。
- 准备工作
Windows 环境：已安装 Qt Creator（建议最新版本）并启用 WSL 功能。
WSL 发行版：已安装 Ubuntu（18.04 / 20.04 / 22.04 均可，本文以 Ubuntu18.04 为例）。
- 在 WSL Ubuntu 中安装基础工具与 Qt 开发库
2.1 更新包列表并安装基础构建工具
打开 WSL Ubuntu 终端，执行以下命令：
sudo apt updatesudo apt install build-essential cmake gdb git -y
2.2 针对 Ubuntu 18.04 升级 CMake（可选）
Ubuntu 18.04 自带的 CMake 版本可能过低，推荐升级到 3.22 以上。执行以下命令安装官方二进制版本：
卸载旧版 CMakesudo apt remove cmake -y 下载 CMake 3.22 二进制包wget https://github.com/Kitware/CMake/releases/download/v3.22.1/cmake-3.22.1-linux-x86_64.tar.gztar -xzf cmake-3.22.1-linux-x86_64.tar.gzsudo mv cmake-3.22.1-linux-x86_64 /opt/cmakesudo ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake
2.3 安装 Qt 开发库
根据项目需求选择Qt5或Qt6（二者选其一），本文已qt5为例。
安装 Qt5：
sudo apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qt5-default -y
安装 Qt6：
sudo apt install qt6-base-dev qt6-tools-dev qt6-tools-dev-tools -y
2.4 安装运行 GUI 程序所需的额外依赖
为避免运行 Linux 图形程序时出现 xcb 相关库缺失错误，请安装以下依赖：
sudo apt install libgl1-mesa-dev libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-xinerama0 -y
2.5 验证安装
执行以下命令检查各工具版本，若能正常输出版本信息则安装成功。
qmake6 --version # 若安装 Qt5，使用 qmake --versiongcc --versiongdb --version
- 配置 SSH 服务（用于 Qt Creator 远程连接）
3.1 安装 OpenSSH Server
sudo apt update && sudo apt install openssh-server -y
3.2 修改 SSH 配置，允许密码登录
编辑 SSH 配置文件：
sudo nano /etc/ssh/sshd_config
找到以下两行并确保其状态为（去掉#注释）：
PasswordAuthentication yesChallengeResponseAuthentication yes
保存并退出（Ctrl+O → 回车 → Ctrl+X）。
3.3 重新生成主机密钥
执行以下命令自动生成 RSA、ECDSA、Ed25519 三种密钥：
sudo ssh-keygen -A
生成后重启 SSH 服务：
sudo service ssh restart
3.4 测试 SSH 连接
3.4.1 在 WSL 内部自测
ssh localhost
输入当前 WSL 用户的密码，若能成功登录则说明 SSH 服务正常运行。
3.4.2 从 Windows PowerShell 测试
首先获取 WSL 的 IP 地址（在 WSL 终端中执行）：
hostname -I
假设得到的 IP 为172.x.x.x，在 Windows PowerShell 中执行：
ssh 你的用户名@172.x.x.x -p 22
输入密码，若能登录则 SSH 配置成功。
注意：若连接失败，可尝试使用systemctl彻底重启 SSH 服务：
sudo systemctl stop ssh.servicesudo systemctl stop ssh.socketsudo systemctl daemon-reloadsudo systemctl start ssh.socketsudo systemctl start ssh.service
- 在 Qt Creator 中添加远程 Linux 设备（WSL）
4.1 添加设备
打开 Qt Creator，进入编辑→Preferences（设置）→设备（Devices）。
点击添加（Add），选择Remote Linux Device（远程 Linux 设备）。
填写设备名称（如WSL-Ubuntu），主机名填写 WSL 的 IP 地址（如172.x.x.x），用户名填写 WSL 登录用户名，认证方式选择密码或密钥（推荐密钥）。
4.2 生成并部署 SSH 密钥（推荐）
在设备设置窗口，点击创建新密钥对按钮，Qt Creator 会自动生成 RSA 密钥对并保存到 Windows 用户目录（C:\Users\你的用户名.ssh\）。
生成后，点击部署公钥按钮。
在弹出的密码输入框中输入 WSL 用户的登录密码，Qt Creator 会自动将公钥添加到 WSL 的~/.ssh/authorized_keys文件中。
部署成功后会有提示。
4.3 测试连接
在设备设置页面点击测试连接（Test Connection），若显示成功则表示 Qt Creator 可与 WSL 正常通信。
- 配置 Qt Creator 的构建套件（Kit）
5.1 添加 Qt 版本、编译器、调试器和 CMake
在Preferences→Kits（套件）中，Qt Creator 通常会自动检测到 WSL 中的 Qt 安装、GCC 编译器和 GDB 调试器。若未自动检测，可手动添加：
Qt 版本：选择 WSL 中的qmake路径（例如/usr/bin/qmake6）。
编译器：选择 WSL 中的gcc和g++。
调试器：选择 WSL 中的gdb。
CMake：选择 WSL 中的cmake路径。
5.2 创建构建套件
在Kits页面点击添加（Add）。
选择设备为之前添加的 WSL 设备。
分别指定 Qt 版本、C/C++ 编译器、调试器和 CMake 工具。
套件名称可自定，例如WSL-Qt6。
点击Apply保存。
- 配置 X Server 显示环境（用于运行 GUI 程序）
6.1 在 Windows 上安装并启动 X Server
推荐使用VcXsrv（免费开源）：
下载地址：https://sourceforge.net/projects/vcxsrv/
安装完成后，启动XLaunch。
配置选项：
Display number：保持-1。
选择Multiple windows。
务必勾选“Disable access control”（禁用访问控制，允许任意客户端连接）。
完成配置，保持 X Server 后台运行（系统托盘中会有图标）。
6.2 在 WSL 中设置 DISPLAY 环境变量
6.2.1 获取 Windows 主机在 WSL 网络中的真实 IP
在 WSL 终端执行：
ip route | grep default | awk '{print $3}'
会得到一个类似172.19.64.1的地址，记下该 IP（后续会用到）。
6.2.2 临时设置 DISPLAY 并测试
在当前终端临时设置（替换为实际 IP）：
export DISPLAY=172.19.64.1:0.0
6.2.3 永久设置（写入 .bashrc）
为避免每次重启终端都要设置，将以下命令写入~/.bashrc：
echo "export DISPLAY=$(ip route | grep default | awk '{print $3}'):0.0" > ~/.bashrc_tempcat ~/.bashrc_temp >> ~/.bashrcrm ~/.bashrc_tempsource ~/.bashrc
6.3 在 Qt Creator 的 Kit 中直接设置环境变量（推荐）
为确保 Qt Creator 启动的每个进程都带有正确的DISPLAY，在套件中设置环境变量：
打开Tools→Options→Kits。
选择你创建的 WSL 套件（如WSL-Qt6）。
在右侧找到Environment（环境），点击Edit Build Environment...（或Edit Run Environment...，建议两者都设置）。
点击Add（添加），填写：
变量名：DISPLAY
值：之前获取的 IP 地址 +:0.0（例如172.19.64.1:0.0）
点击OK保存，再点击Apply→OK退出。
6.4 测试图形界面是否正常
安装x11-apps并运行测试程序xeyes：
sudo apt install -y x11-appsxeyes
若出现一个眼睛跟随鼠标的窗口，则说明 X Server 配置成功。
- 完成
至此，你的 Windows Qt Creator + WSL Linux 应用开发环境已全部准备就绪。现在你可以创建或导入 Qt 项目，项目目录需为wsl中的目录，选择 WSL 套件进行编译、调试，并运行图形界面程序。
注意事项：
若 WSL 版本较新（如 WSL 2），网络 IP 可能会变化，建议每次启动后确认DISPLAY是否正确。
若 SSH 连接失败，可检查防火墙是否允许 22 端口，或尝试重启 WSL 终端。
在 Qt Creator 中若无法自动检测到工具链，可手动指定 WSL 中的路径（通过\wsl$\Ubuntu\usr\bin...访问）。
**参考：https://blog.csdn.net/writemans/article/details/161883925 **
浙公网安备 33010602011771号