1. 为什么要在银河麒麟上折腾这套开发环境银河麒麟V10这个系统这两年我在好几个项目里都部署过。最早接触是因为客户要求全国产化环境服务器和开发机全部换成银河麒麟。刚开始确实踩了不少坑尤其是开发环境的搭建跟Ubuntu、CentOS那套习惯完全不一样。后来慢慢摸清楚了发现其实银河麒麟底层就是基于Linux内核的包管理用的是aptV10 SP1之后或者yum早期版本只要把源配置对了大部分软件都能跑起来。这篇文章主要面向三类人第一类是被公司要求迁移到国产系统做开发的工程师第二类是学生或者个人开发者想提前熟悉国产化开发环境第三类是做信创项目的实施人员需要快速搭建标准开发环境。核心目标就是一件事在银河麒麟V10上把VSCode和Qt这套组合拳配置到能干活的状态。为什么选VSCode加Qt这个组合VSCode轻量、插件生态好、启动快写C和Python都顺手Qt则是做桌面应用和嵌入式界面开发的老牌框架尤其在国产化项目里很多界面层都是用Qt做的。两者配合VSCode负责写代码和调试Qt负责界面设计和构建这套流程在银河麒麟上跑通之后开发效率跟Windows上差别不大。但问题在于银河麒麟的软件源里VSCode和Qt的版本往往比较旧有些甚至没有。而且银河麒麟的桌面环境是UKUI基于Qt开发的系统里本身就带了一些Qt库版本冲突是常有的事。所以这篇文章不会只告诉你“点下一步”而是会把版本选择、依赖处理、环境变量配置这些关键环节讲透。2. 银河麒麟V10系统准备与基础配置2.1 确认系统版本和架构动手之前先确认你手上的银河麒麟到底是什么版本。打开终端执行cat /etc/kylin-release uname -m你会看到类似Kylin Linux Advanced Server release V10 (Sword)的输出uname -m一般是aarch64或者x86_64。这个信息很重要因为后面下载Qt安装包和VSCode的deb包时必须选对架构。我见过有人把x86_64的包往飞腾机器上装折腾半天报一堆错其实就是架构不对。银河麒麟V10 SP1、SP2、SP3这几个版本差异不小。SP1的软件源里Qt版本是5.12SP2之后有些源里能到5.15。如果你要做Qt 5.15.2的开发建议直接去Qt官网下载离线安装包不要依赖系统源。2.2 配置软件源和更新系统银河麒麟默认的软件源速度一般建议先换成国内镜像源。编辑源列表sudo vim /etc/apt/sources.list如果你用的是V10 SP1之后版本源文件格式跟Ubuntu类似。换成阿里云或者清华的镜像源之后执行sudo apt update sudo apt upgrade -y这一步别省。我遇到过系统自带的glibc版本太低导致Qt安装包解压后运行报错的情况。升级完系统很多依赖问题会自动解决。注意升级内核之前如果机器上有特殊外设驱动比如某些加密卡、打印机驱动先确认驱动兼容性再升级否则可能出现设备无法识别的情况。2.3 安装基础开发工具链不管后面装什么编译工具链先装好sudo apt install -y build-essential cmake git wget curl sudo apt install -y libgl1-mesa-dev libglu1-mesa-dev sudo apt install -y libxkbcommon-x11-dev libxcb-xinerama0-dev这几个包看着不起眼但Qt的图形界面依赖它们。尤其是libxkbcommon-x11-dev缺了它Qt Creator启动时会报“could not load the Qt platform plugin xcb”的错误。这个错误我见过太多次了新手往往以为是Qt装坏了其实就是少了个依赖库。另外银河麒麟默认可能没有安装openssh-server如果你需要远程开发记得sudo apt install -y openssh-server sudo systemctl enable ssh sudo systemctl start ssh3. VSCode在银河麒麟上的安装与汉化配置3.1 下载正确的VSCode安装包VSCode官网提供了.deb和.rpm两种包。银河麒麟V10 SP1之后基于Debian体系用.deb包。去官网下载时注意选x64还是arm64跟你的机器架构匹配。下载完之后不要急着双击安装。先检查依赖sudo dpkg -i code_*.deb如果报依赖错误执行sudo apt install -f这个命令会自动修复缺失的依赖。我实测下来银河麒麟V10 SP2上装VSCode最常见的缺失依赖是libsecret-1-0和libxkbfile1apt install -f基本都能搞定。3.2 解决VSCode启动黑屏或闪退有些机器上装完VSCode启动时黑屏或者直接闪退。这通常是显卡驱动或者沙箱模式的问题。可以尝试用以下命令启动code --disable-gpu --no-sandbox如果这样能启动说明是GPU加速的问题。可以修改VSCode的启动配置在/usr/share/applications/code.desktop里把Exec那一行改成Exec/usr/share/code/code --disable-gpu --no-sandbox %F提示--no-sandbox会降低安全性仅在开发环境使用。生产环境建议排查具体的沙箱冲突原因。3.3 汉化与常用插件配置VSCode装好之后第一件事是装中文语言包。打开扩展面板搜索Chinese (Simplified)安装后重启即可。如果在线安装插件很慢可以手动下载.vsix文件离线安装code --install-extension ms-ceintl.vscode-language-pack-zh-hans-*.vsixC/C开发必装的插件C/C微软官方、CMake Tools、Qt Configure。Python开发装Python和Pylance。Qt开发建议再装一个Qt tools虽然功能不算强但能提供.ui文件的语法高亮。配置C/C环境时c_cpp_properties.json里的includePath要加上Qt的头文件路径。比如{ configurations: [ { name: Linux, includePath: [ ${workspaceFolder}/**, /opt/Qt/5.15.2/gcc_64/include/** ], compilerPath: /usr/bin/g, cppStandard: c17 } ], version: 4 }这个路径根据你Qt实际安装位置调整。我习惯把Qt装在/opt/Qt下面方便管理。4. Qt 5.15.2离线安装与版本管理4.1 为什么选Qt 5.15.2Qt 5.15.2是Qt 5系列的最后一个长期支持版本之后Qt 6的API变化较大很多国产化项目里的老代码迁移成本高。而且银河麒麟系统自带的Qt库版本参差不齐直接依赖系统Qt容易出问题。自己装一个独立的Qt 5.15.2跟系统Qt隔离是最稳妥的做法。去Qt官网下载离线安装包时注意选qt-opensource-linux-x64-5.15.2.run这个文件。下载完之后先赋予执行权限chmod x qt-opensource-linux-x64-5.15.2.run然后运行安装程序。安装过程中会让你登录Qt账号如果没有账号可以跳过不影响安装。组件选择时至少勾选Desktop gcc 64-bit如果需要Android开发再勾选Android相关组件。4.2 安装过程中的依赖问题处理Qt安装程序本身是个Qt写的图形界面在银河麒麟上运行时可能会报缺少libxcb-xinerama0之类的错误。提前装好sudo apt install -y libxcb-xinerama0 libxcb-icccm4 libxcb-image0 sudo apt install -y libxcb-keysyms1 libxcb-render-util0 libxcb-shape0如果安装程序界面显示乱码是字体问题装一下中文字体sudo apt install -y fonts-wqy-microhei fonts-wqy-zenhei安装路径建议选/opt/Qt不要装在用户目录下。因为后面配置环境变量和团队协作时统一路径能省很多事。4.3 配置Qt环境变量安装完成后需要把Qt的bin目录加到PATH里。编辑~/.bashrcexport QTDIR/opt/Qt/5.15.2/gcc_64 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins执行source ~/.bashrc生效。验证一下qmake -v应该输出QMake version 3.1和Using Qt version 5.15.2。如果输出的还是系统自带的Qt版本检查PATH顺序确保/opt/Qt/5.15.2/gcc_64/bin在系统路径之前。注意LD_LIBRARY_PATH这个变量要谨慎设置。如果系统里其他程序依赖系统Qt库改了LD_LIBRARY_PATH可能导致它们启动失败。更优雅的方式是在Qt Creator里单独配置Kit而不是全局改环境变量。4.4 Qt Creator的配置与Kit设置打开Qt Creator进入工具-选项-Kits。在Qt Versions标签页里添加/opt/Qt/5.15.2/gcc_64/bin/qmake。然后到Kits标签页新建一个KitCompiler选GCC (x86_64-linux-gnu)Qt version选刚才添加的5.15.2。这里有个坑银河麒麟系统里可能同时存在多个gcc版本。用gcc --version确认一下如果系统默认gcc版本太低比如gcc 7编译Qt 5.15.2的项目可能会报C17特性不支持。建议装gcc 9以上sudo apt install -y gcc-9 g-9 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 90 sudo update-alternatives --install /usr/bin/g g /usr/bin/g-9 90然后在Qt Creator的Kit里把Compiler手动指向/usr/bin/gcc-9和/usr/bin/g-9。5. 联调VSCode与Qt的完整工作流5.1 用CMake组织Qt项目现在Qt项目推荐用CMake而不是qmake。在VSCode里建一个CMakeLists.txtcmake_minimum_required(VERSION 3.16) project(MyQtApp LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) set(CMAKE_AUTOUIC ON) find_package(Qt5 COMPONENTS Widgets REQUIRED) add_executable(MyQtApp main.cpp mainwindow.cpp mainwindow.h mainwindow.ui ) target_link_libraries(MyQtApp Qt5::Widgets)在VSCode的settings.json里配置CMake路径{ cmake.cmakePath: /usr/bin/cmake, cmake.configureArgs: [ -DCMAKE_PREFIX_PATH/opt/Qt/5.15.2/gcc_64 ] }这样VSCode的CMake Tools插件就能找到Qt的库了。按F7构建CtrlF5运行整个流程跟Windows上Visual Studio的体验差不多。5.2 调试配置VSCode调试Qt程序需要配置launch.json{ version: 0.2.0, configurations: [ { name: Qt Debug, type: cppdbg, request: launch, program: ${workspaceFolder}/build/MyQtApp, args: [], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [ { name: LD_LIBRARY_PATH, value: /opt/Qt/5.15.2/gcc_64/lib } ], externalConsole: false, MIMode: gdb, setupCommands: [ { description: Enable pretty-printing for gdb, text: -enable-pretty-printing, ignoreFailures: true } ] } ] }关键点是environment里的LD_LIBRARY_PATH不设置的话调试时程序找不到Qt的动态库会报“error while loading shared libraries”。5.3 处理Qt SerialPort模块缺失问题很多人在Qt项目里用到串口通信find_package(Qt5 COMPONENTS SerialPort REQUIRED)时会报Unknown module(s) in Qt: serialport。这是因为Qt 5.15.2的离线安装包里SerialPort模块默认没有勾选安装。解决办法是重新运行Qt安装程序在组件选择里勾选Qt Serial Port。如果不想重装也可以单独编译SerialPort模块cd /opt/Qt/5.15.2/Src/qtserialport /opt/Qt/5.15.2/gcc_64/bin/qmake make -j$(nproc) sudo make install编译完之后/opt/Qt/5.15.2/gcc_64/lib下会出现libQt5SerialPort.soCMake就能找到了。6. 常见问题排查与避坑经验6.1 问题速查表问题现象可能原因解决方法VSCode启动黑屏GPU加速冲突加--disable-gpu参数启动Qt Creator报xcb插件错误缺少xcb依赖库安装libxcb-xinerama0等包qmake版本不对PATH顺序问题调整~/.bashrc中PATH顺序编译报C17不支持gcc版本过低升级到gcc 9以上调试时找不到Qt库LD_LIBRARY_PATH未设置在launch.json中配置环境变量SerialPort模块缺失安装时未勾选重新安装或单独编译模块中文显示乱码缺少中文字体安装fonts-wqy-microhei6.2 几个我踩过的坑第一个坑是银河麒麟的chmod 777问题。有些教程让你把整个项目目录chmod 777这在银河麒麟上可能导致Qt Creator无法正确识别文件权限编译时莫名其妙报错。正确的做法是只对可执行文件加执行权限目录权限保持755。第二个坑是磁盘突然空白。银河麒麟V10有个已知问题在某些NVMe硬盘上系统运行一段时间后/home分区可能突然变成只读或者挂载丢失。如果遇到这种情况先别慌检查dmesg | grep -i error看是不是硬盘I/O错误。如果是文件系统损坏用fsck修复。平时养成定期备份代码的习惯别把重要东西只放在一个地方。第三个坑是Navicat到期。银河麒麟软件源里的Navicat是试用版到期后无法启动。如果只是需要连接MySQL可以用DBeaver或者MySQL Workbench替代都是免费开源的。6.3 性能优化建议银河麒麟的UKUI桌面本身占资源不少如果开发机配置一般建议关掉一些视觉效果。另外VSCode的文件监视器在大型项目里可能吃满inotify限制编辑/etc/sysctl.conffs.inotify.max_user_watches524288执行sudo sysctl -p生效。这个调整对Qt这种头文件多的项目特别有用能避免VSCode提示“无法监视文件变化”。Qt Creator的编译速度也可以通过make -j$(nproc)来提升在项目-构建步骤里把Make参数改成-j8或者-j$(nproc)充分利用多核CPU。7. 关于国产化开发环境的一些个人体会这套环境我在三台不同配置的银河麒麟机器上都部署过有飞腾FT-2000的也有兆芯的还有一台是海光的。整体感受是银河麒麟V10 SP2之后的版本生态已经比早期好太多了。VSCode和Qt的安装基本能按照标准Linux的流程走不需要太多特殊处理。但国产化环境最大的挑战不是软件安装而是版本碎片化。不同项目用的Qt版本不一样有的要求5.12有的要求5.15还有的已经开始用Qt 6。我的建议是如果条件允许用Docker或者容器化方案来隔离不同项目的开发环境。银河麒麟上装Docker没问题把Qt和编译工具链都封在容器里换项目时直接换容器比在宿主机上反复卸载安装要省心得多。另外银河麒麟的软件源更新频率不高有些新版本的开发工具在源里找不到。这时候不要死磕系统源直接去官网下载离线包或者从源码编译。Qt和VSCode都提供了完整的离线安装方案只要把依赖处理干净跑起来很稳。最后说一个细节银河麒麟的默认shell是bash但有些脚本可能用了dash的语法。如果遇到脚本执行报错检查一下/bin/sh指向的是哪个shell。可以用sudo dpkg-reconfigure dash切换选“No”保持bash作为默认sh。这个在编译一些老项目的configure脚本时特别重要。