在Unreal引擎里摸爬滚打了这几年从4.22一路用到5.2大大小小的坑踩了不少。有的问题查了两三天最后发现就是某个勾选框没开有的问题看着像是引擎Bug翻源码才发现是自己资源命名不规范。这篇东西算是我个人的问题处理记录不是教程就是一次一次解决问题的过程复盘。我会尽量把现象、排查思路、最终解法都写清楚也把一些排查时容易忽略的关键点标出来。如果你是刚开始用Unreal做项目或者正在被某个奇怪问题卡住这篇应该能有参考价值。1. 项目背景与问题类型概览1.1 这个记录是怎么来的先说下背景。我这边主要做的是中小型团队的项目开发覆盖PC、移动端和一些可视化交互类场景。用的技术栈是C和蓝图混合渲染部分依赖UE的延迟光照和静态光照烘焙物理部分以默认的Chaos物理系统为主。团队规模不大测试资源有限很多问题都是开发过程中撞上的当时没有系统整理过这次借着写记录的机会把它们串起来。这些问题的跨度其实很大有渲染层面的有物理模拟层面的有打包发布流程上的还有性能优化和内存管理相关的。每个问题我都尽量贴出当时的排查日志和最终的处理方式。不夸张地说这些坑如果不记下来下次遇到大概率还得重新踩一遍。1.2 问题分类与排查思路总述我习惯把Unreal开发中的问题分成四类资源与资产问题、引擎配置与构建问题、运行时逻辑问题、性能与内存问题。每一类的排查思路差别很大。资源问题最常见比如贴图显示不对、模型导入后有奇怪的拉扯、动画没生效——这类通常先从资产本身的导入设置和引用关系查起。引擎配置和构建问题一般出现在打平台包或者烘焙内容时这类问题建议直接开日志文件和构建日志信息量比弹窗提示大得多。运行时逻辑问题的排查思路是“最小化复现”把无关系统全部关掉用最简单的蓝图或C脚本去验证功能是否正常。性能与内存问题则依赖分析工具Unreal Insights和stat命令是最基础的排查手段。下面的内容就是按这几个方向展开的每个问题都是一个独立的经验片段你可以按需查阅不需要从头到尾连读。2. 渲染与画面问题排查2.1 静态光照烘焙后阴影边缘出现锯齿和漏光这个现象在建筑可视化类项目里特别明显。烘焙完Lightmass之后墙面和地面交接的暗角区域会出现一条一条的锯齿状阴影某些角落还会漏光看起来像阴影没封闭。我一开始以为是Shadow Map的分辨率不足但实际上静态光照烘焙走的是Lightmass跟Shadow Map关系不大。查了一圈之后锁定两个关键因素Lightmass参数里的Static Lighting Level ScaleWorld Settings里的Lightmass重要体积范围先说第一个。Static Lighting Level Scale直接影响光照贴图的分辨率分配值越小分辨率越高烘焙时间也越长。默认一般是1.0如果一个关卡很大相当于用一张相对较粗的贴图去承载整个关卡的光照信息阴影边界自然就不锐利。我把这个值从1.0调到0.5之后锯齿问题明显改善。代价是烘焙时间翻了将近一倍这个需要有心理准备。第二个是漏光问题。漏光的本质是Lightmass计算时场景中某些几何体的包围盒没有完全闭合光线从一个看似封闭的缝隙里“漏”了进去。常见的做法是在漏光位置的边缘手动补一面不可见的阻挡面比如加一个很薄的Blocking Volume把它标记为不参与渲染但参与光照计算。这个操作在BSP模型上尤其常用因为BSP的面拼接偶尔会产生极细小的裂缝。注意调低Static Lighting Level Scale之后如果场景里没有一个完整覆盖的Lightmass Importance Volume烘焙时间会长得非常离谱。务必在World Settings里把Importance Volume范围拉满到场景关键区域。顺带提一句如果是比较新的引擎版本开启了Lumen也可以考虑直接放弃静态烘焙改用Lumen的实时全局光照方案这样根本不用考虑Lightmass的那套参数。不过Lumen在低端显卡和移动端的开销还是偏高除非目标平台性能足够否则我建议还是老老实实调Lightmass。2.2 模型贴图在近距离观察时出现闪烁这个问题的具体表现是当相机靠近某一个模型表面或者模型表面与另一个表面几乎平行贴合时画面上会出现高频闪烁的噪点像是贴图在“震动”。这种闪烁其实不是贴图问题而是深度冲突(Z-fighting)。Unreal的深度缓冲精度是有限的当一个表面距离相机很近且投影深度数值非常接近时深度测试就很难稳定判断哪个像素在前哪个在后。最常见的高发场景是地砖与地砖之间、墙纸与背景板之间或者两个重叠的平面模型。排查的时候我用了一个笨办法把相机拉远闪烁消失拉近闪烁出现。然后我把其中一块平面手动偏移0.1个单位闪烁就没了。这基本确定是Z-fighting。正规解法有几个调整相机的Near Clip Plane把Near Clip Plane从默认的10调整到100或者更大。但要小心如果场景里有需要近距离观察的物体这个值太大会导致近处物体被裁掉。设置模型深度偏移在材质编辑器里启用Pixel Depth Offset用噪声贴图或者固定值给深度加一个很小的偏移让两个表面在深度测试时不再完全重合。使用贴花(Decal)方案像地上贴的标识、墙面挂的画尽量用Decal而不是实际建模Decal本身有专用的深度偏移机制不会跟基础表面打架。提示Z-fighting不是只出现在静态场景动态物体跟静态场景靠近时也会出现。比如可拾取物掉落到地板上如果没有足够的厚度或者没有给可拾取物的碰撞体设置合理的Margin同样会闪。这时候用Physics Body里Sphere Radius与Capsule的Half Height组合方式能有效避免。我在实际项目中比较常用的组合是网格体本身不要做太薄给表面一个最小的物理厚度同时材质里开启Pixel Depth Offset。两层保险下来闪的情况基本灭了。3. 构建与打包问题处理3.1 热更新包体越来越大加载时间越来越长这个问题的背景是项目里做了基于Pak包的资源热更新机制核心思路是游戏客户端先加载一个最小的启动Pak然后从服务器下载后续资源再通过动态挂载的方式加载新的Pak。项目跑了一个月之后测试反馈启动时加载时间从原来的20秒涨到了40多秒而且包体也从1.2GB增加到了2.4GB。诊断逻辑很简单包体变大说明内容物增加了加载时间变长说明扫描或挂载的Pak数量变多或者某个Pak内部的资源索引变得臃肿。我先用命令行工具把Pak文件列表导出来看UnrealPak.exe -List E:\Project\Saved\StagedBuilds\Android_ASTC\ProjectName\Content\Paks\patch001.pak -Text结果发现里面混进了一堆美术同事测试用的高模FBX、临时落地的贴图甚至还有一份策划配表的多语言副本。这些资源明明不在项目打包设置里为什么会进Pak原因是有一些资产被Soft Reference或者Primary Asset ID间接引用了导致打包器认为它们是必需资源就一并收进来了。解法分两步第一步是做打包资源白名单在Project Settings - Packaging里开启List of Maps to Include in a Package Build只勾选实际需要的地图然后在Additional Asset Types to Include里精确枚举要打进Pak的资产目录。我把美术临时目录从/Game/Art/Temp移到项目目录之外让打包器根本扫描不到。第二步是限制单次热更新的大小在资源服务器端做清单比对把增量更新限制为“只下发变更的资源”。这样可以避免每次全量下载。跟服务端沟通好之后第一次全量包大约900MB之后每次增量更新只有几十MB到几百MB用户等待时间大幅下降。提示检查Pak内容的工具除了命令行的UnrealPak还可以在编辑器里打开Project Launcher用Build流程里的Archive步骤配合Diagnostics选项直接看到每个Stage的资源清单。这一步在打包机器上操作比反解Pak包要快得多。这里要强调一个习惯性问题热更新方案接入之后团队里每个人都会往项目里丢资源如果不做定期的包体体检包体增长就是必然的。我当时定了一个规矩每个迭代版本发布之前负责构建的人必须跑一次资源清单对比把新增资源的数量、类型、大小整理成表格发给全组。这个习惯操作不算复杂但对包体控制的作用非常直接。3.2 移动端构建后贴图发白或颜色严重偏移有段时间Android包提测之后发现角色衣服的贴图颜色整个偏灰部分UI贴图干脆变成纯白。同一个资源在编辑器里颜色正常但手机上就是不对。第一反应是Shader编译问题因为移动端GPU支持的压缩纹理格式和桌面端不同。查了打包日志发现ASTC格式的贴图在部分测试机型上没有被正确识别。Unreal在Android端的默认纹理格式是ASTC但如果项目里还有老设备或者部分资源在导入时被强制指定为ETC2就会出现格式不一致导致的颜色读取异常。处理方式是统一项目的纹理压缩格式。在Project Settings - Android - Texture Formats里把Default Settings下的Texture Format从Auto改为ASTC确保所有贴图都按ASTC标准导出。同时清理了项目中手动指定压缩格式的资产把所有Texture资产统一改为TC_ASTC如果某些贴图在导入时被设置了TC_BC7或其它格式全部重建。还有一个容易被忽略的点移动端烘焙时默认剔除了很多编辑器专用的Shader变体如果美术材质里用了编辑器特有的节点比如Debug相关的节点打包后就会被替换成默认白色。排查时我逐个检查了材质编辑器里的节点类型把不在移动端特性支持范围内的节点全部换掉最终颜色恢复正常。提示如果一台设备上颜色正常、另一台偏白基本可以确定是压缩格式兼容性或者Shader变体缺失问题。先用r.ShaderPipelineCache日志查看设备实际编译的Shader信息再判断是压缩格式还是变体问题不要一上来就重装包。4. 物理与场景交互问题4.1 角色被卡进墙体或者网格体穿插这个问题在测试场景中出现得非常多角色沿着墙角走的时候偶尔会被卡进墙面模型里视角看起来像是穿模了走两步又弹出来。更让人头疼的是有时候角色会整个陷到地板下面直接掉出世界。最先怀疑的是碰撞体的形状与网格体不匹配。Unreal的角色移动默认使用Capsule胶囊体作为碰撞形状Capsule如果比模型窄就会导致角色模型本身穿过墙壁但Capsule还卡在外面。我做的调整很直接进入角色的CapsuleComponent设置Capsule Half Height和Capsule Radius与角色模型的实际体积匹配确保Capsule边界完全包裹住角色的躯干部分。但这只能解决穿模问题的一部分。真正麻烦的是墙角处的碰撞“卡壳”。当角色同时贴着两面墙移动时如果Capsule与墙面的接触点判断不稳定物理系统会在两个接触点之间来回切换导致角色轻微抖动严重时会被挤到墙里。Unreal的CharacterMovementComponent里有一个bSweep选项默认是开启的它会在移动时做Sweep测试理论上不太会出现这种情况。但我在测试中发现如果角色移动速度过快Sweep的频率跟不上照样穿模。解法是开启CharacterMovementComponent里的bRunPhysicsWithNoController同时把Max Walk Speed控制在一个合理范围内不要超过每秒600单位。如果项目确实需要高速移动那就要考虑在移动的帧更新里手动做一次FloorLineTrace或者FindFloor检测把穿模的情况兜底救回来。还有一个很实用的技巧是给墙角和柱子加上一点倒角也就是在建模阶段就把这些尖锐边缘做成有弧度的面。这一招虽然听起来很“美术”但效果非常好因为物理引擎处理圆滑表面比处理尖锐角面要稳定得多卡角概率直接降一个档次。4.2 物理模拟的物体在生成起点处乱蹦这个问题出现在一个交互类项目里玩家可以拾取场景中的一些道具拾取之后通过物理模拟把它们抛出去。Bug的表现是道具在生成时或在被放到某个位置时会自己不停地跳动甚至直接弹飞。排查过程很有意思。一开始我以为是重力参数或物理材质的问题但检查之后发现所有物体的Physics Material和Gravity Scale都是默认值排除。后来又怀疑是碰撞体与其他静态网格体在初始位置重叠导致物理系统为了“推开重叠物”而施加了额外的力。这个方向看起来更接近真相。Unreal的物理引擎在对象生成时会做一次接触检测。如果新生成的物体一开始就跟地面或其他物体重叠引擎会尝试通过施加冲量来解除重叠表现就是乱蹦。解决思路很简单生成时先把物理模拟关掉让对象保持视觉位置等一帧或几帧之后确保引擎完成初始接触计算再开启模拟。在蓝图里就是在Begin Play事件里获取到目标的Static Mesh Component禁用Simulate Physics使用Delay节点或Timer延迟0.2秒延迟结束后重新启用Simulate Physics这样处理之后乱蹦的情况基本消失。同理如果一个物体是从很远的点传送过来也要在传送后延迟一帧再开启模拟避免传送本身触发的碰撞力把物体甩出去。注意Simulate Physics的开启和关闭不是瞬时的引擎要等一个物理帧的处理周期。如果你用一个极短的时间比如0.01秒延迟可能仍然会触发碰撞力。经验值是延迟至少0.1秒以上。5. 性能与内存优化记录5.1 DrawCall导致的性能瓶颈有一次性能测试时发现PC端帧率在一个室内场景只有45帧而性能分析显示CPU端渲染线程占用非常高。用stat RHI查看发现DrawCall数量达到了惊人的3800多。Unreal的渲染机制里一个DrawCall对应一次GPU绘制指令。室内场景之所以高是因为场景里摆放了大量独立的小物件——桌子上的杯子、墙上的挂画、沙发上的抱枕——每一个物件即使模型很小只要它在渲染队列里没有被合批就会占一个DrawCall。我当时做的优化顺序是这样第一开启Use Instanced Static Meshes把场景里大批量重复的小物件比如椅子、柱子替换为Instanced版本。用HISMHierarchical Instanced Static Mesh组件承载这些重复实例DrawCall从几百个瞬间降到十几个。第二处理非重复物件的合批逻辑。在Merge Actor工具里把零散的小物体按区域合并成一个大的静态网格体。比如一个桌面上的笔筒、一个咖啡杯、几本书合并成一个Mesh。这个操作会破坏原本独立的动态性但如果是完全静态的场景合批不会影响视觉效果。第三降低透明物体的DrawCall开销。透明物体没法走普通的Opaque合批路径所以尽量把透明物体数量控制在最低线或者用Mask替代Alpha混合。优化完之后帧率回到72帧以上DrawCall稳定在1200左右。这个案例给我的经验是先分清DrawCall是CPU瓶颈还是GPU瓶颈。stat RHI里如果DrawPrimitive的耗时远高于FinishDrawing说明CPU提交绘制命令太频繁减DrawCall就有用如果GPU端耗时高单纯减DrawCall帮助不大得整理渲染的Overdraw。5.2 内存持续上涨最终崩溃移动端项目测了一段时间后出现一个诡异的问题游戏内存使用量每隔几分钟就涨一部分越玩越卡最后直接闪退。刚开始以为是场景加载没有释放旧关卡但检查关卡流送都是正常的。后来用stat Memory和内存分析工具逐项排查发现是动态生成的Material Instance没有释放。我的项目里有一个拾取反馈系统每次玩家拾取道具时都会基于基础材质动态创建一个Material Instance并把它指定给道具模型。按逻辑拾取之后这个实例应该没用了应该被垃圾回收。问题出在蓝图里的引用关系上。项目用的是一个全局的GameInstance保存当前道具的状态里面有个变量存了最新的Material Instance引用。这个引用一直存在垃圾回收器认为这个实例仍然被使用所以不会回收。每次拾取都创建一个新实例旧实例就一直堆积在内存里内存自然就涨上去了。解法是在道具拾取完成后手动清空GameInstance里保存的Material Instance引用并把材质实例上的贴图资源解除引用。如果是在C里做还可以用WeakObjectPtr替代强引用这样垃圾回收器就能正常回收动态生成的资源。提示动态生成Material Instance本身不是问题问题永远是“谁持有它的引用”。排查内存问题时直接在Memory Profiler里看Class Memory和Reference Count定位到持有引用的对象比盲目猜测要快得多。Unreal Insights里的Memory面板也能清晰看到分配趋势。6. 常见问题速查表与避坑清单6.1 高频问题速查表这里整理了一个速查表是我自己排查项目时常用的对照表。建议大家直接收藏遇到同类问题先查表比翻文档快。问题现象大概率原因排查工具/命令处理方案阴影锯齿/漏光Lightmass参数不当World Settings面板降低Static Lighting Level Scale补漏光面近距离贴图闪烁Z-fighting深度冲突拉近/拉远相机测试调Near Clip Plane或Pixel Depth Offset移动端贴图发白纹理压缩格式不匹配构建日志、设备Shader日志统一ASTC更换不受支持的材质节点角色卡进墙里Capsule碰撞体不匹配调试模式按P显示碰撞调整Capsule尺寸墙角加倒角物理物体乱蹦初始位置碰撞重叠延迟开启模拟生成时关Simulate Physics延迟一帧再开帧率低DrawCall过高stat RHI使用Instanced Static Mesh、合并Actor内存持续上涨动态资源持有强引用Memory Profiler清除引用或改用WeakObjectPtr动画不播放AnimBlueprint引用丢失检查资产引用关系重新编译蓝图重建引用打包后资源缺失资产未被打包器收录UnrealPak -List调整打包白名单检查Soft Reference这张表的排查顺序是按“从简单到复杂”排列的。比如阴影锯齿先查参数再补漏光面基本两步就能解决。物理物体乱蹦先延迟开启模拟无效再查物理材质和碰撞体形状。顺序错位最耽误时间。6.2 几条让我印象深刻的经验先说一个工具类的经验排查问题优先看Log而不是看弹窗。Unreal的弹窗提示往往只会显示一个笼统的错误码比如“Failed to load”但具体哪张贴图、哪个资产加载失败全部记录在Saved/Logs目录下的Log文件中。用-Log参数启动游戏可以输出更详细的运行时日志这个比什么排查工具都直接。另一个是关于版本升级的。有一次项目从4.27升到5.0大部分功能都正常但烘焙出来的光照有明显变化。排查到最后发现是Lightmass的计算参数和4.27不一致5.0开始默认提升了全局光照质量烘焙时间也增加了。升级之后务必做一次光照对比测试不要默认沿用老参数。最后是关于团队协作的。Unreal项目最大的特点是“一个资产被很多人引用”改一个公共资源的导入设置可能影响整个场景的渲染结果。后来我养成了一个习惯任何核心资源的修改先做备份再改参数最后跑一遍相关的功能测试再提交。这个习惯帮我拦下了好几次大事故。结尾这次先记录到这里。说实话整理这些记录的过程比当时解bug的过程更有价值。很多问题在当时看来是天大的坑事后回头看其实都能归到几个固定的类别里。我个人的一个习惯是每次解决完一个问题就在项目的Wiki里更新一条记录哪怕只有一句话也好。当一个团队积累了足够多这样的记录时“踩坑”就不再是重复劳动而是一种可以复用的经验库。之后如果再遇到有意思的问题我会持续更新。也建议大家养成记录的习惯不管是代码注释里的几句话还是单独建一个文档关键是把自己当时的排查思路写下来。下次遇到相似问题时你可能会感谢现在这个愿意多写两行的自己。