Unity应用部署到银河麒麟V10：打包配置、权限处理与避坑指南

1. 为什么要在麒麟系统上跑Unity应用1.1 一个真实的需求场景去年接了个单子客户是某事业单位要求把一套Unity做的三维展示系统部署到内网机器上机器清一色装的银河麒麟V10。当时第一反应是Linux打包嘛Unity不是有Linux Build Target吗结果真上手才发现坑远比想象的多——打包出来的可执行文件在麒麟上双击没反应、字体全变方块、视频播不了、文件读写权限被卡死。折腾了差不多两周才算跑通中间踩的坑我基本都记了下来。这篇东西就是那次项目的完整复盘。核心讲三件事Unity怎么给麒麟系统出包、路径和权限怎么处理、以及那些官方文档里不会写的坑。适合手里有Unity项目、需要往国产Linux系统上部署的开发者也适合刚接触麒麟系统、想搞清楚Linux下应用分发逻辑的朋友。不需要你有多深的Linux功底但基本的命令行操作得会。1.2 先搞清楚麒麟系统到底是什么很多人一听麒麟系统就懵其实它本质上是基于Linux内核的国产发行版目前主流的是银河麒麟V10底层跟Ubuntu、CentOS是同一套东西包管理用的是apt或yum看具体版本。所以你在Ubuntu上能跑的东西理论上麒麟也能跑只是有些库的版本和默认配置不一样。这里有个关键认知麒麟系统分桌面版和服务器版桌面版才有图形界面Unity应用要跑就得装桌面版。而且麒麟默认开启了比较严格的安全策略普通用户对系统目录几乎没有写权限这一点跟Ubuntu的sudo一把梭体验差别很大后面讲权限的时候会重点说。Unity这边官方支持的Linux Build Target从2019版本就稳定了2021 LTS和2022 LTS是现在用得最多的。我实测下来2021.3.x系列在麒麟上兼容性最好2022的部分版本对某些显卡驱动有兼容问题这个后面细说。1.3 整体思路先捋一遍整个流程拆开就是四步准备构建环境 → 配置Player Settings → 打包出可执行文件 → 在麒麟上部署并处理权限。听起来简单但每一步都有细节。我当时的方案是在Windows上用Unity打包出Linux版本x86_64然后把整个输出目录拷到麒麟机器上运行。为什么不直接在麒麟上装Unity打包因为麒麟的软件源里没有Unity Hub手动装依赖太折腾而且麒麟自带的显卡驱动对Unity Editor的支持不稳定容易崩。用Windows打包、麒麟运行是性价比最高的方案。当然如果你非要在麒麟上装Unity Editor也不是不行但那是另一个话题了这篇主要讲打包和部署。2. Unity打包Linux的核心配置细节2.1 安装Linux Build Support模块第一步打开Unity Hub找到你用的Unity版本点右边的齿轮图标选添加模块勾选Linux Build Support (Mono)和Linux Build Support (IL2CPP)。这两个的区别后面会讲建议都装上。如果你用的是Unity 2021之前的版本可能只有Mono选项那也没关系Mono打包出来的包体积小、构建快缺点是性能略低、代码保护弱。IL2CPP是把C#转成C再编译性能好、反编译难但构建慢、依赖多。给麒麟这种国产系统打包我建议优先用IL2CPP因为Mono在部分麒麟版本上会遇到glibc版本不匹配的问题IL2CPP生成的二进制兼容性更好。装模块的时候注意如果你的Unity是装在C盘的模块也会装到C盘占大概1-2G空间提前留好。2.2 Player Settings里必须改的几个地方打开你的项目File → Build Settings → 切到Linux平台 → Player Settings。这里有几个地方不改打包出来在麒麟上大概率出问题。第一个是Architecture。麒麟V10桌面版基本都是x86_64架构所以选x86_64。如果你的目标机器是ARM架构比如某些国产CPU平台那得选ARM64但Unity对Linux ARM64的支持一直不太行很多插件不兼容这个要提前确认。第二个是Scripting Backend。前面说了优先IL2CPP。切到IL2CPP后下面会出现Api Compatibility Level选.NET Standard 2.1或者.NET Framework都行看你的代码用了哪些库。如果用了System.Drawing之类的得选.NET Framework。第三个是Target Device。选Desktop不要选Server。第四个是Graphics API。这个很关键。Unity在Linux下默认用Vulkan但麒麟系统自带的显卡驱动对Vulkan的支持参差不齐尤其是国产显卡。我建议把Vulkan去掉只保留OpenGL Core兼容性最稳。操作是在Player Settings → Other Settings → Rendering → Graphics APIs里把Vulkan删掉只留OpenGL Core。提示如果你的项目必须用Vulkan比如用了某些Compute Shader特性那得确保目标麒麟机器装了支持Vulkan的驱动这个要提前在目标机器上验证。2.3 分辨率与全屏设置麒麟系统的桌面环境UKUI对窗口管理有自己的逻辑Unity默认的全屏模式在麒麟上可能会出问题——要么全屏后切不回来要么分辨率不对。我的做法是Resolution and Presentation里把Fullscreen Mode设成Windowed然后Default Is Native Resolution勾上。这样应用启动时是一个无边框窗口铺满屏幕看起来跟全屏一样但实际是窗口模式切换和退出都正常。如果客户要求必须真全屏那就设成Exclusive Fullscreen但要在代码里加个ESC退出的逻辑不然用户可能卡在里面出不来。分辨率这块Default Screen Width和Height设成1920x1080就行实际运行时会自适应。Resizable Window建议勾上方便调试。2.4 字体与中文显示的处理这是麒麟上最容易翻车的地方。Unity默认用的Arial字体在Linux上不一定有而且中文字符在默认字体下会显示成方块。解决方案有两个一是把中文字体打包进项目在Text组件的Font里指定一个带中文的字体比如思源黑体、微软雅黑然后把这个字体文件放到Assets里Unity会一起打包。二是用TextMeshProTMP需要生成字体图集把常用中文字符加进去这样不依赖系统字体。我推荐第二种TMP渲染质量好而且不依赖系统环境。但要注意TMP的字体图集如果字符集太大包体会膨胀一般加个常用3500字就够了。如果项目里已经大量用了普通Text那就老老实实打包一个中文字体进去。字体文件建议用开源的思源黑体避免版权问题。3. 打包输出与文件结构解析3.1 构建过程与输出目录配置好之后Build Settings里点Build选一个输出目录Unity会生成一个文件夹里面通常包含这些文件一个以你的项目名命名的可执行文件没有扩展名比如MyApp.x86_64一个MyApp_Data文件夹里面是资源、Managed代码等一个UnityPlayer.soIL2CPP模式下是GameAssembly.so可能还有libmonobdwgc-2.0.soMono模式或libil2cpp.soIL2CPP模式UnityCrashHandler64之类的辅助文件整个目录大概几百M到几个G不等取决于你的资源量。关键点这个目录必须整体拷贝不能只拷可执行文件。因为可执行文件依赖同目录下的_Data文件夹和.so库缺一个都跑不起来。3.2 可执行文件的权限问题从Windows拷到麒麟上第一个坑就是可执行文件没有执行权限。Windows的文件系统不记录Linux的权限位拷过去之后所有文件默认是644读写不可执行双击没反应命令行运行会报Permission denied。解决办法很简单在麒麟的终端里进到目录执行chmod x MyApp.x86_64但这里有个细节不只是主可执行文件需要执行权限UnityPlayer.so和GameAssembly.so这些动态库也需要。虽然.so文件理论上不需要x但Unity的加载逻辑有时候会检查保险起见一起加上chmod x *.x86_64 *.so如果目录里文件很多可以用find . -type f \( -name *.so -o -name *.x86_64 \) -exec chmod x {} \;3.3 路径问题的根源Unity应用在Linux下运行时会去几个地方找资源当前工作目录、可执行文件所在目录、以及用户主目录。如果你是从终端cd到目录再./MyApp.x86_64运行工作目录就是当前目录没问题。但如果是双击运行工作目录可能是用户主目录这时候Unity找不到_Data文件夹就会黑屏或崩溃。解决方案写一个启动脚本。在应用目录下建一个start.sh#!/bin/bash cd $(dirname $0) ./MyApp.x86_64然后给这个脚本加执行权限以后双击这个脚本启动就不会有路径问题了。$(dirname $0)的意思是取脚本自身所在的目录这样不管从哪里调用都会先切到应用目录。这个脚本还有个好处可以在里面加环境变量。比如某些麒麟版本需要指定LD_LIBRARY_PATH#!/bin/bash cd $(dirname $0) export LD_LIBRARY_PATH$PWD:$LD_LIBRARY_PATH ./MyApp.x86_643.4 日志与崩溃排查Unity应用在Linux下的日志默认写到~/.config/unity3d/公司名/产品名/Player.log。如果应用启动就崩第一件事就是看这个日志。也可以在启动脚本里加-logfile参数把日志输出到当前目录./MyApp.x86_64 -logfile ./app.log这样排查起来方便不用去翻用户主目录。日志里常见的错误有找不到.so库、OpenGL上下文创建失败、字体加载失败等对应不同的解决方案。4. 麒麟系统权限与路径全攻略4.1 麒麟的权限模型与Ubuntu的差异麒麟V10基于Linux权限模型跟标准Linux一样文件有属主、属组、其他三组权限用rwx表示。但麒麟有几个特殊的地方一是默认用户不是root。安装系统时创建的用户是普通用户sudo需要密码而且麒麟的sudo配置比Ubuntu严格某些操作即使sudo也会被安全策略拦截。二是系统目录保护更严。/usr、/opt、/etc这些目录普通用户完全没写权限sudo写入也可能触发安全审计。所以应用不要往系统目录装放在用户主目录或/home下的某个目录最稳。三是麒麟有安全中心会监控应用的某些行为比如修改系统文件、监听端口等。如果你的Unity应用需要这些操作可能会被拦截需要在安全中心里加白名单。4.2 应用该放在哪个目录我的建议是放在用户主目录下的一个固定目录比如~/MyApp/。这样有几个好处用户有完全读写权限、不需要sudo、卸载时直接删目录就行。如果客户要求所有用户都能用那可以放到/opt/MyApp/但需要sudo创建并且要设置合适的权限sudo mkdir -p /opt/MyApp sudo cp -r ./BuildOutput/* /opt/MyApp/ sudo chown -R root:root /opt/MyApp sudo chmod -R 755 /opt/MyApp这样普通用户能读能执行但不能改。注意chmod -R 755会把所有文件设成可执行对.so和可执行文件没问题但对配置文件和资源文件其实没必要不过不影响运行。4.3 读写权限的处理Unity应用运行时如果需要读写文件比如保存配置、导出数据不要往应用目录写因为如果应用装在/opt下普通用户没写权限。正确做法是写到用户主目录string savePath Path.Combine( Environment.GetFolderPath(Environment.SpecialFolder.Personal), MyAppData ); if (!Directory.Exists(savePath)) Directory.CreateDirectory(savePath);SpecialFolder.Personal在Linux下对应/home/用户名在Windows下对应我的文档跨平台通用。如果一定要在应用目录写那得确保应用目录对当前用户可写。放在~/MyApp/下就没这个问题。4.4 常见权限报错与解决实际部署中最常遇到的权限报错有这么几个报错信息原因解决方法Permission denied可执行文件没有xchmod xcannot open shared object file.so库路径不对或没权限检查LD_LIBRARY_PATHchmod xRead-only file system往只读目录写改写到用户主目录Operation not permitted安全策略拦截安全中心加白名单No such file or directory路径大小写问题Linux区分大小写检查路径最后一条特别容易踩。Windows不区分大小写Linux区分。如果你的代码里写的是Assets/Textures/icon.png实际文件是icon.PNGWindows下没事Linux下就找不到。打包前一定要检查所有资源路径的大小写。5. 那些官方文档不会告诉你的坑5.1 视频播放问题Unity在Linux下的视频播放一直是个老大难。Unity的VideoPlayer在Linux上依赖系统安装的编解码器麒麟默认装的编解码器不全MP4可能播不了。解决方案用AVPro Video之类的第三方插件它们自带解码器不依赖系统。或者把视频转成Unity原生支持的格式但Linux下原生支持也有限。如果非要用Unity自带的VideoPlayer得在麒麟上装gstreamer的插件sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav但麒麟的软件源里不一定有这些包可能得手动下载deb安装。这个比较折腾能避开就避开。5.2 显卡驱动与渲染问题麒麟系统预装的显卡驱动版本通常比较老尤其是国产显卡。Unity应用启动时如果报Failed to initialize graphics大概率是驱动问题。排查步骤先在终端运行glxinfo | grep OpenGL version看看OpenGL版本。Unity的OpenGL Core需要3.2以上如果低于这个就得升级驱动。如果是NVIDIA显卡可以去官网下Linux驱动手动装。如果是国产显卡景嘉微、兆芯等那就得找厂商要适配麒麟的驱动这个只能联系厂商。还有一个坑Unity的阴影在麒麟上可能显示异常。这是因为某些驱动对阴影贴图的支持有问题。解决办法是在Quality Settings里把阴影质量调低或者改用硬阴影。5.3 串口通信的权限问题如果项目里用了串口通信Unity串口通信在工控场景很常见麒麟下访问串口设备需要权限。串口设备通常是/dev/ttyUSB0或/dev/ttyS0默认只有root能访问。解决办法是把当前用户加到dialout组sudo usermod -aG dialout $USER然后注销重新登录生效。或者改串口设备的权限sudo chmod 666 /dev/ttyUSB0但后者每次插拔设备都会重置不如加组靠谱。5.4 打包体积优化Unity打包出来的Linux应用体积通常很大因为包含了完整的Mono或IL2CPP运行时。如果客户对体积有要求可以做这些优化开启Strip Engine CodePlayer Settings → Other Settings → Optimization → Managed Stripping Level设为High能去掉没用的引擎代码。压缩纹理把纹理的压缩格式设成适合Linux的比如ASTC或ETC2。剔除未使用的资源用Asset Bundle或者Addressables把不常用的资源分离出去。IL2CPP的代码剥离IL2CPP模式下可以配置link.xml精确控制哪些代码不被剥离。我那个项目优化前是1.8G优化后压到600M左右效果还是很明显的。5.5 麒麟系统特有的兼容性问题麒麟V10有几个版本SP1、SP2、SP3不同版本的系统库版本不一样。我遇到过SP1上跑得好好的应用SP2上启动就崩原因是glibc版本变了。建议在目标机器上先跑一个最小化的Unity测试应用确认基本环境没问题再部署正式应用。测试应用就一个空场景加一个Cube能跑起来说明环境OK。另外麒麟的UKUI桌面环境对窗口的管理跟GNOME不一样Unity应用的全屏切换、窗口置顶这些行为可能有差异需要实际测试调整。6. 完整部署流程速查6.1 从打包到运行的步骤清单把整个流程整理成一个可执行的清单照着做基本不会漏Unity里装Linux Build Support模块Mono和IL2CPP都装Player Settings里设Architecture为x86_64Scripting Backend选IL2CPPGraphics API只留OpenGL Core去掉VulkanFullscreen Mode设Windowed勾选Native Resolution打包中文字体或用TextMeshPro生成字体图集Build出Linux版本得到输出目录把整个目录拷到麒麟机器U盘或scp都行终端里cd到目录chmod x *.x86_64 *.so创建start.sh启动脚本加执行权限双击start.sh或终端运行看日志排查问题6.2 启动脚本模板直接给一个我常用的启动脚本复制就能用#!/bin/bash # Unity应用启动脚本 # 切换到脚本所在目录 cd $(dirname $0) # 设置库路径 export LD_LIBRARY_PATH$PWD:$LD_LIBRARY_PATH # 设置日志输出 LOG_FILE$PWD/app_$(date %Y%m%d_%H%M%S).log # 启动应用 ./MyApp.x86_64 -logfile $LOG_FILE $ # 检查退出码 if [ $? -ne 0 ]; then echo 应用异常退出日志见 $LOG_FILE read -p 按回车键退出... fi这个脚本做了几件事切目录、设库路径、日志带时间戳、异常时暂停让用户看到错误。实际用下来很省心。6.3 常见问题速查表现象可能原因排查方向双击没反应没有执行权限chmod x启动黑屏工作目录不对用启动脚本中文变方块字体缺失打包中文字体视频不播放编解码器缺失用AVPro或装gstreamer闪退驱动或库不兼容看Player.log全屏切不回窗口模式问题改Windowed模式串口打不开权限不足加dialout组路径找不到大小写问题检查资源路径6.4 一些实操心得最后分享几个我踩坑踩出来的经验。第一永远在目标机器上测试。别在开发机上跑通了就以为没问题麒麟的版本差异、驱动差异、库差异都可能让应用跑不起来。有条件的话搞一台跟客户环境一样的测试机。第二日志是你的朋友。Unity的Player.log、系统的/var/log/syslog、dmesg出问题先看这三个。很多错误日志里写得清清楚楚比瞎猜快多了。第三别用系统字体。麒麟系统自带的字体跟Windows不一样依赖系统字体迟早出问题。所有字体都打包进项目一劳永逸。第四路径全用相对路径或Environment.GetFolderPath。硬编码绝对路径在Linux下必翻车尤其是带盘符的Windows路径。第五权限问题优先考虑用户目录。别跟系统目录较劲往/opt装还要sudo往用户主目录装啥事没有。客户如果要求全局可用那就装/opt然后设好权限但要做好被安全策略拦截的心理准备。这套流程我在三个不同的麒麟项目上验证过从V10 SP1到SP3都跑通了。当然每个项目情况不一样遇到新问题还是得具体分析。核心思路就是环境先验证、权限先理清、日志先打开剩下的就是耐心排查。