UE5 3DGS 常见故障按现象排查

本页按你看到的现象组织，每条给出可能原因、确认方法与解决办法。

查看日志、使用调试工具的方法见日志与诊断。咨询类问题（支持什么格式、两条管线的区别）见常见问题。

分类	涵盖现象
先做这两步	任何问题都建议先走一遍
数据加载失败	点了 Load 没反应、打包后看不到、蓝图工程打包、GIS 位置不对、大数据闪退
画面不显示或显示不全	完全看不到、远处缺失、边缘空洞、SceneCapture 空白、被水面遮挡
画面质量问题	拖影、闪烁、孔洞、颜色发灰、接缝、场景中有一道线
光照异常	过曝、没有形体明暗、ProxyMesh 不生效、阴影被截断、特效被盖住
参数改了没效果	勾选框未勾、全量加载、裁剪剖切、球谐、授权配额
性能问题	帧率低、显存高、加载卡顿、遮挡关系错误
碰撞与寻路	射线打不中、角色坠落穿模、NavMesh 不生成
崩溃	ArraySliceIndex 断言错误
授权问题	Status 不是绿勾、各类授权报错
编译与打包	缺少二进制、缺少预编译清单、打包失败、Android
还是没解决	提交问题前该收集什么

先做这两步

大部分问题在这两步之内就能定位，遇到任何现象都建议先走一遍。

打开 Output Log 看插件日志。 加载失败、路径错误、授权问题都会在这里留下明确信息。方法见查看插件日志。
确认数据加载成功。 选中 Actor，看 Details 面板里的 MetaInfo 是否有内容（Total Splats 大于 0）。为空说明数据没进来，直接跳到数据加载失败。

数据加载失败

现象：点了 Load 但什么都没出现

按顺序检查：

可能原因	确认方法	解决
路径不存在或拼错	日志出现 `LCC file :<路径> does not exist.`	核对路径。相对路径以 `Content` 为基准
LCC1 数据缺文件	日志出现 `Load Meta.lcc error` 或 `meta.lcc file :<路径> load error`	`.lcc` 同目录必须有 `data.bin` 与 `index.bin`，缺一个就失败
用错了 Actor	无明确报错，但画面空白	`.lcc2` 用 `ALCC2Actor`，`.lcc` 用 `ALCCActor`，单文件格式各有专用 Actor。见常见问题
格式不支持	日志出现 `LCC4Unreal do not support this file format!`	确认扩展名在支持范围内，见介绍
`.ply` 不是 3DGS 格式	日志提示 PLY 被拒绝	插件只支持含 3DGS 属性的 `.ply`，普通几何点云无法加载

现象：编辑器里正常，打包后看不到

按顺序检查两件事。

一、是不是用了绝对路径。 绝对路径只在本机有效，换机器后路径不存在。改为相对路径，相对项目 Content 目录，例如 Scenes/Tower/meta.lcc2。

二、数据目录有没有配进打包设置。 两个设置项用途不同，按需要选：

设置项	用途
`Additional Non-Asset Directories To Copy`	数据以普通文件形式复制到打包产物里
`Additional Non-Asset Directories To Package`	数据打进 pak 包

需要把 LCC 数据打进 pak 时用后者，只要求数据跟着打包产物一起分发用前者。两个都在 ProjectSettings > Packaging 下。

配好后重新打包，并检查打包产物里数据是否真的在。详细配置见快速入门。

现象：蓝图工程打包后插件不工作

蓝图工程（Blueprint-only）只支持在编辑器中使用，不支持打包。需要打包时必须用 C++ 工程。

现象：地理坐标位置不对，GIS 模式没生效

检查这几项：

数据是否含 RTK 信息。用 GetMetaInfo().IsRTK() 判断，日志出现 This lcc does not have RTK information! 说明数据不含地理信息
用代码开启时要调 SetGeoPlacement(true)，它会自动重新加载使设置生效。直接给 bEnableGeoPlace 赋值不会触发重载
位置有偏差时用 GeoLocationOffset 微调

与 Cesium 配合的搭建步骤见第三方与引擎插件集成。

现象：加载超大 LCC2 数据时漫游闪退

如果用的是 v1.0.0，这是该版本的已知缺陷（GPU Buffer 超限）。升级到 v2.x 及以上版本即可。

现象：加载大体积 PLY 报数组相关错误

v3.0.0 的已知缺陷，v3.3.0 及以上已修复，升级版本即可。

另外 PLY 不含球谐时，文件超过 2GB 可能无法加载，建议转成 LCC2 格式。

画面不显示或显示不全

现象：Actor 在场景里，但完全看不到内容

可能原因	确认方法	解决
数据没加载成功	见上一节	先解决加载问题
`LoadMode` 设成了 `None`	查看 Details 面板	改回 `Both`
摄像机在渲染距离之外	靠近场景看是否出现	调大 Max Distance
裁剪体把内容裁掉了	临时把裁剪体的 `bEnabled` 关掉	检查裁剪模式，`Inside` 与 `Outside` 效果相反，见 EClipType
剖切面把内容切掉了	临时关掉剖切面	检查 `Mode` 与平面朝向，见 ESectionType
`GlobalAlpha` 为 0	查看 Details 面板	改回 1.0
全在环境数据里但设了 `OnlyMain`	切换 `LoadMode` 对比	按数据实际情况选择，见 ELoadMode

现象：远处内容缺失，靠近才出现

这是 LOD 与距离限制的正常表现，不是故障。想让远处也显示：

调大 Max Distance，代价是性能下降
调小 Level Factor，让同样距离下用更高精度
配合雾效可以掩盖距离边界

现象：快速转动视角时屏幕边缘出现空洞

节点预加载跟不上视角变化。LCC 管线可以开启 Add Extra Preload Nodes，它会追加额外的预加载节点，代价是需要渲染的节点变多。

现象：SceneCapture 或小地图里是空白

需要先在项目设置里开启 SceneCaptureComponent Support。这一项默认关闭，且有轻微性能代价。

用代码为 SceneCapture 单独设置渲染策略见 SetSceneCaptureRenderMode，注意这组接口只在 LCC 管线上有效。

现象：3DGS 被水面遮挡

单层水材质的深度处理导致。开启 SingleLayerWater Support，见单层水支持。

画面质量问题

现象：移动时有拖影、残影

抗锯齿方法造成的。TSR 与 TAA 依赖历史帧做时域累积，3DGS 移动时容易残留上一帧画面。

依次尝试，找画质与拖影的平衡点：

None → FXAA → MSAA → TAA → TSR

场景中只有 3DGS 时可以直接设为 None，既没有拖影，也省下抗锯齿开销。各管线默认值与设置位置见性能参数说明。

现象：画面闪烁、边缘跳动

按收益排序尝试：

检查抗锯齿方法。这是最常见的原因，LCC2 管线推荐 TSR，见性能参数说明。
LCC 管线：调低 Sort Factor 提高排序频率。排序频率过低时，半透明的前后关系每隔几帧才更新一次，表现为画面轻微跳动。
检查 Small Splat Threshold，值过大会让远景发颗粒感。
摄像机推拉过程中细密结构闪烁，可以试开 Mip Filter，它会做一次带不透明度补偿的低通滤波，不同缩放下更稳定。.ply / .spz / .sog 默认关闭这一项。

现象：画面有孔洞、稀疏

SplatScale 调得过小。默认 1.0 是上限，调小虽然能降低 Overdraw 提升帧率，但面片变小后会露出空隙。往回调大一些。

现象：颜色发灰、发平

用调色参数处理，见画面调节。常见做法是略微提高 Contrast，或用 Gamma 提亮暗部。代码接口见 Color Adjustment。

现象：画面接缝明显（LCC 管线）

LCC 文件版本 5.0 及以上会自动处理接缝。旧版本数据可手动开启接缝裁切，对应属性 bEnableSeamCutting。

现象：场景中出现一道线

检查 Actor 的缩放。LCC 系列 Actor（ALCCActor、ALCC2Actor、ASogActor、ASpzActor、APlyActor）只支持等比缩放。

不要用这类非等比缩放：

带负值的，例如 (-1, 1, 1)
各轴不相等的，例如 (2, 1, 3)

三个轴必须保持一致，例如 (1, 1, 1) 或 (2, 2, 2)。非等比缩放会导致渲染异常，画面上表现为一道线。

光照异常

现象：切到 Lit 后画面过曝

采集数据的颜色里已经烘进了拍摄现场的光照，场景光会在此基础上再叠一层。

LCC2 管线：用 LightingScale 压低原始亮度，见法线与光照
检查场景光照强度是否过高

现象：Lit 模式下没有形体明暗，画面很平

这是预期行为。3DGS 数据没有几何法线，Fixed、ViewFacing、Hemispherical 这三种模式都是用近似手段构造法线，只能产生整体亮度变化，都无法产生随形体起伏的明暗。各模式定义见 ELCC2NormalGenerationMode。

想要真实的形体明暗，只有 ProxyMesh 一种模式能做到，需要制作并摆放代理网格，且需要授权。见代理网格与法线与光照。

三种近似模式之间的区别在于整体亮度如何随光照与视角变化，不在于有没有形体明暗：

Fixed：整片共用一个固定法线，摄像机移动时完全稳定
ViewFacing：法线跟随摄像机，转视角时整体亮度会变
Hemispherical：法线由屏幕位置映射到固定半球，方向光旋转时整体亮度过渡比前两者平滑

现象：ProxyMesh 模式设置了但没效果

检查项	确认方法
NormalMode 是否为 ProxyMesh	查看 Details 面板
授权是否有效	看插件面板的 Status，绿色勾表示授权正常。代码里也可以调 `GetEffectiveNormalGenerationMode()`，返回 `Fixed` 说明被降级了
代理网格是否有 StaticMesh	日志出现 `has a null StaticMesh` 警告
代理网格是否与 3DGS 空间重叠	配对靠位置判断，不重叠则不生效

详见代理网格。

现象：明暗出现在错误的位置

代理网格与 3DGS 实际表面偏差过大。要么改进代理网格的贴合度，要么改用近似法线模式，后者虽然没有形体明暗但更稳定。

现象：ProxyMesh 的阴影只在近处出现，远了就没了

阴影被距离截断，这是引擎自身的问题，不是插件的缺陷。

解决办法：选中 ProxyMesh Actor，把 Far Shadow（远距离阴影）关闭再重新打开，阴影即可恢复完整。属性在 StaticMeshComponent 的 Lighting 分类下。

现象：Lit 模式下出现巨大的异常阴影

近似法线模式在某些光照角度下会产生异常。依次尝试：

切换 NormalMode 看哪种模式表现正常
调整方向光的角度
改用 ProxyMesh 模式，配一个贴合的代理网格，这是效果最好的方案

现象：开了阴影后颜色变了

这是预期行为。3DGS 接受外部光照后颜色会随光源变化，调节方向光的颜色与强度即可。

现象：亮度调不动、场景整体偏暗

如果项目里用了 Composure 之类的合成插件，需要关闭 Component 上的后处理相关选项，改用 Post Process Volume 控制曝光。

曝光相关设置见画面调节。

现象：Niagara 特效在 3DGS 上看不见

LCC2 管线输出深度，特效的遮挡关系是正确的，正常不会出现这个问题。

只有 LCC 管线（.lcc 数据）可能遇到，因为它不输出深度，半透明的前后关系需要靠排序优先级决定。解决办法是把 Niagara System 的 Translucent Sort Priority 调到更高的值，让它渲染在 3DGS 之上。

现象：场景外围有杂乱内容

那是环境数据。把 LoadMode 从 Both 改成 OnlyMain，只渲染主体。

现象：切换光照模式没反应

点云模式下 SetLightMode 无效，会跳过赋值并输出警告日志。先切回 3DGS 模式。

现象：切到 Lit 模式后没有任何光照效果

前向渲染管线（Forward Shading）缺少 GBuffer，无法使用重光照。LightMode 设为 Lit 不会产生效果。

切换到延迟渲染管线（Deferred Shading）即可正常使用 Lit 模式。在 Project Settings > Rendering > Forward Shading 中取消勾选。注意 UE 的 VR 模板默认开启了 Forward Shading，使用该模板时需要手动关闭。

参数改了没效果

现象：改了 Performance 里的数值但没变化

每个参数左侧都有一个勾选框，未勾选时使用插件内置默认值，你填的数值不生效。 这是最常见的一个坑。

各参数的内置默认值见性能参数说明。

现象：改了全量加载参数没变化

Use Full Load 与 Full Load Splat Number 在加载时判定，改完需要重新加载数据才生效。

两种加载方式的区别见渲染。

现象：运行时改了裁剪体或剖切面的属性没反应

bEnabled、Mode、VolumeType 这些属性没有 Setter，运行时赋值后必须调用该 Actor 的 Refresh()。运行时改变换（位置、旋转）也一样。

编辑器里在细节面板改属性会自动更新，不需要手动调。

详见 ALCCClippingVolume。

现象：开了球谐但画面没变化

数据可能是 Portable 类型，本身不含球谐。用 CanSetShcoef() 确认，类型定义见 EFileType
点云模式下 SetUseShcoef 静默无效，先切回 3DGS
LCC2 可以只关掉球谐，通过 SetUseShcoef

现象：裁剪体加了很多但只有一部分生效

免费版每类限制 50 个。日志里会有明确提示：Unlicensed: enabled clipping volumes limited to 50 ...。授权说明见版本与授权。

性能问题

帧率低的完整调优流程见性能优化指南，这里只列快速判断。

现象：帧率低

先确认瓶颈是不是 3DGS。用 stat unit 看 Game / Draw / GPU 三项，再用 stat XGrids 看 LCC 自身耗时。如果 LCC 耗时占比不高，问题在场景其他部分（光照、后处理、蓝图逻辑），调 LCC 参数不会有改善。

确认是 3DGS 造成的话，按收益排序调整：

增大 Level Factor（收益最明显）
减小 Max Distance
减小 Max Splat Num
上调 Start Level 跳过最精细层级
关闭球谐
必要时切到点云模式

现象：显存占用过高

增大 Level Factor
减小 Max Splat Num
LCC2 管线调整 LCC2 GPU Memory Budget
调整 Max GPU Usage Percetage For Free 释放阈值

显存的分配规则与自动释放机制见渲染。单文件格式（.sog / .spz / .ply）会一次性全量加载，显存占用恒定不随视角变化，见单文件格式的加载上限。

现象：加载时卡顿

首次开启碰撞会有一次烘焙开销，尽量在加载阶段就开好，别在玩家操作过程中临时开
减小 Max Load Collision Distance，只加载需要的范围
调整线程配置，见性能参数说明

现象：多个 3DGS 互相穿插时遮挡关系错误

LCC 管线：开启多 Actor 半透排序
LCC2 管线：调整深度阈值改变深度写入位置

碰撞与寻路

现象：射线打不中 3DGS

检查项	处理
数据是否含碰撞	单文件格式不含碰撞数据，见前置条件
碰撞是否已开启	勾选 `bEnableCollision`，见开启
碰撞是否已加载到该位置	用 `ShowCollision()` 看线框，见碰撞可视化
检测距离是否超出碰撞加载范围	调大 Max Load Collision Distance

日志出现 There is neither collision.bin nor collision.lci in the folder 说明数据目录下没有碰撞文件。

LCC1 另有一组针对点云位置的射线检测接口，但未经充分测试，建议优先用碰撞加引擎射线检测，见 ULCCComponent Raycast。

现象：角色一开始就往下坠落

碰撞是动态分块加载的，游戏刚开始时碰撞数据可能还没构建完成，此时角色脚下没有碰撞就会掉下去。

处理办法：

把 PlayerStart 放在距地面稍高的位置
或者延迟几秒再允许角色移动
尽量在加载阶段就开启碰撞，别等玩家开始操作了再开

现象：角色穿模、走到一定距离外就掉下去

碰撞按距离流式加载，超出加载范围的地方没有碰撞体。调大 Max Load Collision Distance(m) 覆盖角色的活动范围。

角色移动过快也可能出现碰撞跟不上的情况，同样靠调大加载距离缓解。

现象：NavMesh 完全不生成

检查项	处理
数据不含碰撞	确认使用 `.lcc` 或 `.lcc2`，单文件格式无碰撞数据
碰撞未启用	勾选 `bEnableCollision`，并确认 `CanEverAffectNavigation = true`
碰撞尚未加载完成	视图模式选择玩家碰撞或可视性碰撞，确认目标区域已出现碰撞体
碰撞加载范围不足	调大 `Max Load Collision Distance(m)` 覆盖整个 AI 活动区域
NavMeshBoundsVolume 缺失或未覆盖	放置并缩放至覆盖目标区域
未重新构建导航	执行 `Build → Build Paths` 并保存关卡

完整流程见寻路系统支持。

崩溃

现象：报 ArraySliceIndex 断言错误后崩溃

报错形如：

Assertion failed: ArraySliceIndex >= 0

原因是当前版本不支持 Substrate 的 Adaptive GBuffer 格式。

解决办法：

打开 ProjectSettings > Rendering，找到 Substrate GBuffer Format (Project)。
把值改为 BlendableGBuffer。这是引擎的默认值。
重启引擎。

AdaptiveGBuffer 是已知不兼容的格式，BlendableGBuffer 可正常工作。

授权问题

先看插件面板的 Status，绿色勾表示授权正常，此时专业版功能可用。不是绿色勾就说明授权没生效，再看日志确认原因。

日志里的授权相关信息都比较明确，按提示处理：

日志信息	含义与处理
`ProjectID is invalid; generate one in Project Settings`	工程没有 Project ID。在 `Project Settings > Project > Description` 里生成
`Failed to decode AppKey, please check.`	AppKey 内容不完整或复制出错，重新复制
`Invalid AppKey, please check.`	AppKey 格式不对，确认是从开发者平台获取的完整字符串
`Authorization has expired, please check.`	授权已过期，在开发者平台重新生成
`AppKey has expired. Please generate a new one.`	同上
`HTTP request failed` / `HTTP error! Status: <code>`	网络问题或无法访问授权服务器，检查网络与防火墙
`Signature Verification Failed`	签名校验失败，联系技术支持

授权流程见版本与授权。

编译与打包

现象：缺少二进制文件或模块编译失败

出现下面任一报错时，按本节的步骤重新生成并编译工程：

Missing UnrealGame binary. You may have to build the UE project with your IDE.
Alternatively, build using UnrealBuildTool with the commandline:
UnrealGame <Platform> <Configuration>

*** could not be compiled. Try rebuilding from source manually

原因是 C++ 工程加入插件后，引擎检测到新模块但缺少对应的编译产物。按以下步骤处理：

关闭工程。
找到工程对应的 *.uproject 文件。
右键 *.uproject，在菜单中选择 Generate Visual Studio project files。
等待 VS 工程重新生成完毕。
双击 *.sln 打开 Visual Studio。
在解决方案资源管理器中右键工程，选择 Set as Startup Project，确保它是启动项目。
确认项目配置为 Development Editor 与 Win64。
点击 Debug > Start Without Debugging 启动项目。
编译通过后即可正常进入工程。之后直接双击 *.uproject 打开即可，不需要每次都走这个流程。

如果上述步骤后仍然失败，先删除工程的 Intermediate 目录，再从第 3 步重新执行一遍。

插件安装步骤见快速入门。

现象：打包失败

先检查这三项：

ProjectSettings > Packaging 下的 Full Rebuild 必须保持关闭，同时不要在 VS 里执行 Rebuild。插件不支持这两种方式，见快速入门
确认用的是 C++ 工程，蓝图工程无法打包
确认引擎版本在支持范围内（UE 5.4 ~ 5.8）

具体报错见下面两节。

现象：打包时报缺少预编译清单

报错形如：

Missing precompiled manifest for 'LCC4UnrealRuntime',
'\Shipping\LCC4UnrealRuntime\LCC4UnrealRuntime.precompiled'.
This module was most likely not flagged for being included in a precompiled build
- set 'PrecompileForTargets = PrecompileTargetsType.Any;' in LCC4UnrealRuntime.build.cs
to override. If part of a plugin, also check if its 'Type' is correct.

为什么会发生： 报错提到的这些文件本来就随插件一起分发，位于插件的 Intermediate 目录下。执行 ProjectSettings > Packaging 的 Full Rebuild、或在 VS 里执行 Rebuild 时，引擎会清理 Intermediate 目录，把这些预编译产物一起删掉。

LCC4Unreal 是二进制插件，不包含源码，删掉的产物无法重新编译生成，只能从插件包里恢复。所以这两个操作要避免使用。

怎么修复：

确认 ProjectSettings > Packaging 下的 Full Rebuild 处于关闭状态，且不要在 VS 里执行 Rebuild。
把插件的 lcc4unreal/Intermediate/Build/Win64/UnrealGame 目录内容，复制到工程的 <工程目录>/Intermediate/Build/Win64/<工程名> 目录下。
把插件的 lcc4unreal/Intermediate/Build/Win64/x64 目录内容，复制到工程的 <工程目录>/Intermediate/Build/Win64/x64 目录下。
重启引擎后重新打包。

第 2 步的目标目录名是工程名，不是 UnrealGame。例如工程叫 MyProject，目标路径就是 MyProject/Intermediate/Build/Win64/MyProject。

如果报错指向其他文件： 上面两个目录覆盖了常见情况。报错里提到别的文件时，按同样思路处理，在插件的 Intermediate 目录下按相同的相对路径找到该文件，复制到工程对应位置即可。

如果插件的 Intermediate 目录本身也被清理了： 那就没有可复制的源了，重新下载插件包解压覆盖即可恢复。

插件版本与引擎版本
数据格式与大致规模
出问题那次运行的完整日志文件，不要过滤、不要只截报错那几行
复现步骤
显卡型号与驱动版本

日志文件位置与其他细节见日志与诊断。