UE5.8 数据验证与资产规范：把提交前的低级错误挡在 CI 门外

周五晚上九点，小林把刚做完的一批武器资产提交到 Perforce。他本地验证过，模型能正常导入，材质也没报错。十分钟后，CI 邮件来了：构建失败，错误清单足足三十七条。老周打开日志，看到 SM_Rifle_Laser_01 被命名成 SM_Rifle_Laser_01_1，一张 4K 贴图没开压缩，三个 Static Mesh 的 LOD 1 屏幕尺寸写成了 0.0，还有一个 Material Instance 的父材质指向了临时目录里的 M_Debug_Red。

这些错误没有一个会让编辑器崩溃。单独看，每条都像小毛病。合在一起，它们足以让包体多出一百多兆，低端机帧率掉五帧，策划在装备栏里找不到正确的武器图标。数据验证和资产规范要做的，就是在这些小毛病溜进版本库之前把它们抓住。

UE5.8 提供了 Data Validation 系统、Editor Utility Widget、Python 脚本、Cook 验证等多种工具。把它们串成一条提交前检查链，配合一份清晰的团队规范，就能把大部分低级错误挡在构建阶段之外。本文按我们项目里实际推进的顺序，把这条链路拆成八个部分讲清楚。

1. 资产命名规范

命名规范听起来枯燥。可真到项目中期，打开 Content Browser 看到 T_Rifle_01、T_rifle_01、T_Rifle_01_new、T_Rifle_01_new_new 同时存在时，你会理解老周为什么在黑板上写命名即接口。命名不规范的直接后果是：搜索不到、脚本批量处理失败、材质引用容易断、跨模块合并时冲突频发。

我们的规范基于 Epic 推荐的前缀体系，同时按项目类型做了细化。核心规则只有三条：

• 每个资产文件必须带类型前缀；
• 名称主体用 PascalCase，语义清晰；
• 版本号用两位数字，禁止在文件名里出现 _final、_new、_old 这类时间戳后缀。

具体前缀表如下：

资产类型	前缀	示例
Static Mesh	SM_	SM_Rifle_Laser_01
Skeletal Mesh	SK_	SK_Hero_Winter_01
Texture	T_	T_Rifle_Laser_Diffuse_01
Material	M_	M_Rifle_Laser_Master
Material Instance	MI_	MI_Rifle_Laser_01
Blueprint	BP_	BP_WeaponSelectWidget
Sound Cue	SC_	SC_Rifle_Fire_01
Particle System	PS_	PS_Rifle_Muzzle_01
Data Table	DT_	DT_WeaponStats
Curve Table	CT_	CT_DamageFalloff

有了前缀，脚本才能快速按类型过滤。比如要检查所有 Static Mesh 的 LOD，只需要遍历 /Game/Weapons 下 SM_ 开头的 UStaticMesh。

命名里还有一个常见坑：下划线的语义。我们用下划线做层级分隔，用连字符做单词分隔。例如 T_Rifle_Laser-Diffuse_01 表示武器、激光步枪、漫反射贴图、版本 01。把层级和单词混在一起，搜索时很难用通配符匹配。

下面这张图展示了命名规范如何串联资产类型、目录和引用关系。

graph LR
    A[SM_Rifle_Laser_01] --> B[MI_Rifle_Laser_01]
    B --> C[M_Rifle_Laser_Master]
    C --> D[T_Rifle_Laser_Diffuse_01]
    C --> E[T_Rifle_Laser_Normal_01]
    E --> F[/Game/Weapons/Rifle/Laser/Textures]
    A --> F
    B --> G[/Game/Weapons/Rifle/Laser/Materials]

图的左边是模型，中间是材质实例，右边是父材质和贴图，底部是目录路径。名称前缀一致时，脚本可以顺着命名规则快速定位依赖。命名乱了，这条链就断了。

我们还在 CI 里加了一条硬规则：任何文件名中出现 _final、_new、_old、_v1、_v2 等字样，直接报错。因为历史经验告诉我们，这种文件名意味着作者自己也不确定哪个是正式版。

2. 目录结构规范

目录结构是命名的延伸。UE5 的 Content Browser 默认按文件夹组织，如果文件夹和命名规范不一致，查找资产会变成体力活。我们在 /Game 下按玩法模块划分一级目录，再按资产类型划分二级目录。

/Game
  /Characters
    /Hero
      /Meshes
      /Materials
      /Textures
      /Animations
    /Enemy
  /Weapons
    /Rifle
      /Laser
        /Meshes
        /Materials
        /Textures
        /Sounds
      /Plasma
  /Maps
    /Campaign
    /Multiplayer
  /UI
    /Widgets
    /Icons
    /Fonts
  /Core
    /Materials
    /Blueprints
    /Data

一级目录对应玩法模块：角色、武器、地图、UI、核心。二级目录按资产类型细分。每个资产目录下再放版本号或变体，而不是用文件名表达变体。这样做有几个好处：

• 打包时可以按目录做 Chunk 分配；
• 美术找资源时不需要记复杂前缀；
• Python 脚本按路径批量扫描更稳定。

目录结构里最容易被忽略的是共享资产的位置。比如一套通用 UI 材质、一个角色共用的基础骨骼、几张所有武器都能用的贴图。如果这些东西散落在各个模块目录里，Cook 时很容易出现重复打包。我们把共享资产统一放到 /Game/Core 下，其他模块通过软引用访问。

规范还要求：禁止在 /Game 根目录直接放资产文件。根目录只保留文件夹。这条规则看起来很严，但能有效防止临时文件随手一放就忘了的情况。小林那次提交失败的 M_Debug_Red 就是有人把临时材质存在了 /Game/Debug 目录下，然后被正式材质实例引用进去了。

3. 自定义 Data Validation 规则

UE5.8 的 Data Validation 系统挂在 UAssetValidationSubsystem 下，允许你给特定资产类写验证规则。验证失败时，编辑器会在 Content Browser 里给资产打黄色警告，也可以配置为 Cook 阶段报错。

Data Validation 的核心是继承 UEditorValidatorBase 并实现 CanValidateAsset 和 ValidateLoadedAsset。比如我们要检查所有 Static Mesh 必须有至少两个 LOD，可以写这样一个验证器。

#include "EditorValidatorBase.h"
#include "Engine/StaticMesh.h"

UCLASS()
class UStaticMeshLODValidator : public UEditorValidatorBase
{
    GENERATED_BODY()
public:
    virtual bool CanValidateAsset_Implementation(UObject* InAsset) const override
    {
        return InAsset->IsA<UStaticMesh>();
    }

    virtual EDataValidationResult ValidateLoadedAsset_Implementation(
        UObject* InAsset, TArray<FText>& ValidationErrors) override
    {
        UStaticMesh* Mesh = Cast<UStaticMesh>(InAsset);
        if (!Mesh) return EDataValidationResult::NotValidated;
        if (Mesh->GetNumLODs() < 2)
        {
            ValidationErrors.Add(FText::FromString(
                TEXT("Static Mesh 至少需要 2 个 LOD")));
            return EDataValidationResult::Invalid;
        }
        return EDataValidationResult::Valid;
    }
};

这个验证器只关注 Static Mesh 的 LOD 数量。实际项目里，我们还会检查 LOD 的屏幕尺寸是否递减、LOD 0 的三角形数是否超过阈值、是否有碰撞体、Lightmap UV 是否正确展开。

Data Validation 也可以做成蓝图友好的形式。UE5.8 支持在 UAssetValidationSubsystem 中注册基于蓝图的验证规则，让策划和美术也能参与定义。比如数据表 DT_WeaponStats 里的每一行都必须有非零伤害、射速和弹匣容量。验证失败时直接在编辑器里弹出具体行号，而不是等运行时才发现武器打不出伤害。

下面用一张架构图展示 Data Validation 在编辑器、Cook 和 CI 三层中的位置。

flowchart TD
    subgraph editor ["UE5.8 Editor"]
        dv["Data Validation Subsystem"]
        eu["Editor Utility Widget"]
        py["Python Scripting"]
    end
    subgraph rules ["Validation Rules"]
        naming["Naming Rule"]
        lod["LOD Rule"]
        tex["Texture Rule"]
        mat["Material Rule"]
    end
    subgraph pipeline ["Pipeline"]
        cook["Cook Validation"]
        ci["CI Pre-commit Hook"]
        report["Report Service"]
    end
    dv --> naming
    dv --> lod
    dv --> tex
    dv --> mat
    eu --> naming
    py --> tex
    cook --> report
    ci --> report

编辑器层发起验证请求，规则层存放具体的命名、LOD、贴图、材质规则，流水线层在 Cook 和 CI 中复用同一批规则，并把结果汇总到报告服务。这样就不会出现本地不报错、CI 却报错的规则不一致问题。

4. Editor Utility / Python 检查脚本

Data Validation 适合规则明确、能在加载资产时完成的检查。但有些检查涉及跨资产引用、目录结构、命名一致性，用 Python 或 Editor Utility Widget 更方便。

UE5.8 内置了 Python 编辑器脚本插件。启用 PythonEditorScriptPlugin 后，可以通过 unreal 模块遍历资产、读取属性、批量修复。比如我们写了一个检查贴图尺寸的脚本：

import unreal

def check_texture_size(max_size=2048):
    issues = []
    textures = unreal.EditorAssetLibrary.list_assets("/Game")
    for path in textures:
        tex = unreal.EditorAssetLibrary.load_asset(path)
        if not isinstance(tex, unreal.Texture2D):
            continue
        w = tex.blueprint_get_size_x()
        h = tex.blueprint_get_size_y()
        if max(w, h) > max_size:
            issues.append(f"{path}: {w}x{h}")
    return issues

if __name__ == "__main__":
    problems = check_texture_size()
    for p in problems:
        print(p)

这个脚本只检查贴图是否超过 2048。小林那次失败的贴图就是一张 4096x4096 的法线贴图，美术同事为了展示细节直接导入了高清源文件，但忘了在引擎里限制最大尺寸。脚本跑出来后，我们可以在 Python 里直接调用 tex.set_max_texture_size(2048) 批量修复，也可以让美术手动处理。

Editor Utility Widget 更适合美术同学使用。我们在工具栏放了一个按钮，点击后执行一组预设检查，结果以表格形式展示在编辑器窗口里。表格里每行是一条问题资产，双击可以直接定位到 Content Browser。美术不需要看命令行，也能知道自己哪些资产不符合规范。

Python 脚本还能做命名规范的扫描。下面这段代码检查 /Game 下所有资产文件名是否符合前缀规则：

import unreal

PREFIX_RULES = {
    "StaticMesh": "SM_",
    "Texture2D": "T_",
    "Material": "M_",
    "MaterialInstanceConstant": "MI_",
    "Blueprint": "BP_",
}

def check_naming():
    issues = []
    for path in unreal.EditorAssetLibrary.list_assets("/Game"):
        asset = unreal.EditorAssetLibrary.load_asset(path)
        cls = asset.get_class().get_name()
        expected = PREFIX_RULES.get(cls)
        if not expected:
            continue
        name = asset.get_name()
        if not name.startswith(expected):
            issues.append(f"{path}: expected prefix {expected}")
    return issues

这段代码只有二十多行，却能拦住大部分命名错误。我们在 Editor Utility 里把它和贴图检查、LOD 检查组合成一个提交前自检按钮，要求美术在提交前必须点一次。

5. CI 集成与提交前检查

编辑器里的检查再好，也拦不住有人忘记点按钮。真正能把错误挡在版本库外面的，是 CI 里的提交前检查。

我们的 CI 流程分两条线：一条是 P4 的预提交触发，另一条是 nightly build 的全量扫描。预提交触发针对本次变更的资产，速度快；nightly build 检查全量资产，覆盖广。

下面这张图展示了提交前检查的完整流程。

flowchart TD
    A["美术提交资产"] --> B{触发预提交检查}
    B -->|"失败"| C["返回错误报告"]
    B -->|"通过"| D["允许提交"]
    C --> E["美术本地修复"]
    E --> F["重新提交"]
    F --> B
    D --> G["进入 nightly build"]
    G --> H{全量扫描}
    H -->|"失败"| I["生成告警工单"]
    H -->|"通过"| J["进入正式构建"]

预提交检查通常运行在安装了 UE5.8 的 CI Agent 上。我们用 UEditor-Cmd.exe 以 -run=ValidateAssets 的方式启动引擎，加载变更列表里的资产，执行 Data Validation 和 Python 脚本。命令大致如下：

UEditor-Cmd.exe "D:\Project\MyProject.uproject" \
  -run=ValidateAssets \
  -AssetPaths=/Game/Weapons/Rifle/Laser \
  -ReportOutput=D:\Build\validation_report.json \
  -stdout -unattended -nopause

这里用 UEditor-Cmd.exe 而不是普通编辑器，是因为 CI 环境没有 GUI。-unattended 和 -nopause 保证进程不会卡住。-ReportOutput 把结果输出成 JSON，方便后续解析和展示。

nightly build 则跑全量扫描。它会读取整个 /Game 目录，生成一份完整的资产健康报告。报告里包含命名违规数量、贴图超标数量、LOD 缺失数量、材质引用错误数量等核心指标。我们把这些指标画成趋势图，每周例会先看图再讨论。

CI 检查还有一个隐藏价值：它迫使规则必须写成可执行代码。口头规范很容易被遗忘，脚本规范不会。每次规则更新都要同步到三个地方：编辑器里的 Data Validation、Python 脚本、CI 配置文件。这一点后面讲团队协作时还会展开。

6. 贴图/模型/材质常见问题

小林的 CI 报告里，三十七条错误可以归为三类：贴图问题、模型问题、材质问题。每一类都有典型的踩坑模式。

贴图问题

最常犯的错误是尺寸超标和压缩格式错误。手机项目上，一张 4096x4096 的贴图在内存里可能占用 64MB。如果武器、角色、场景都随意使用 4K，包体很快就爆炸。

我们的规范规定：

• 角色主贴图最大 2048；
• 武器贴图最大 2048；
• UI 图标最大 512；
• 场景远景贴图最大 1024。

贴图内存可以用一个简单公式估算：

$M = W \times H \times C \times \frac{b}{8}$

其中 $W$ 和 $H$ 是贴图宽高，$C$ 是通道数，$b$ 是每个通道的位深。一张 2048x2048 的 RGBA8 贴图，$W=2048$，$H=2048$，$C=4$，$b=8$，代入公式得到 $M = 2048 \times 2048 \times 4 \times 1 = 16777216$ 字节，约 16MB。如果是 4096x4096，就是 64MB。把最大尺寸从 4K 降到 2K，单张贴图就能省 48MB。

压缩格式也很关键。法线贴图应该用 TC_Normalmap，灰度图应该用 TC_Grayscale，UI 贴图应该用 TC_EditorIcon 或 UserInterface2D。用错格式会导致画面精度下降或内存浪费。

模型问题

模型方面的问题主要集中在 LOD 和碰撞体。LOD 0 细节最高，LOD 1、LOD 2 依次递减。每个 LOD 都有 ScreenSize 属性，决定摄像机多远时切换。规范要求：

• 武器 Static Mesh 至少 3 个 LOD；
• LOD 1 的 ScreenSize 不应大于 LOD 0；
• LOD 2 的 ScreenSize 建议小于 0.25。

小林那次 LOD 1 的 ScreenSize 写成 0.0，意味着模型只要稍远一点就跳到最低面数，画面会突然跳变。验证脚本检查到 ScreenSize 序列非递减就会报错。

碰撞体方面，复杂模型不要直接用凸包分解做碰撞。车辆、建筑这种规则物体建议手调 UCX_ 前缀的碰撞网格。角色胶囊体碰撞用 UShapeComponent 就够了，不需要把角色网格做成可碰撞。

材质问题

材质问题主要是父材质引用错误和参数命名不一致。临时调试材质 M_Debug_Red 被正式材质实例引用，Cook 时会把它打进包体，颜色和参数都不对。我们的规范要求：正式资产不能引用 /Game/Debug、/Game/Temp、/Game/Sandbox 目录下的任何内容。

另一个常见问题是材质实例里的 Scalar Parameter 名字和父材质不一致。策划调了半天 Roughness，发现父材质里叫 RoughnessValue，参数根本传不进去。Data Validation 可以检查材质实例的所有参数是否在父材质里存在。

这三类问题用脚本覆盖后，CI 报告会变得非常具体。美术看到 T_Rifle_Laser_Normal_01 尺寸 4096x4096，超过 2048，比看到材质报错有用一百倍。

7. 报告与修复

检查只是手段，修复才是目的。如果报告不清晰，美术会忽略它；如果修复流程太复杂，团队会绕过它。我们在报告上做了三层设计：即时弹窗、CI 网页报告、工单系统。

编辑器内执行 Python 脚本或 Data Validation 时，结果直接显示在 Editor Utility Widget 的表格里。表格列包括：资产路径、问题类型、严重程度、建议修复方式、一键修复按钮。能自动修复的问题，比如重命名、设置 Max Texture Size、删除空材质节点，直接点按钮就行。

CI 里的报告输出成 JSON，再渲染成网页。网页报告按模块分组，每个模块显示通过率和问题列表。我们加了一个功能：把问题按责任人分组。资产路径里包含 /Game/Weapons/ 的问题分配给武器组，包含 /Game/Characters/ 的问题分配给角色组。这样各组打开报告只看自己的部分。

{
  "summary": {
    "total_assets": 1247,
    "failed_assets": 37,
    "critical": 5,
    "warning": 32
  },
  "issues": [
    {
      "asset": "/Game/Weapons/Rifle/Laser/Textures/T_Rifle_Laser_Normal_01",
      "type": "texture_size",
      "severity": "critical",
      "message": "尺寸 4096x4096，超过上限 2048",
      "owner": "weapons"
    },
    {
      "asset": "/Game/Weapons/Rifle/Laser/Meshes/SM_Rifle_Laser_01",
      "type": "lod_screensize",
      "severity": "warning",
      "message": "LOD 1 ScreenSize 为 0.0",
      "owner": "weapons"
    }
  ]
}

一键修复脚本我们也会分级别。安全修复可以自动执行，比如把 Max Texture Size 降到 2048、把 LOD ScreenSize 按默认值重新计算。危险修复必须人工确认，比如删除资产引用、重命名文件。我们不允许 CI 自动修改版本库里的资产，所有修复都在本地编辑器完成，再重新提交。

下面用序列图展示一次报告到修复的完整流程。

sequenceDiagram
    participant Artist as "美术"
    participant CI as "CI Agent"
    participant Report as "报告服务"
    participant Editor as "UE5.8 Editor"
    Artist->>CI: 提交变更列表
    CI->>CI: 执行 Data Validation + Python 检查
    CI->>Report: 上传 JSON 报告
    Report-->>Artist: 返回问题链接
    Artist->>Editor: 打开 Editor Utility Widget
    Editor->>Report: 拉取问题列表
    Artist->>Editor: 点击一键修复
    Editor-->>Artist: 本地验证通过
    Artist->>CI: 重新提交

这个流程的关键是反馈速度。预提交检查必须在五分钟内出结果，否则美术会关闭页面去干别的。我们把全量扫描拆成增量扫描和全量扫描两层，增量扫描只检查本次提交改动的资产，通常一两分钟就能跑完。

8. 团队协作流程

规范和技术都到位后，真正的挑战是让人愿意遵守。我们的经验是：规则要写成代码，责任要分到人，反馈要及时。

每周一早上，组长会把上周的 CI 报告截图发到群里。报告里违规数量最多的那个人，不是被批评，而是被要求在下一次站会花两分钟讲清楚自己遇到了什么坑。这种分享让规范变成团队的共同记忆，而不是贴在墙上的标语。

新人入职第一周，我们会安排一次资产规范工作坊。内容包括：怎么命名、目录怎么选、Editor Utility 自检按钮在哪、CI 报告怎么看。新人提交的第一批资产必须由老员工 review 通过。这个环节虽然耗时，但能避免新人把坏习惯带进项目。

规则更新也有流程。如果某个规则太严，导致大量误报，任何人都可以在项目文档里提修改建议。建议需要包含：规则当前行为、误报案例、建议修改方式、修改后的影响范围。规则变更由 TA 组长审批，审批通过后同步更新 Data Validation 代码、Python 脚本、CI 配置和团队文档。不同步更新这四个地方，就不允许合入。

我们还建立了一个例外清单。有些资产因为特殊原因必须违反规范，比如一张 4K 的主宣传图、一个单 LOD 的远景 billboard。例外清单需要填写资产路径、例外原因、有效期、审批人。CI 读到例外清单里的路径会跳过对应检查。这个机制防止规范变成僵化的枷锁，也留下审计痕迹。

最后放一张团队协作流程图。

flowchart LR
    A["制定规范"] --> B["编写验证代码"]
    B --> C["集成到 CI"]
    C --> D["本地 Editor Utility"]
    D --> E["提交前自检"]
    E --> F["CI 预提交检查"]
    F -->|"通过"| G["合入版本库"]
    F -->|"失败"| H["本地修复"]
    H --> E
    G --> I["nightly 全量扫描"]
    I --> J["周会 review 趋势"]

图的左边是规范制定和技术实施，右边是日常提交和持续 review。流程跑顺之后，团队会形成一种默契：提交前点一下自检，看到 CI 报告先修自己的问题，每周例会看一眼趋势图。命名、贴图、LOD、材质这些问题不会凭空消失，但它们会被尽早发现、尽早修复。

回到文章开头的那个周五晚上。小林那批武器资产经过三个小时的修复，最终合入了版本库。后来他把这次踩坑经历写进了新人培训文档，标题叫《三十七条 CI 错误教会我的事》。老周看到标题笑了笑，说下次争取只有十七条。

数据验证和资产规范并不是为了让谁多写几行代码。它们的作用是把那些看起来没问题的低级错误，变成还没提交就被发现的小问题。项目越大，这种预防的价值越明显。UE5.8 提供的工具已经足够把这件事做成自动化流水线，剩下的就是团队愿不愿意把规则当真。

小结

• 命名规范是后续所有自动化检查的基础，前缀、大小写、版本号都要固定。
• 目录结构按玩法模块和资产类型分层，共享资产集中到 /Game/Core。
• Data Validation 适合做资产加载后的规则校验，LOD、贴图、材质都可以覆盖。
• Python 和 Editor Utility Widget 适合做跨资产、跨目录的扫描和一键修复。
• CI 预提交检查是最后一道门，增量扫描保证速度，nightly 全量扫描保证覆盖。
• 报告要按责任人和严重程度分组，一键修复只处理安全操作。
• 团队协作靠规则代码化、新人培训、例外清单和每周趋势 review。

把这套东西跑起来，周五晚上的 CI 邮件会从三十七条变成两三条，最后变成零条。到了那个时候，你会发现最有价值的技术，往往不是某个炫酷的新功能，而是让错误在造成破坏之前就被拦住的流水线。