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 目錄本身也被清理了： 那就沒有可複製的源了，重新下載插件包解壓覆蓋即可恢復。

插件版本與引擎版本
數據格式與大致規模
出問題那次運行的完整日誌文件，不要過濾、不要只截報錯那幾行
復現步驟
顯卡型號與驅動版本

日誌文件位置與其他細節見日誌與診斷。