1. 项目概述与背景最近在给一个国产化项目做技术适配客户要求最终交付物必须能在银河麒麟V10操作系统上稳定运行。项目本身是一个用Unity引擎开发的模拟训练应用我们团队之前的主力打包工具一直是Windows平台下的各种方案面对这个全新的Linux国产化环境打包部署成了第一个拦路虎。经过几轮踩坑和测试最终我们选定并成功用Qt Installer Framework以下简称QtIFW完成了在银河麒麟V10上对Unity游戏的打包并且完美解决了桌面快捷方式的配置问题。这个过程远比想象中复杂不仅仅是换个打包工具那么简单涉及到从Unity导出设置、Linux依赖库处理、到安装包交互逻辑的全链条适配。今天我就把这个从零到一的“保姆级”流程拆解清楚如果你也面临类似的国产化交付需求这篇内容应该能帮你省下至少一周的摸索时间。简单来说我们要做的是在银河麒麟V10桌面操作系统上将一个完整的Unity项目通常导出为Linux x86_64版本打包成一个专业的、可图形化安装的.run安装包。这个安装包要能自动处理依赖、创建桌面菜单项和快捷方式并且具备标准的安装、卸载流程。QtIFW本身是一个用于创建安装程序的框架它原生支持跨平台其生成的安装程序在Linux下表现非常专业这正是我们需要的。2. 核心工具链选型与原理剖析2.1 为什么是Qt Installer Framework在Linux下打包分发软件常见的选择有制作简单的tar.gz压缩包、编写deb/rpm包、或者用一些打包工具。我们逐一分析过tar.gz压缩包最简单但用户体验最差。用户需要手动解压、可能还要自己处理依赖、创建快捷方式完全不符合一个成熟产品的交付标准。deb/rpm包是Linux软件分发的标准形式可以通过系统包管理器安装卸载能自动解决依赖。但问题在于首先制作过程有学习成本其次其依赖管理严重绑定特定的发行版如deb基于Debian/Ubunturpm基于RedHat/Fedora。银河麒麟V10虽然底层基于Linux但其软件源和库路径有其特殊性制作一个普适性强的deb/rpm包并不容易且无法保证在所有麒麟V10的机器上都能完美安装。其他打包工具如AppImageAppImage的理念是“一个文件到处运行”它把应用和依赖打包成一个可执行文件。这听起来很美好但对于复杂的Unity应用尤其是依赖特定版本系统库如某些图形驱动库时AppImage可能会遇到兼容性问题且其文件体积通常较大。最终选择QtIFW基于以下几个核心考量跨平台一致性我们的产品线也涉及WindowsQtIFW可以让我们用同一套配置逻辑和脚本知识为不同平台生成安装包降低维护成本。专业安装体验它提供图形化安装向导也支持静默安装用户可以自定义安装路径、查看协议、选择组件体验与商业软件无异。灵活的脚本控制QtIFW允许通过JavaScript脚本控制安装、卸载、维护过程的每一个步骤。这正是我们解决“创建银河麒麟V10桌面快捷方式”这个关键需求的技术基础。相对宽松的依赖管理QtIFW安装包并不严格管理系统级依赖它更倾向于打包应用所需的全部第三方库。对于Unity游戏我们可以将引擎导出时附带的所有共享库.so文件一并打包从而形成一个相对独立的运行环境减少对目标系统特定库版本的依赖。当然一些最基础的运行时如glibc仍需系统提供。开源免费对于商业项目来说没有额外的授权费用。2.2 Unity导出设置的关键调整在开始打包之前Unity项目的导出设置是地基这里错了后面全白费。针对银河麒麟V10通常是x86_64架构你需要重点关注以下几点目标平台在File - Build Settings中选择Linux Target Architecture 选择x86_64。不要选择Server版本除非你的应用是无界面的服务端程序。图形API在Player Settings - Other Settings中Rendering部分确保取消勾选Auto Graphics API。然后在下方列表中将Vulkan移到第一位其次是OpenGL Core。银河麒麟V10的默认桌面环境对Vulkan的支持已经比较完善优先使用Vulkan能获得更好的性能和兼容性。将OpenGL Core作为备选。脚本后端在Configuration中Scripting Backend推荐使用IL2CPP。虽然这会增加构建时间但生成的二进制代码性能更好且更安全。确保Target Architecture包含了x86_64。屏幕空间UI如果你的游戏使用了大量的UGUI Canvas并且Canvas的Render Mode是Screen Space - Overlay在部分Linux窗口管理器下可能会遇到输入事件穿透或渲染层级问题。一个实用的技巧是将关键的全屏UI Canvas改为Screen Space - Camera模式并指定一个专用的、只渲染UI的Camera。构建输出构建时选择输出到一个干净的文件夹。你会得到一个可执行文件默认与项目名相同和一个_Data文件夹包含资源、代码、库等。请务必将这个可执行文件重命名为一个更通用的名字例如MyGameLauncher避免使用空格和特殊字符。因为后续的安装脚本会频繁引用它。注意在银河麒麟V10上实测Unity 2021 LTS及之后的版本兼容性更好。如果使用较老的Unity版本可能会遇到因系统库版本过高如glibc而导致游戏无法启动的问题。如果条件允许建议将项目升级到稳定的LTS版本。3. Qt Installer Framework 环境部署与项目结构搭建3.1 在银河麒麟V10上安装QtIFWQtIFW本身不提供银河麒麟V10的预编译包但我们可以通过源码编译安装或者使用其他Linux发行版的二进制包通常是兼容的。这里推荐使用二进制包更快捷。下载二进制安装包访问Qt官方下载页面找到Qt Installer Framework的Linux版本通常是一个.run文件。你可以在一台可以联网的机器上下载然后拷贝到银河麒麟V10的开发机上。安装在终端中赋予下载的.run文件执行权限然后运行安装。chmod x qt-installer-framework-linux-x64.run sudo ./qt-installer-framework-linux-x64.run安装过程是图形化的选择一个安装路径例如/opt/QtIFW。安装完成后将QtIFW的bin目录添加到系统的PATH环境变量中方便后续使用命令行工具。# 编辑 ~/.bashrc 文件 echo export PATH$PATH:/opt/QtIFW/bin ~/.bashrc source ~/.bashrc验证安装运行binarycreator --version和repogen --version如果能输出版本信息说明安装成功。3.2 创建QtIFW项目骨架QtIFW项目有一套标准的目录结构。我们在一个工作目录下创建如下结构MyGameInstaller/ ├── config/ │ └── config.xml # 安装包主配置文件 ├── packages/ │ └── com.vendor.mygame/ │ ├── meta/ │ │ ├── package.xml # 组件包描述文件 │ │ └── installscript.qs # 安装控制脚本 │ └── data/ # 这里存放我们要打包的所有文件 │ ├── MyGameLauncher # Unity生成的可执行文件 │ ├── MyGame_Data/ # Unity的Data文件夹 │ ├── ... (其他依赖的.so库如果有的话) │ └── ... (文档、许可文件等) └── installer.ico (可选Windows用Linux忽略)关键文件解析config/config.xml: 这是安装程序的全局配置。?xml version1.0 encodingUTF-8? Installer Name我的超级游戏/Name Version1.0.0/Version Title我的超级游戏 安装程序/Title Publisher我的工作室/Publisher StartMenuDir我的超级游戏/StartMenuDir TargetDirHomeDir/MySuperGame/TargetDir MaintenanceToolNameMaintenanceTool/MaintenanceToolName /InstallerTargetDir默认安装路径。HomeDir是QtIFW的内置变量代表用户家目录。MaintenanceToolName指定维护工具用于卸载、修改安装的名称。packages/com.vendor.mygame/meta/package.xml: 定义组件包信息。?xml version1.0 encodingUTF-8? Package DisplayName我的超级游戏/DisplayName Description这是一个激动人心的Unity游戏。/Description Version1.0.0/Version ReleaseDate2023-10-27/ReleaseDate Defaulttrue/Default Scriptinstallscript.qs/Script /PackageScript指定与该组件包关联的安装脚本。packages/com.vendor.mygame/meta/installscript.qs这是整个打包过程的灵魂所有自定义逻辑都在这里。我们稍后详细展开。packages/com.vendor.mygame/data/这是数据目录。你需要将Unity导出的全部内容可执行文件、_Data文件夹、以及可能自带的第三方.so库复制到这个data目录下。请保持其在Unity导出时的相对路径结构。4. 核心脚本解析安装、卸载与快捷方式配置installscript.qs是一个JavaScript脚本Qt的扩展称为QScript它定义了安装过程中的各种操作。我们需要实现三个核心功能安装时复制文件、创建桌面和菜单快捷方式卸载时删除所有相关文件。4.1 组件安装函数function Component() { // 组件构造函数 } Component.prototype.createOperations function() { // 调用父类方法建立默认操作如文件复制 component.createOperations(); // ********** 关键步骤为Linux创建快捷方式 ********** // 注意QtIFW的安装操作在“目标目录”进行所以我们需要在文件复制完成后再创建指向目标目录的快捷方式。 // 因此我们不在createOperations里直接创建而是在安装最后一步进行。 }真正的安装后逻辑我们写在Component.prototype.createOperations之外通过重写安装向导的finished回调来实现。4.2 实现安装完成后的回调我们需要监听安装程序的“完成”信号然后执行创建快捷方式等操作。一个更可靠的做法是在createOperations函数末尾为安装程序添加一个回调操作。Component.prototype.createOperations function() { component.createOperations(); // 在安装操作链的最后添加一个自定义操作来创建快捷方式 if (installer.value(os) x11) { // 判断是否为Linux/X11环境 component.addOperation(CreateShortcuts); } } // 定义“CreateShortcuts”操作的具体内容 Component.prototype.createShortcuts function() { // 获取安装目录和目标可执行文件路径 var installDir component.value(TargetDir); var executablePath installDir /MyGameLauncher; // 你的可执行文件名 var iconPath installDir /MyGame_Data/Resources/UnityPlayer.png; // 使用Unity自带的图标或你自己准备的图标 // 1. 创建桌面快捷方式 (.desktop 文件) var desktopFileContent [Desktop Entry]\n TypeApplication\n Name我的超级游戏\n Comment一个Unity开发的精彩游戏\n Exec\ executablePath \ %U\n Icon iconPath \n Terminalfalse\n CategoriesGame;\n StartupWMClassMyGameLauncher; // 这行很重要用于窗口匹配通常填可执行文件名 var desktopFilePath installer.value(DesktopDir) /my-super-game.desktop; // 使用QFile和QTextStream写入文件这里简化为概念实际需调用Qt脚本对象 // 在实际脚本中我们需要用QInstaller.createDesktopFile等内部函数或执行shell命令 // 方法A使用QtIFW的内部工具函数如果可用 // 方法B更通用的使用shell命令调用系统工具desktop-file-install // 这里展示方法B通过执行shell命令 var cmd desktop-file-install --dir installer.value(HomeDir) /.local/share/applications --set-keyExec --set-value\\\ executablePath \\\ --set-keyIcon --set-value iconPath --set-keyName --set-value\\\我的超级游戏\\\ (installer.value(DesktopDir) ? (--add-category Game --set-keyPath --set-value installDir // 设置工作目录 \ desktopFilePath \) : ); // 执行命令 installer.execute(cmd); // 2. 创建应用程序菜单项实际上desktop-file-install已经将其安装到~/.local/share/applications // 如果需要复制到系统级目录如/usr/share/applications需要root权限不推荐。 // 对于当前用户安装~/.local/share/applications 是标准位置。 // 3. (可选) 确保可执行文件有运行权限 installer.execute(chmod, x, executablePath); }重要提示上面的desktop-file-install命令是一个理想化的示例。在实际的QtIFW脚本环境中直接拼接和执行复杂的shell命令可能会遇到转义问题。更稳健的做法是先在脚本内构建完整的.desktop文件内容字符串。使用QFile和QTextStream对象Qt Script环境提供将内容写入一个临时文件。使用installer.execute调用desktop-file-install命令安装这个临时文件。或者更直接地将.desktop文件直接复制到~/.local/share/applications/和DesktopDir。但直接复制需要手动处理Exec和Icon路径的变量替换。4.3 一个更实际、更完整的脚本示例下面是一个整合了健壮性处理的installscript.qs示例// installscript.qs function Component() { } Component.prototype.createOperations function() { // 调用基类方法设置默认的文件复制操作 component.createOperations(); // 如果是Linux添加创建快捷方式的操作 if (installer.value(os) x11) { component.addOperation(CreateShortcuts); } } // 自定义操作CreateShortcuts Component.prototype.createShortcuts function() { try { var installDir component.value(TargetDir); var appName MySuperGame; var execName MyGameLauncher; var execPath installDir / execName; var iconName game_icon.png; // 假设你有一个图标放在data目录根下 var iconPath installDir / iconName; // 构建 .desktop 文件内容 var desktopContent [Desktop Entry]\n Version1.0\n TypeApplication\n Name appName \n CommentAn awesome Unity game.\n Exec\ execPath \\n Icon iconPath \n Terminalfalse\n CategoriesGame;\n StartupWMClass execName \n; // 获取用户桌面和应用程序目录 var desktopDir installer.value(DesktopDir); var applicationsDir installer.value(HomeDir) /.local/share/applications; // 创建应用程序目录如果不存在 installer.execute(mkdir, -p, applicationsDir); // 写入应用程序菜单的 .desktop 文件 var appDesktopPath applicationsDir / appName.toLowerCase().replace(/\s/g, -) .desktop; var file new QFile(appDesktopPath); if (file.open(QFile.WriteOnly | QFile.Text)) { var out new QTextStream(file); out.write(desktopContent); file.close(); // 设置文件权限 installer.execute(chmod, 644, appDesktopPath); } else { console.log(Failed to write application desktop file.); } // 写入桌面快捷方式如果桌面目录可用 if (desktopDir) { var desktopFilePath desktopDir / appName .desktop; var desktopFile new QFile(desktopFilePath); if (desktopFile.open(QFile.WriteOnly | QFile.Text)) { var out2 new QTextStream(desktopFile); out2.write(desktopContent); desktopFile.close(); installer.execute(chmod, 755, desktopFilePath); // 桌面快捷方式需要可执行权限 } else { console.log(Failed to write desktop shortcut.); } } // 确保启动器可执行 installer.execute(chmod, x, execPath); console.log(Shortcuts created successfully.); } catch (e) { console.log(Error creating shortcuts: e.message); } }4.4 卸载脚本卸载时需要清理我们创建的文件。这通常在Component.prototype.createOperations中通过添加Delete操作来实现但更清晰的做法是重写卸载相关的函数。Component.prototype.createOperationsForArchive function(archive) { component.createOperationsForArchive(archive); // 在卸载操作链中添加删除快捷方式的自定义操作 if (installer.value(os) x11) { component.addOperation(DeleteShortcuts); } } Component.prototype.deleteShortcuts function() { var appName MySuperGame; var applicationsDir installer.value(HomeDir) /.local/share/applications; var desktopDir installer.value(DesktopDir); var appDesktopPath applicationsDir / appName.toLowerCase().replace(/\s/g, -) .desktop; if (QFile.exists(appDesktopPath)) { QFile.remove(appDesktopPath); } if (desktopDir) { var desktopFilePath desktopDir / appName .desktop; if (QFile.exists(desktopFilePath)) { QFile.remove(desktopFilePath); } } console.log(Shortcuts removed.); }5. 构建与测试安装包5.1 使用 binarycreator 构建安装包当所有文件就位、脚本编写完成后就可以构建安装包了。在终端中切换到项目根目录MyGameInstaller的上一级执行命令binarycreator -c config/config.xml -p packages MyGame_Installer.run-c: 指定配置文件路径。-p: 指定包含组件包的目录。最后的参数是输出的安装包文件名通常以.run结尾这是Linux下常见的可执行安装包格式。这个过程会打包data目录下的所有文件并嵌入配置和脚本生成一个独立的MyGame_Installer.run文件。5.2 在银河麒麟V10上测试安装包分发与权限将生成的.run文件拷贝到目标测试机银河麒麟V10。首先赋予其执行权限chmod x MyGame_Installer.run图形化安装双击运行或者在终端中执行./MyGame_Installer.run就会启动熟悉的图形化安装向导。你可以测试选择安装路径、点击下一步、完成安装。验证安装结果检查目标安装目录下文件是否完整。检查桌面是否生成了快捷方式。检查开始菜单应用程序启动器中是否能找到你的游戏。双击桌面快捷方式或菜单项启动游戏测试功能是否正常。测试卸载通过开始菜单中的MaintenanceTool如果你在config.xml里设置了其他名字就是那个名字或者在安装目录下运行./MaintenanceTool启动维护工具选择卸载验证是否能干净地移除程序和快捷方式。6. 常见问题排查与实战心得6.1 Unity游戏启动黑屏或无响应这是Linux下部署Unity游戏最常见的问题。原因1图形驱动问题。银河麒麟V10可能使用开源驱动如Mesa或闭源驱动如NVIDIA。首先确保系统已安装合适的显卡驱动。排查在终端中运行glxinfo | grep OpenGL renderer查看当前使用的渲染器。运行游戏时查看终端输出如果你从终端启动或系统日志journalctl -f是否有OpenGL或Vulkan相关的错误。解决尝试在Unity导出设置中切换图形API的优先级。如果黑屏尝试将OpenGL Core移到Vulkan前面。也可以尝试在启动游戏时添加命令行参数-force-glcore或-force-vulkan来强制指定API。原因2依赖库缺失。Unity导出的Linux版本会链接一些特定的系统库。虽然大部分库已打包在_Data文件夹的Plugins/x86_64目录下但仍有少数基础库依赖系统。排查在终端中使用ldd命令检查可执行文件的动态链接情况ldd MyGameLauncher。查看是否有not found的库。解决对于常见的缺失库如libicu、特定版本的libstdc可以在银河麒麟V10的软件源中搜索安装例如sudo apt-get install libicu-dev包名可能不同麒麟使用yum或apt视版本而定。更彻底的做法是将这些库的兼容版本也打包到你的data目录下并利用LD_LIBRARY_PATH环境变量在启动脚本中指定优先加载路径。原因3文件权限或路径问题。快捷方式中的Exec路径错误或者可执行文件没有x权限。排查检查桌面快捷方式.desktop文件的Exec字段路径是否正确且用引号包裹因为路径可能包含空格。检查安装目录下的可执行文件是否有执行权限ls -l MyGameLauncher。解决修正.desktop文件确保Exec路径是绝对路径。在安装脚本中务必执行chmod x。6.2 桌面快捷方式不显示或点击无效图标不显示.desktop文件中的Icon路径必须是绝对路径且图标文件格式需被支持如PNGSVG。建议将图标文件打包进安装目录并使用绝对路径引用。快捷方式不出现.desktop文件必须放在正确的目录~/.local/share/applications/用于当前用户并且具有正确的权限至少644。对于桌面快捷方式还需要有可执行权限755。安装后有时需要刷新桌面环境才能立即显示可以尝试注销再登录或运行update-desktop-database ~/.local/share/applications命令。点击无效除了检查Exec路径还需检查StartupWMClass字段。这个字段用于将应用程序的窗口与快捷方式关联。如果设置不正确点击启动后可能在任务栏上创建新的图标而不是聚焦到已运行的窗口。通常这个值设置为可执行文件的名称不含路径和扩展名。你可以通过运行游戏后使用xprop WM_CLASS命令点击游戏窗口来获取正确的值。6.3 安装包体积过大Unity游戏本身资源就多打包后体积大是常态。QtIFW默认不会压缩data目录下的文件。优化可以使用binarycreator的-n参数启用压缩但注意这可能会增加安装时的解压时间。binarycreator -c config/config.xml -p packages -n MyGame_Installer.run终极优化考虑对Unity项目本身进行资源优化如纹理压缩、音频格式转换、代码剥离等这是减少体积的根本。6.4 维护工具MaintenanceTool相关问题找不到维护工具确保在config.xml中正确设置了MaintenanceToolName并且安装后该工具存在于安装根目录。在脚本中不要删除或移动它。维护工具无法更新如果你后续需要发布更新需要使用repogen工具生成在线仓库并配置维护工具指向该仓库。这涉及到更复杂的持续交付流程本篇不展开。个人实操心得脚本调试QtIFW脚本的调试比较困难。多使用console.log()将变量信息输出到安装时的终端如果你从终端启动安装程序。这是定位脚本问题最有效的方法。路径分隔符在Qt脚本中文件路径使用正斜杠/即使在Windows上编译时也是如此这保证了跨平台脚本的一致性。用户权限我们的安装脚本默认以当前用户权限运行因此只能操作用户目录~/.local,~/Desktop。不要试图在脚本中向/usr/share等系统目录写入文件除非安装程序本身以root权限运行不推荐。充分测试一定要在纯净的、与目标环境一致的银河麒麟V10系统上进行测试。虚拟机测试是第一步但最终必须在真实硬件或与客户环境一致的镜像上进行完整测试包括安装、运行、卸载的全流程。