刚开始拿到这台预装银河麒麟 v10 的开发机时我心里是有点轻松的——不就是个 Linux 嘛装个 Qt、装个 VSCode 还不简单。结果事实证明这套系统跟常见的 Ubuntu 发行版在细节层面的差距足以让人从中午折腾到天黑。软件源里没有现成的 Qt 开发包VSCode 的 C/C 插件在默认配置下找不到 Qt 头文件在线安装器好不容易把 Qt 5.15.2 装完新建一个串口工程的瞬间直接报Project ERROR: Unknown module(s) in QT: serialport。这篇文章就是我在这台银河麒麟系统上把 VSCode 和 Qt 开发环境从零配到能正常编译、调试、跑通串口应用的完整过程。里面包含我在实际环境中踩过的坑、每一步的排查思路、最终的配置模板以及几个能让后续开发省心不少的小习惯。给同样需要在银河麒麟上做 Qt 开发的同事一份可以直接照着抄的作业少走一点弯路。1. 动手前先花十分钟确认三件事版本分支、架构、软件源很多人拿到机器第一件事就是下载安装包我建议先确认系统的三件事。磨刀不误砍柴工尤其是银河麒麟这种分支比较特殊的系统。1.1 系统版本分支决定了包管理器银河麒麟 v10 有桌面版和服务器版桌面版底层偏向 Debian/Ubuntu 体系服务器版有的发行版底子则偏向 CentOS/RHEL 体系。这意味着你的安装命令可能是apt也可能是yum或dnf搞混了第一步就卡住。打开终端依次执行cat /etc/os-release uname -m cat /etc/kylin-release 2/dev/null重点看/etc/os-release里的ID和ID_LIKE。如果看到debian或ubuntu后面都用 apt如果看到centos或rhel就用 yum/dnf。uname -m输出x86_64说明是 64 位Qt 和 VSCode 选对应版本即可如果是aarch64就得找 ARM 版本的安装包这一步特别容易忽略。1.2 软件源和基础工具链确认完分支后先把软件源更新一下然后安装编译 Qt 工程必需的基础工具链# Debian 系 sudo apt update sudo apt install -y build-essential cmake ninja-build gdb git ccache # CentOS 系 sudo yum install -y gcc-c make cmake ninja-build gdb git ccache这里有个经验如果apt update速度很慢或者报错先检查源配置文件。银河麒麟 v10 默认可能配置的是发行方维护的源个别网络环境下访问不稳定。可以备份原有配置文件后换成国内公共镜像源注意系统架构要选对amd64还是arm64不要混用。sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak改完源之后再次apt update基础环境就通了。1.3 记住这几条命令后面排查全靠它们在配置过程中会频繁用到下面这些命令我把它们整理成一张对照表方便顺手查用途命令查看 Qt 安装路径qmake -query QT_INSTALL_PREFIX查看编译器路径which gcc g gdb cmake查看安装过的软件包dpkg -l | grep qt5Debian 系查看服务状态systemctl status sshd查看磁盘剩余空间df -h /home /opt查看动态库依赖ldd ./build/MyApp这些命令看起来基础但真正排查 Qt 模块缺失、VSCode 连接不上远端、程序启动缺库这类问题的时候每一步都会用到。2. Qt 装哪个版本、从哪下载、怎么装最省事2.1 为什么我选了 Qt 5.15.2 而不是 6.x在银河麒麟这种相对保守的系统上做 Qt 开发我推荐 Qt 5.15.2 而不是 6.x原因有三个第一兼容性。很多工控、军工、电力行业的存量项目都是基于 Qt 5.12 或 5.15 写的直接用 5.15.2 可以减少代码迁移成本。第二离线安装。5.15.2 可以下载到完整的离线 run 安装包在隔离网络环境下也能装。Qt 6 的安装策略更偏向在线安装器在没有外网或网络受限的开发环境里非常被动。第三串口、CAN、Modbus 等模块在 5.15.2 里都是现成的工控类应用尤其依赖这些正好契合麒麟系统的实际使用场景。2.2 在线安装器与离线安装包的选择如果你所在的网络环境能正常访问 Qt 官方源可以用在线安装器但我实际体验下来在银河麒麟上用在线安装器容易在两个地方卡住一是 Qt 账户登录环节偶尔加载不出页面二是组件下载过程中的网络波动会导致重试成本很高。更稳妥的方式是直接找 Qt 5.15.2 的离线 run 包。我在实际部署时主要依赖国内高校镜像源和 Qt 官方镜像目录搜索qt-opensource-linux-x64-5.15.2.run或qt-opensource-linux-x64-5.15.2-xxx.run即可找到。下载之后先检查文件完整性md5sum 对一下官方给出的校验值避免下载损坏。chmod x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run2.3 安装目录和组件的“一锤定音”决策安装运行包时有三个选择会直接影响后面的 VSCode 配置和 CMake 编译我建议一次选对安装目录固定为/opt/Qt5.15.2不要装到带中文、空格的自定义路径下否则后续 gdb 调试和 CMake 解析路径都可能出问题。组件树里务必确认勾选Qt 5.15.2 → GCC 64-bit以及Qt Serial Port、Qt CAN Bus这类工控模块。安装器界面默认会展开组件列表很多人在这一步为了省空间把组件都取消了后面才会报serialport找不到。安装完成后先做一个验证确认核心库和串口库都在ls /opt/Qt5.15.2/5.15.2/gcc_64/lib/ | grep Qt5SerialPort如果输出为空说明组件没装上后续编译一定会报模块缺失。此时需要重新打开/opt/Qt5.15.2/MaintenanceTool在组件管理里勾选缺失模块并更新。2.4 装完之后必须做的环境变量配置很多人装完 Qt 后直接打开 Qt Creator 能编译但切到 VSCode CMake 就找不到 Qt原因就是环境变量没配。把下面这段写入/etc/profile.d/qt.shexport QTDIR/opt/Qt5.15.2/5.15.2/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export PKG_CONFIG_PATH$QTDIR/lib/pkgconfig:$PKG_CONFIG_PATH export CMAKE_PREFIX_PATH$QTDIR然后执行source /etc/profile.d/qt.sh再用qmake -v验证。如果输出Using Qt version 5.15.2 in /opt/Qt5.15.2/5.15.2/gcc_64说明 Qt 部分完成了。3. VSCode 安装与 C/C 插件配置里的三个隐藏点3.1 VSCode 安装的三种方式和依赖问题在银河麒麟系统上安装 VSCode常见有三种方式apt 直接安装。如果软件源里有code包最简单但版本可能比较旧。官网下载 deb 包安装。下载code_xxx_amd64.deb后执行sudo dpkg -i code_xxx_amd64.deb sudo apt -f install -ydpkg -i经常会因为缺依赖报错后面跟上apt -f install基本都能修复。手动解压 tar.gz 包。这种方式适合无桌面环境的服务器但不推荐因为没有 .desktop 文件图形界面打开不方便。我实际测试下来第二种方式是兼容性最好的。VSCode 在麒麟桌面环境下本质是一个 Electron 应用deb 包封装完整装完即用。3.2 扩展插件里最容易被忽略的编译器路径装完 VSCode第一件事不是写代码而是装插件C/C、CMake Tools、Remote - SSH、GitLens一个都不能少。C/C 插件默认会尝试自动探测编译器但如果你在终端里能正常编译、VSCode 里却提示找不到头文件问题基本出在c_cpp_properties.json的编译器路径和 includePath 配置上。按CtrlShiftP打开命令面板输入C/C: Edit Configurations (JSON)写入{ configurations: [ { name: Qt5.15.2-Kylin, includePath: [ ${workspaceFolder}/**, /opt/Qt5.15.2/5.15.2/gcc_64/include/**, /opt/Qt5.15.2/5.15.2/gcc_64/include/QtWidgets/**, /opt/Qt5.15.2/5.15.2/gcc_64/include/QtSerialPort/** ], defines: [], compilerPath: /usr/bin/g, cStandard: c17, cppStandard: c17, intelliSenseMode: linux-gcc-x64 } ], version: 4 }如果安装了CMake Tools插件并开启了compileCommands生成C/C 插件也能通过compile_commands.json自动获取头文件路径这样就不用手动维护一大串 includePath。在.vscode/settings.json里加一行{ cmake.configureSettings: { CMAKE_PREFIX_PATH: /opt/Qt5.15.2/5.15.2/gcc_64 } }3.3 Remote-SSH 模式Windows 笔记本 麒麟开发机的经典组合实际项目里很常见的一种场景是本地开发环境是 Windows 笔记本银河麒麟是远程服务器或者专用开发机。这种情况下没必要把 VSCode 整个装到麒麟系统上直接用 VSCode 的 Remote-SSH 扩展 远程连接过去开发本地只负责编辑和调试控制台编译运行都在远端进行。这个模式唯一的坑在于远端的openssh-server版本。银河麒麟 v10 自带的 OpenSSH 版本有时候偏旧VSCode Remote-SSH 连接时可能会报版本不兼容或者算法不支持。建议连上去之后先看一眼ssh -V如果版本太旧尝试用系统包管理器更新sudo apt update sudo apt install -y openssh-server升级之前记得备份/etc/ssh/sshd_config避免原有配置丢失。修改完配置后重启 sshdsudo systemctl restart sshd另外补充一个 VSCode 远程开发的普遍问题首次连接远端时远端会自动下载vscode-server如果下载失败Remote-SSH 会一直卡在“设置 SSH 主机”的界面。解决办法是打开 Remote-SSH 插件的输出日志找到commit id然后在本地手动下载对应版本的vscode-server-linux-x64.tar.gz用 scp 拷贝到远端的~/.vscode-server/bin/commit id/目录下解压。这个操作我做过好几次比反复重试省时间得多。4. 用 CMake tasks.json launch.json 打通编译调试全链路很多人在 Qt Creator 里开发用顺手了切到 VSCode 后最大的痛点是不会配置 F5 一键编译调试。其实套路很简单CMake 负责构建tasks.json 负责把构建命令暴露给 VSCodelaunch.json 负责把 gdb 接到构建产物上。4.1 为什么在 VSCode 生态里推荐 CMake 而不是 qmakeQt 官方对 qmake 的维护已经明显放缓CMake 目前是 Qt 项目的主流构建方式尤其在 VSCode 这种编辑器模式下CMake 的好处很直接compile_commands.json生成机制可以反向给 C/C 插件提供头文件路径代码补全和跳转准确率提升明显。跨平台一致性好同样的 CMakeLists 在 Windows、Ubuntu、银河麒麟上都能跑。与 CMake Tools 插件结合可以直接在 VSCode 底栏切换构建套件、编译目标比手动敲命令直观。一个最小可用的 Qt5 SerialPort 的 CMakeLists.txt 长这样cmake_minimum_required(VERSION 3.16) project(MyApp VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) set(CMAKE_AUTOUIC ON) find_package(Qt5 COMPONENTS Core Gui Widgets SerialPort REQUIRED) add_executable(MyApp main.cpp mainwindow.cpp mainwindow.h mainwindow.ui ) target_link_libraries(MyApp PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets Qt5::SerialPort )注意CMAKE_AUTOMOC、AUTORCC、AUTOUIC三个开关一定都要打开。Qt 的元对象编译器moc处理信号槽、Q_OBJECT 宏uic 处理.ui文件少了任何一个开关编译就会报一堆莫名其妙的未定义符号。4.2 tasks.json 怎么触发 cmake 与 ninja 编译在工程根目录创建.vscode/tasks.json内容如下{ version: 2.0.0, tasks: [ { label: CMake Configure, type: shell, command: cmake -S . -B build -DCMAKE_BUILD_TYPEDebug -DCMAKE_PREFIX_PATH/opt/Qt5.15.2/5.15.2/gcc_64, group: build, problemMatcher: [] }, { label: CMake Build, type: shell, command: cmake --build build -j$(nproc), group: { kind: build, isDefault: true }, problemMatcher: [$gcc] }, { label: Clean Build, type: shell, command: rm -rf build cmake -S . -B build -DCMAKE_BUILD_TYPEDebug -DCMAKE_PREFIX_PATH/opt/Qt5.15.2/5.15.2/gcc_64 cmake --build build -j$(nproc), group: build, problemMatcher: [$gcc] } ] }-j$(nproc)会自动使用机器全部逻辑核心在银河麒麟服务器上编译大项目时这个参数很关键省下的时间非常可观。problemMatcher: [$gcc]是让 VSCode 把编译错误直接标记到“问题”面板双击就能跳到出错的行排错体验和 Qt Creator 有一拼。首次使用时按CtrlShiftP运行Tasks: Run Build Task先执行 CMake Configure再执行 CMake Build。以后每次改完代码按CtrlShiftB就可以直接编译。4.3 launch.json 的 gdb 调试模板创建.vscode/launch.json{ version: 0.2.0, configurations: [ { name: Debug MyApp, type: cppdbg, request: launch, program: ${workspaceFolder}/build/MyApp, args: [], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [], externalConsole: false, MIMode: gdb, setupCommands: [ { description: Enable pretty-printing for gdb, text: -enable-pretty-printing, ignoreFailures: true } ], preLaunchTask: CMake Build, miDebuggerPath: /usr/bin/gdb } ] }关键点是preLaunchTask: CMake Build。按 F5 时 VSCode 会先编译再启动调试刚好和 Qt Creator 的调试按钮行为对齐。externalConsole设为 false程序窗口直接在 VSCode 内部终端显示如果你的 Qt 程序是带界面的建议调试时保持 false这样可以通过 VSCode 的“调试控制台”看到 qDebug 输出。5. 高频报错现场实录串口模块、头文件路径、中文与 SSH这部分是我自己在这台“银河麒麟 Qt VSCode”组合上遇到过的真实问题每个都花了不少时间才搞清楚根因。5.1 serialport 模块缺失的完整排查链路报错信息长这样Project ERROR: Unknown module(s) in QT: serialport这个错误很多人一看到就懵。其实排查链路很固定第一步确认 qmake 到底来自哪个 Qtwhich qmake qmake -query QT_INSTALL_LIBS如果结果显示/usr/lib/x86_64-linux-gnu说明用的是系统 apt 安装的 Qt那就直接装串口模块sudo apt install -y libqt5serialport5-dev如果结果显示/opt/Qt5.15.2/5.15.2/gcc_64/lib说明用的是离线包安装的 Qt继续第二步。第二步检查该 Qt 是否真正包含 SerialPort 模块ls /opt/Qt5.15.2/5.15.2/gcc_64/lib/cmake/ | grep SerialPort如果没有输出说明安装时根本没有勾选 SerialPort 组件。打开 MaintenanceTool 勾选即可如果是离线包环境我建议干脆重新运行完整的离线 run 安装器把所有 Qt Serial Port、Qt CAN Bus 组件都选上装到同一目录避免组件残缺。第三步如果目录存在但仍然报模块未知检查环境变量QMAKEMODULES是否被设置成奇奇怪怪的路径这个变量会干扰 qmake 搜索模块。正常情况不需要手动设置它unset 掉再编译试试unset QMAKEMODULES在 CMake 工程中对应的报错是Could not find a package configuration file provided by Qt5SerialPort这种场景 90% 是CMAKE_PREFIX_PATH没指到 Qt 的gcc_64目录检查.vscode/settings.json或tasks.json里的CMAKE_PREFIX_PATH是否准确。5.2 编译头文件路径混乱系统 Qt 和自装 Qt 冲突银河麒麟自带的系统源里可能已经有 Qt5 相关包如果你之前用 apt 装过qtbase5-dev后来又装了/opt/Qt5.15.2两者会发生头文件和库文件的抢占。表现很明显CMake 配置时明明显示找到了 Qt 5.15.2但编译时#include QtWidgets/QMainWindow报找不到头文件或者链接时报一堆undefined reference。排查方法也很直接先确认 CMake 找到的 Qt 路径grep -i qt5_dir build/CMakeCache.txt如果 Qt5_DIR 指向/usr/lib/x86_64-linux-gnu/cmake/Qt5说明 CMake 找到的是系统 Qt而不是/opt/Qt5.15.2。解决办法就是把 tasks.json 里的CMAKE_PREFIX_PATH显式指过去并在 configure 之前删掉 build 目录重新配置。这个坑的隐蔽之处在于如果你不清空 buildCMake 缓存会一直沿用旧路径怎么改配置都不生效。5.3 中文显示、输入法、字体和 SSH 旧版本Qt 程序在银河麒麟上跑起来后第一眼看到的就是界面中文。如果出现方块字通常是缺少中文字体sudo apt install -y fonts-noto-cjk fonts-wqy-microhei输入法也是高频问题。用 fcitx5 作为 Qt 应用的输入法框架时需要设置环境变量export QT_IM_MODULEfcitx export GTK_IM_MODULEfcitx export XMODIFIERSimfcitx如果漏了QT_IM_MODULEfcitx在 Qt 应用里切换中文输入法时会发现拼音候选框一直不出现非常影响调试效率。SSH 旧版本的问题在上面 Remote-SSH 一节已经提过这里补充一点如果升级 openssh-server 后 VSCode 仍然提示连接被拒绝先检查 sshd 是否有监听端口sudo ss -tlnp | grep 22如果 22 端口没有监听很可能是 sshd 启动失败看journalctl -u sshd日志定位。注意修改 sshd_config 之前先备份这是我在踩过远程连接断掉、无法恢复的坑之后养成的习惯。6. 让环境更顺手的小事环境变量固化、ccache 加速、目录命名习惯配置完基本环境只是开始。真正让这套环境每天都好用的往往是几个不起眼的小习惯。6.1 把环境变量固化到 profile 文件Qt 的环境变量如果只写在当前终端里每次重启终端都要重复 export。建议统一写到/etc/profile.d/qt.sh这样所有用户登录时都会自动加载。我见过不少同事把环境变量写进/etc/profile也能用但/etc/profile.d/更规范升级或排查时不容易污染主配置文件。6.2 ccache 加速 Qt 项目重编译Qt 项目编译慢尤其是改个头文件导致整个工程重编时等待过程非常煎熬。ccache 是救命工具。安装之后在 CMakeLists 里加一行。find_program(CCACHE_PROGRAM ccache) if(CCACHE_PROGRAM) set(CMAKE_CXX_COMPILER_LAUNCHER ${CCACHE_PROGRAM}) endif()第一次编译时没有明显效果第二次开始没有改动的源文件会直接命中缓存整个重编时间经常能缩短一半以上。ccache 默认缓存路径在~/.ccache如果磁盘空间不够可以设置ccache -M 10G控制最大缓存容量。6.3 我坚持的目录命名习惯最后分享一个我自己的习惯工程路径、用户名、文件名一律用英文不要用中文和空格。银河麒麟底层的 Linux 生态对非 ASCII 路径的支持虽然比过去好了很多但在 CMake 处理 Qt 插件路径、gdb 解析符号、VSCode Remote-SSH 同步文件时中文字符偶尔会引发一些非常难查的问题。我碰到过一次因为路径带中文导致 VSCode 远程调试无法命中断点最后把工程挪到/home/dev/qt-projects/MyApp下问题立刻消失。如果项目已经建在中文路径下尽早迁移别等项目大了再动手。另一个习惯是工程里保留.vscode目录并纳入 git 仓库tasks.json、launch.json、c_cpp_properties.json 都是团队共享的配置文件。新同事克隆代码后不用再自己摸索半天直接 F5 就能跑起来。这对“银河麒麟 Qt VSCode”这种有几个明显配置坑的组合来说节省的时间和沟通成本非常可观。