事情得从我把主力开发机从 22.04 升级到 Ubuntu 24.04 说起。升级完的第一个下午我就被 QtCreator 折腾得够呛老工程打开后编译器全部灰掉套件管理器里一片空白新装的 Qt Creator 死活找不到系统里的 g紧接着在几个社区讨论串里又看到一堆高频问题——有人开机左上角光标闪个不停黑屏进不去桌面有人 Grub 菜单离奇失踪有人 WSL 安装向导提前结束报错。我索性把自己踩过的坑、修好的和还没修好的问题都整理成这篇问题集合如果你是 Ubuntu 24.04 下用 QtCreator 做开发的希望这篇能帮你省下至少半天排查时间。1. QtCreator 在 Ubuntu 24.04 上的安装与 Kit 配置问题1.1 三种安装方式apt、官方安装器与 .run 离线包先说结论日常开发推荐 apt 装一个保底版本再用官方 .run 离线包装一个较新的 QtCreator 备用。原因很简单apt 仓库里的版本通常滞后一两个迭代但胜在依赖处理得干净装上就能跑官方离线包则能解决“新工程需要新版 Qt 支持”的问题比如某些 QML 模块版本较老导致 parser 报错。sudo apt install qtcreatorUbuntu 24.04 仓库默认带的 QtCreator 6.x安装完成后会自动检测系统已有的 Qt 版本。但注意如果你只装了 qtcreator 而没有装 qtbase-dev打开 .pro 工程时会提示找不到 qmake这就引出依赖问题了。Qt 官方在线安装器qt-unified-installer需要在 Qt 官网注册账号装起来很正规可以选择 Qt 6.5/6.6/6.7 等多版本库。缺点是网络慢、体积大国内网络环境下下载经常断。直接去 Qt 官方 archive 页面下载.run离线安装包以qt-creator-opensource-linux-x86_64-13.0.2.run为例下载后chmod x再运行即可。这个安装包不强制 root可以直接解包安装到~/qtcreator目录隔离性最好也不会污染系统 Python 环境。snap 版snap install qtcreator。我试过最大问题是沙箱权限——代码目录如果在/home下还好若放在/mnt/data这类挂载目录snap 默认访问不到要么在 snap connections 里手动连接 system-files要么放弃 snap 保平安。另外 Snap 版检测套件有时候会漏掉系统编译器。1.2 把 Qt Design Studio 生成的程序跑进 QtCreator这个需求在热词里出现频率很高。很多做 UI 设计的朋友用 Qt Design Studio简称 QDS拖完界面导出成 qmlproject 格式后拿到 QtCreator 里打开就抓瞎。先解释原理QDS 生成的是面向视觉设计的 qml 工程核心是.qmlproject文件加一堆.qml文件并不带 CMakeLists.txt。而 QtCreator 要运行一个工程必须有一个可构建的工程文件CMakeLists.txt 或者 .pro。所以核心工作就是“给 qml 工程补一个 CMake 壳”。实操步骤大致是这样在 QDS 里如果你的版本支持“Generate CMake Project”直接导出即可但多数版本没有这个选项。手工在工程根目录新建CMakeLists.txt最小内容如下cmake_minimum_required(VERSION 3.16) project(MyApp) find_package(Qt6 COMPONENTS Quick QuickControls2 REQUIRED) qt_standard_project_setup() qt_add_executable(MyApp main.cpp) qt_add_qml_module(MyApp URI MyApp VERSION 1.0 QML_FILES main.qml )如果原来没有 main.cpp补一个最简单的 C 入口里面创建 QGuiApplication、加载Main.qml即可。其实qt_add_qml_module会自动处理资源QML 文件会打进 qml 模块里不需要手写 qrc。在 QtCreator 里 File Open 打开这个 CMakeLists.txt然后选择套件构建。容易踩的第一个坑是模块缺失报错比如QML module not found (QtQuick.Studio.Components)这类。很多 QDS 工程依赖 Qt Quick Studio 系列特效组件这些组件不在开源社区版 Qt 里需要把 QDS 安装目录下的imports路径手动加到 QML import path在工程里加一行engine.addImportPath(路径/Qt Design Studio/.../imports);或者更省事直接把依赖的 .qml 文件复制到本地工程目录。实测后者的兼容性更好只是要注意许可证范围。第二个坑是QML 里引用了 QDS 专属类型如“粒子效果”或“页面切换动画”这些在标准 Qt 库中不存在换到 QtCreator 后编译不报错但运行时报一堆模块找不到。这类情况我一般建议重新在 QDS 里做降级处理把特效简化为可用 StackLayout Animation 实现的效果不值得为一个小动效卡整个工程。1.3 Kit 列表里编译器全部灰掉的排查顺序QtCreator 打开老工程套件管理界面里编译器显示“Invalid”或者压根没显示九成是下面三个原因之一。第一只装了 gcc 没装 g。Qt 默认用 g 编译 C 代码只装 gcc 会直接导致编译器无法识别。补一条命令sudo apt install build-essential g cmake ninja-build第二Qt 版本路径没有指向正确的 qmake。系统内同时存在 Qt5 和 Qt6 时最容易出现这个问题。Ubuntu 24.04 默认源里qtbase5-dev对应/usr/bin/qmakeqtchooser 的链接qt6-base-dev提供的是/usr/lib/qt6/bin/qmake。在 QtCreator 的菜单里进入 Tools → Options → Kits → Qt Versions手动添加/usr/lib/qt6/bin/qmake或者/usr/bin/qmake看你的工程需要哪个版本。添加后如果显示“qmake 版本无法解析”通常是缺少qt6-qmltooling或者qt6-tools-dev装上就行。第三CMake 工程需要导出 compile_commands.json。新版 QtCreator 对 CMake 工程的感知依赖这个文件如果你用的是 CMake 工程在 Tools → Options → CMake → Generator 里选择“CodeBlocks - Unix Makefiles”或者“Ninja”并把“导出编译数据库”选项打开否则 include 路径解析和套件识别都会异常。顺带说一个 24.04 特有的坑系统自带 Python 3.12 在某些 QtCreator 插件启动时会报 distutils 相关错误。新版本 Python 不再默认带 distutils解决办法是sudo apt install python3-setuptools装完后插件就可以正常加载。2. Ubuntu 24.04 启动异常光标闪烁黑屏与 Grub 菜单缺失2.1 开机左上角光标闪烁黑屏的排查链路这是热词里搜索量最高的系统级问题不少用户刚装完 24.04 重启就中招。屏幕上只有一个光标在闪看着像死机其实内核已经启动完成是显示服务gdm3/lightdm或者显示驱动没有正常拉起来。我用最快路径教大家排查按Ctrl Alt F2切换到 tty 登录界面。如果能登录说明内核没问题问题锁定在显示栈如果 tty 都切不过去那问题在更底层多半是内核 oops 或者磁盘挂载失败先考虑启动参数加nomodeset。在 tty 里执行journalctl -xe | grep -i gdm\|gnome\|nvidia查看 gdm3 的报错日志。最常见的错误是Gtk-WARNING: cannot open display或者Failed to start NVIDIA。执行sudo systemctl status gdm3、sudo systemctl restart gdm3。如果 gdm3 反复重启但桌面起不来尝试sudo apt reinstall gdm3 ubuntu-desktop-minimal很多时候是升级时 gdm3 部分文件损坏。如果是 NVIDIA 独显机器sudo apt purge nvidia-*后重启进桌面后再用sudo apt install nvidia-driver-550或推荐版本重新装驱动。24.04 的 6.8 内核与部分老显卡驱动兼容性不佳此时用官网 .run 驱动的成功率反而更高。还有个小概率是磁盘空间满导致 gdm3 无法写缓存用df -h检查下根分区特别是/var和/tmp。我个人的建议是排查顺序按“tty 能进吗 → journalctl 有没有 gdm 报错 → 系统里有没有 NVIDIA 驱动残留 → 重装 gdm3”来走不要一上来就动/etc/default/grub否则容易把引导搞坏。内核对 boot 参数有疑问时可以临时加nomodeset验证在 Grub 菜单选 Ubuntu 那项按e编辑启动命令在linux行末追加然后按F10启动重启后恢复。能进桌面就说明是显示驱动问题而不是系统安装失败。2.2 Grub 菜单不显示一次说清楚参数与修复“ubuntu24.04系统怎么没有显示grub2启动选项菜单”这个问题我在各种社区里看到几十次。它在 24.04 机型上的出现率尤其高因为新版系统默认把 Grub 菜单隐藏了。判断原因只需要三步编辑/etc/default/grub看到GRUB_TIMEOUT_STYLEhidden这就是菜单不显示的根本原因。改成menu并把GRUB_TIMEOUT5保存后执行sudo update-grub。双系统用户看不到 Windows 引导项还要检查同一文件里是否写了GRUB_DISABLE_OS_PROBERfalse。Ubuntu 从 22.04 开始默认关闭 os-prober必须显式设为 false再执行sudo update-grub才会出现 Windows Boot Manager。如果改完还是不显示检查 Grub 到底有没有装到 EFI 分区df -h /boot/efi看看 EFI 分区是否挂载。再ls /boot/efi/EFI看有没有ubuntu目录没有的话用sudo grub-install --targetx86_64-efi --efi-directory/boot/efi重新安装。顺手给一个快捷键小技巧重启时按住左 Shift传统 BIOS 引导或快速连续按 EscUEFI 引导可以临时唤出 Grub 菜单不用改任何配置。实测 24.04 上按住 Shift 的成功率最高。2.3 双系统安装 24.04 时防翻车的分区建议考虑到热词里“双系统安装ubuntu24.04”也是高频搜索这里直接给出我实验多次后的分区模板/boot/efi100MB - 512MB类型选 EFI System Partition。/根分区至少 50GB建议 80GB 以上。QtCreator Qt 库 缓存一套下来很吃空间。swap24.04 默认用 swapfile 即可无需划分独立 swap 分区。如果保留 Windows最好让 Ubuntu 安装器使用“Install Ubuntu alongside Windows”自动分区比自己手动折腾 GPT 分区表安全尤其是在已有 BitLocker 加密的情况下。另外注意先装 Windows 再装 Ubuntu 是最稳的顺序。反过来的话Windows Boot Manager 会把 Grub 覆盖掉最后还得 boot-repair 救回来。最后提醒一句BIOS 里 Secure Boot 能关就关至少也要允许第三方签名否则后续装 NVIDIA 驱动、vbox 模块都会卡在签名验证上。3. WSL 与虚拟机上跑 Ubuntu 24.04 的开发环境问题3.1 “安装向导提前结束由于错误”——WSL 安装失败的根源“windows linux更新子系统安装向导提前结束 由于错误”这个报错我在 Win10 和 Win11 上都遇到过。字面上看是 WSL 向导崩了其实绝大多数情况是底层功能没开全或者 WSL 内核组件没更新。逐条排查管理员权限打开 PowerShell依次执行下面两条命令开启必需功能dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart必须重启电脑不重启直接进行后面的操作几乎必然出现“安装向导提前结束”。重启后执行wsl --update更新 WSL 内核。Windows 10 老版本如果wsl --update找不到模块需要手动下载 WSL2 Linux 内核更新包。wsl --set-default-version 2强制使用 WSL2 模式。再通过 Microsoft Store 搜索 Ubuntu 24.04 安装或者直接wsl --install -d Ubuntu-24.04。如果报错WslRegisterDistribution failed with error: 0x8007019e基本就是内核没更新报0x80370102则是 BIOS 里没开虚拟化Intel VT-x 或 AMD SVM。进入 BIOS 开启后问题即解除。3.2 WSL 下运行 QtCreator 的显示与文件系统注意点WSL2 WSLg 在较新版本里已经能直接弹 GUI 窗口QtCreator 起来没有任何问题。但有几个细节值得注意窗口起不来时先检查 Windows 设置里“虚拟机平台”是否打开再检查 WSL 版本是否 2.0 以上。旧版本需要手动设DISPLAY:0通过 X Server 转发新版本直接走 Wayland。工程目录不要放在/mnt/c下。WSL 的 /mnt/c 是 9P 文件系统文件锁、inotify 监听和文件权限模型都有限制QtCreator 在这个路径下编译经常出现“Permission denied”或者“无法写入 .o 文件”这类怪问题。把项目放到 WSL 原生文件系统如~/projects速度和安全都会好很多。WSL 里有 systemd 可选配置需要在/etc/wsl.conf里写systemdtrue否则 QtCreator 的某些 DBus 相关组件比如 QDBusInterface会异常。3.3 虚拟机装 Linux 蓝屏先看 BIOS 再调虚拟机配置Windows 宿主开着 VMware 或 VirtualBox 装 Ubuntu 24.04 蓝屏原因基本两类。第一类是 BIOS 里没开虚拟化VMware 起虚拟机时直接报错VirtualBox 同样。开机进 BIOS 确认 Intel VT-x 或 AMD SVM 是 Enabled。第二类是虚拟机配置兼容性问题。VirtualBox 里给 Ubuntu 24.04 分配资源时内存至少 4GBCPU 至少 2 核显示控制器换成 VBoxSVGA显存至少 128MB——默认的 16MB 会导致 QtCreator 界面渲染卡成 PPT。虚拟机磁盘控制器用 NVMe 没问题Ubuntu 24.04 内核天然支持但如果用非常老的 VirtualBox 版本6.x 早期建议用 SATA 控制器装第一遍。VMware Workstation 方面关键设置是“加速 3D 图形”和“启用 VMware 原生 SSH 验证”前者对 GNOME Shell 动画和 Qt 界面至关重要不开的话跑 QtCreator 界面会频繁重绘闪烁。Windows 侧关掉 Hyper-V 冲突也是个要点bcdedit /set hypervisorlaunchtype off后可减少虚拟机蓝屏概率。4. 编译、依赖与 include 头文件的实战手册4.1 装完系统后要装的 Qt 编译依赖清单Ubuntu 24.04 上从零配 QtCreator 开发环境我已经把最小依赖清单固定成下面几条命令sudo apt update sudo apt install build-essential cmake ninja-build sudo apt install qt6-base-dev libgl1-mesa-dev libxkbcommon-dev如果是 Qt5 老项目再多一个sudo apt install qtbase5-dev qtchooser这里面有几个包很容易被遗漏说明一下用途包名用途不装会遇到的报错libgl1-mesa-dev提供 OpenGL 链接库/usr/bin/ld: cannot find -lGLlibxkbcommon-devQt 合成器需要的 xkbcommon 库Project ERROR: xkbcommon development package not foundninja-buildQt6/CMake 默认构建后端CMake 配置阶段报找不到 NinjaqtchooserQt5/Qt6 版本的快速切换同时装两版时 qmake 指向混乱关于“linux镜像安装”顺便说一句下载 Ubuntu 24.04 官方镜像时直接从官网走可能很慢国内建议用清华 TUNA、中科大或者网易镜像站拉 ISOMD5 和 SHA256 校验一下再刷写U 盘写入用 Rufus 或 balenaEtcher 均可但注意Rufus 写完后默认 UEFI 模式老机器 BIOS 模式下启动不了。4.2 include 头文件路径QtCreator 与 VSCode 的配置法热词里那条“ubuntu24.04 vscode添加文件夹如何一键把include头文件也添加进来”本质是 IntelliSense 和代码补全找不到 Qt 头文件目录跟编译没关系但影响日常写代码的体验。VSCode 的解决方法是改.vscode/c_cpp_properties.json{ configurations: [ { name: Linux, includePath: [ ${workspaceFolder}/**, /usr/include/x86_64-linux-gnu/qt6, /usr/include/qt6 ], defines: [], compilerPath: /usr/bin/g } ] }Qt 6 的头文件实际分布在/usr/include/x86_64-linux-gnu/qt6QtCore 等模板层和/usr/include/qt6部分模块头文件两个目录建议都加上。CtrlShiftP 执行 C/C: Reset IntelliSense Database 后生效。QtCreator 这边就简单了如果是 CMake 工程target_include_directories(MyApp PRIVATE /usr/include/x86_64-linux-gnu/qt6)如果是 qmake 的 .pro 文件直接写INCLUDEPATH $$[QT_INSTALL_HEADERS]。最省事的做法是让 QtCreator 从编译数据库里自动读——把 CMake 的 CMAKE_EXPORT_COMPILE_COMMANDS 选项设为 ONQtCreator 打开编译数据库后会自己解析所有 include 路径这才是真正意义上的“一键”。4.3 老项目从 20.04/22.04 迁移到 24.04 的链接报错升级系统后老工程编译失败很大概率是 GCC 版本变了。Ubuntu 24.04 默认 GCC 13比 22.04 的 GCC 11 严格不少C17 成为默认标准也更积极。常见报错和对应处理undefined reference to vtable for ...多数是因为基类有未实现虚函数或者链接时漏了对应源文件。GCC13 对虚函数表识别更敏感查一下是不是把某个类只声明没定义或者忘记在 .pro 里加入对应 .cpp。conversion from const char* to char*直接报错老代码里常见的字符串字面量转 char*GCC13 默认禁止这种隐式转换。不要急着全局加-fpermissive先改代码用const_cast或改为const char*。全局加 -fpermissive 只是掩盖问题在 Qt 信号槽连接时反而会埋下更多运行时错误。Qt4 项目24.04 源里已经没有 Qt4 的包了老项目要么用qmake -v确认版本要么就必须迁移到 Qt5/Qt6。迁移 Qt4→Qt5 的核心动作是改头文件#include QtGui → QtWidgets并把 .pro 里QT gui改为QT gui widgets。Qt5→Qt6 更麻烦一些涉及QRegExp到QRegularExpression的替换以及qmlRegisterType的签名变化。Python 3.12 相关部分 Qt 生成器脚本依赖旧的distutils报错后在 Python 里import distutils如果失败执行sudo apt install python3-setuptools新版本 setuptools 会补上该模块。5. 开发环境外围设备问题集NAS 挂载、打印机、嵌入式驱动与常用运维5.1 Linux 挂载 NAS 存储fstab 与自动挂载的坑“linux挂载nas存储csdn”这个关键词经常出现在 Qt 开发者搜索记录里因为不少团队把工程中间件或 Qt 库放在 NAS 上开发机需要联机读代码、放构建产物。挂载方式推荐 cifsSMB/CIFS 协议因为兼容 Windows 和群晖/QNAP 设备。先装工具sudo apt install cifs-utils nfs-common临时挂载sudo mkdir -p /mnt/nas sudo mount -t cifs //192.168.1.10/共享目录 /mnt/nas -o username你的用户,password你的密码,vers3.0,uid1000,gid1000,iocharsetutf8永久挂载要写入/etc/fstab这一行建议这样写//192.168.1.10/共享目录 /mnt/nas cifs username你的用户,password你的密码,iocharsetutf8,vers3.0,_netdev,uid1000,gid1000 0 0关键是_netdev选项——防止开机时网络还没就绪就尝试挂载导致系统卡在启动流程这个坑我踩过不加的话开机中途会卡很久然后报“dependency failed”。遇到挂载成功但目录不可写的情况优先检查uid/gid因为 SMB 共享默认用 root 权限挂载普通用户写不了。遇到中文文件名乱码检查iocharsetutf8有没有写对。如果 NAS 是较老的 SMB1 设备需要把vers降为 2.0 或 1.0但 2024 年建议直接换 SMB3 设备旧协议安全性堪忧。5.2 HP LaserJet P1106 在 Ubuntu 24.04 上的驱动安装“hp laserjet p1106 linux”这个热词说明有大量开发机用户在用这台老打印机。P1106 是惠普家经典型号在 Linux 上其实比 Windows 更好配因为系统自带的 hplip 驱动已经覆盖它。安装命令sudo apt install hplip hp-setup -ihp-setup会自动探测 USB 设备并下载对应 PPD。如果探测不到检查打印机是否被usblp内核模块占用可以临时卸载模块再试sudo modprobe -r usblp sudo hp-setup -i日常打印失败时先别重装驱动systemctl status cups看下 CUPS 服务然后浏览器打开http://localhost:631查看打印任务队列的错误信息。P1106 常见的“任务已发送但不出纸”多数是驱动里的页面尺寸设置问题在打印对话框里手工改成 A4 即可。5.3 嵌入式 Linux 的 DSA Switch 驱动调试思路一次讲清热词里“linux dsa switch驱动”偏嵌入式场景很多做开发板项目的朋友找资料找到这里。DSADistributed Switch Architecture是 Linux 内核处理多口交换机的框架像 Marvell 88E6xxx、Microchip KSZ 系列都走这个框架。如果你在 Ubuntu 24.04 或嵌入式 Linux 环境里调 DSA 交换机核心要点有三个设备树里 DSA 节点必须定义好 CPU 端口和用户端口。CPU 端口要和 SoC 的 MAC 绑定用户端口则是面向 LAN 的接口名字通常是lan1、lan2。端口序号乱掉多半是 compatible 没配对检查compatible marvell,mv88e6xxx或microchip,ksz8795是否与驱动匹配。常用调试命令watch -n 1 ethtool -S lan0 # 观察收发统计 ip link set dev lan1 up # 手动拉起用户端口 ethtool eth0 # 查看协商速率和双工模式如果内核实模式构建需要确保 kernel config 里CONFIG_NET_DSA和对应 switch 芯片驱动选上否则设备树节点会被静默跳过ip link里根本看不到 lan 端口。嵌入式项目还有一个常见联合场景开发板作为网关需要把 eth0 的网共享给局域网设备这就是热词里“linux 共享上网 办法”对应的场景用 Linux 自带的 NAT 就能解echo 1 /proc/sys/net/ipv4/ip_forward iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE配置好 DHCP 分配后局域网设备就能通过开发板上网了这个思路在 Qt 开发板远程调试时很常用。5.4 开发机上高频使用的几条命令和脚本习惯最后整理几条我在 Ubuntu 24.04 上经常用的命令顺手帮大家查缺补漏journalctl -xe最常用的排查命令。QtCreator 启动失败、gdm3 崩溃、USB 设备识别异常第一条命令基本都是它。ss -tlnp替代老旧的netstat看端口监听。Qt 程序调试时经常需要确认某个端口是否被占用。ps auxf | grep 进程名查看进程树。热词里“linux 修改进程名称”在 bash 里可以用exec -a newname ./你的程序临时修改 argv[0]在 C/C 里则是prctl(PR_SET_NAME, newname)。adduser 新用户名和usermod -aG sudo 新用户名开发机新建管理员账号的标准动作不要用passwd直接改复杂密码容易搞乱 SSH 登录。定期备份 QtCreator 配置cp -r ~/.config/QtProject ~/QtBackup重装系统后恢复这个目录能找回所有套件、构建和外观设置。另外Ubuntu 24.04 上装搜狗输入法时我遇到过一次 Qt 程序里输入法候选框不跟随光标的问题。解决方向是确认安装了fcitx5-frontend-qt5和fcitx5-frontend-qt6如果用的是 fcitx5然后注销重登。搜狗官方虽然提供 deb 包但依赖 fcitx 框架是跑不掉的别漏装前置。最后分享一个我个人的操作习惯系统装完的第一件事永远是做一次 Timeshift 快照第二件事才是装 QtCreator。我这两年最狼狈的几次修复都是因为手贱执行了apt autoremove把某个间接依赖删掉导致 QtCreator 的编译器检测直接罢工。遇到问题先看日志、先想到“快照还原”而不是立刻重装系统这个思路能帮你省下大量时间。