UE项目瘦身实战：自动化清理冗余资源与构建产物的完整方案-平芜编程栈

1. 项目概述：为什么UE项目会“发胖”？

如果你是一个Unreal Engine的深度用户，无论是独立开发者还是团队中的技术美术，大概率都经历过这样的场景：项目开发到中后期，每次打开编辑器都要等上好几分钟，硬盘空间像被黑洞吞噬一样飞速减少，一个看似普通的项目动辄占用几十甚至上百GB。更头疼的是，当你尝试打包（Package）项目时，漫长的等待后可能因为磁盘空间不足而失败。这一切的罪魁祸首，往往不是你的核心内容，而是项目中堆积如山的“冗余资源”。

所谓冗余资源，就像你家里那些“总觉得以后会用上”但实际上几年都没碰过的旧物。在UE项目中，它们主要包括：

未引用资产：在内容浏览器中静静地躺着，但没有任何关卡、蓝图、材质或数据表引用到它们。可能是早期迭代废弃的模型、测试用的音效、或者导入后忘记删除的临时文件。
派生缓存文件：UE为了加速编辑和预览，会为原始资源（如静态网格体、纹理）生成大量中间格式的缓存文件，例如DerivedDataCache（DDC）和Intermediate文件夹下的内容。这些文件体积庞大，且在项目迁移或引擎版本升级后可能失效。
旧版本备份：启用源代码控制（如Perforce、Git LFS）后，本地工作区可能会保留旧版本的文件副本。
平台特定的构建产物：为不同平台（Windows、Android等）构建后留下的Saved、Binaries、Build目录文件，尤其是开发（Development）配置的构建，包含大量调试符号，体积惊人。

手动清理这些资源是一项繁琐且高风险的工作。你需要小心翼翼地检查引用关系，避免误删关键资产；需要知道哪些缓存可以安全清除；还需要处理不同平台构建的残留。这个过程既耗时又容易出错。因此，一个自动化、智能化且安全的清理工具，就成了提升开发效率和维护项目健康的刚需。这正是“ProjectCleaner”这类工具诞生的背景——它不是一个简单的删除脚本，而是一个专为UE项目“瘦身健体”设计的综合解决方案。

2. 核心思路与工具选型：为什么是ProjectCleaner？

面对项目臃肿的问题，社区和官方都提供过一些方法，比如手动删除Saved、Intermediate文件夹，或者使用编辑器内置的“引用查看器”和“迁移工具”来辅助分析。但这些方法要么太粗暴（可能误删必要文件），要么太零散（效率低下）。

ProjectCleaner的设计思路，是提供一个集中、自动且可配置的清理流程。它的核心功能通常围绕以下几个模块构建：

资产依赖关系分析：这是清理的基石。工具需要深度扫描整个Content目录，构建一个资产引用关系图。通过这张图，可以准确识别出那些没有任何入度（即没有被任何其他资产引用）的“孤儿资产”。一个健壮的工具还会考虑间接引用，比如通过蓝图基类、数据表或游戏实例进行的引用。
多维度垃圾识别：除了未引用资产，工具还应能识别：
- 空文件夹：清理后残留的目录结构。
- 无效或损坏的资产：导入失败或引擎无法识别的文件。
- 特定类型的冗余文件：例如，仅用于编辑器预览的巨型纹理_UE4_Thumbnail，或者Shader编译产生的中间文件。
安全隔离与预览：直接删除是危险的。优秀的工具会提供一个“预览模式”，列出所有将被清理的项目，并允许用户手动排除某些资产。更好的做法是，先将资产移动到项目内的一个临时隔离区（如ToBeDeleted文件夹），确认项目运行无误后再行永久删除。
缓存与构建产物清理：提供选项，让用户选择清理DerivedDataCache、Intermediate、Saved下的特定子目录（如Cooked、Binaries），甚至包括Plugins文件夹下的中间文件。
与工作流集成：支持命令行调用，便于集成到CI/CD流水线中，在 nightly build 或发布前自动执行清理任务。

市面上有一些工具，如免费的“Asset Cleaner”插件，或一些开源脚本。但“ProjectCleaner”通常指代一类更集成、功能更全面的工具或自定义方案。在选型或自建时，你需要权衡：

准确性：依赖分析算法是否可靠？是否会误判系统关键资产（如GameInstance蓝图、项目设置引用的资产）？
安全性：是否有隔离和回滚机制？
性能：扫描大型项目（数万资产）的速度如何？
可配置性：能否自定义清理规则、忽略列表（如永远不想扫描的文件夹）？

基于这些考量，一个理想的ProjectCleaner实现，往往会结合UE提供的命令行工具（如AssetRegistry查询）和自定义的C++/Python脚本来实现深度扫描与处理。

3. 实战部署：构建你自己的ProjectCleaner工作流

下面，我将以一个结合了UE Editor Utility Widget（编辑器工具）和Python脚本的混合方案为例，拆解一个高可用ProjectCleaner的实现步骤。这个方案平衡了易用性、安全性和灵活性。

3.1 环境准备与项目设置

首先，你需要在UE项目中启用必要的模块和插件。

启用Python插件：Unreal Engine内置了Python支持，这是实现自动化脚本的关键。在编辑器菜单栏，点击“编辑” -> “插件”，在搜索框中输入“Python”，确保“Python Editor Script Plugin”和“Editor Scripting Utilities”已启用并重启编辑器。

创建工具目录：在你的项目目录下，创建一个清晰的结构来管理清理工具。例如：

YourProject/ ├── Content/ │ └── ... ├── Source/ │ └── ... └── Tools/ ├── ProjectCleaner/ │ ├── Python/ # 存放核心扫描逻辑的Python脚本 │ ├── Utilities/ # 存放Editor Utility Widget蓝图 │ └── Config/ # 存放忽略列表等配置文件 └── ...

编写核心Python扫描脚本：在Tools/ProjectCleaner/Python/下创建asset_scanner.py。这个脚本的核心是利用UE的Python API来获取资产注册表（Asset Registry）信息。

# asset_scanner.py import unreal import json import os from collections import defaultdict def find_unreferenced_assets(): """ 核心函数：查找未被任何其他资产引用的资产。 返回一个字典，包含未引用资产列表和引用关系数据。 """ print("开始扫描资产引用关系...") # 获取资产注册表子系统 asset_registry = unreal.AssetRegistryHelpers.get_asset_registry() # 获取所有资产数据（过滤掉引擎内容等） package_path = "/Game" # 扫描项目Content目录 asset_datas = asset_registry.get_assets_by_path(package_path, recursive=True) # 构建引用关系图 reference_graph = defaultdict(set) # key: 被引用资产, value: 引用它的资产集合 referencer_graph = defaultdict(set) # key: 引用资产, value: 它引用的资产集合 total_assets = len(asset_datas) print(f"共发现 {total_assets} 个资产，正在分析引用关系...") for i, asset_data in enumerate(asset_datas): if i % 1000 == 0: print(f"分析进度: {i}/{total_assets}") asset_package_name = asset_data.package_name # 获取该资产引用了哪些资产 references = asset_registry.get_referencers(asset_package_name, unreal.AssetRegistryDependencyOptions()) for ref in references: reference_graph[ref].add(asset_package_name) referencer_graph[asset_package_name].add(ref) # 找出未被任何资产引用的“根节点”（即入度为0的资产） unreferenced = [] for asset_data in asset_datas: asset_package_name = asset_data.package_name if asset_package_name not in reference_graph: # 注意：需要排除一些特殊资产，如默认地图、游戏实例等 if not _is_system_asset(asset_package_name): unreferenced.append(str(asset_package_name)) print(f"扫描完成。发现 {len(unreferenced)} 个未被引用的资产。") return { "unreferenced_assets": unreferenced, "total_scanned": total_assets } def _is_system_asset(package_name: str) -> bool: """判断一个资产是否为系统关键资产，不应被清理。""" system_keywords = [ "/Game/Maps/", # 默认地图可能被项目设置引用 "/Game/Blueprints/GameInstance", "/Game/Config/", # 你可以在这里添加更多需要忽略的路径模式 ] for keyword in system_keywords: if keyword in package_name: return True return False if __name__ == "__main__": # 当脚本独立运行时，执行扫描并输出结果到JSON文件 result = find_unreferenced_assets() output_path = os.path.join(os.path.dirname(__file__), "..", "Output", "unreferenced.json") os.makedirs(os.path.dirname(output_path), exist_ok=True) with open(output_path, 'w') as f: json.dump(result, f, indent=4) print(f"结果已保存至: {output_path}")

注意：直接使用get_referencers可能无法捕获所有类型的引用（例如通过C++代码硬编码的引用、项目设置中的默认地图）。在生产环境中，你可能需要结合多种方法，例如额外检查DefaultEngine.ini配置文件中的引用。

3.2 创建可视化清理工具（Editor Utility Widget）

为了让非程序员也能安全使用，我们创建一个简单的编辑器界面。

创建Editor Utility Widget：在内容浏览器中右键 ->“编辑器工具集” -> “编辑器工具集部件（Editor Utility Widget）”，命名为WBP_ProjectCleaner。
设计UI：打开这个Widget，拖入以下控件：
- 一个Button，文本为“开始扫描”，点击后调用Python脚本。
- 一个ListView或TreeView，用于显示扫描出的未引用资产列表。
- 每个列表项旁有一个CheckBox，用于选择是否清理该资产。
- 一个Button，文本为“移动到隔离区”，用于执行安全清理。
- 几个CheckBox选项：“清理空文件夹”、“清理DerivedDataCache”、“清理Intermediate目录”。
编写蓝图逻辑：
- “开始扫描”按钮：其点击事件中，使用“执行Python脚本”节点，调用我们上面写的asset_scanner.py。然后读取生成的unreferenced.json文件，将资产列表填充到ListView中。
- “移动到隔离区”按钮：其点击事件中，遍历所有被选中的资产，使用“复制资产”节点将它们复制到项目内一个预设的Content/ToBeDeleted/目录下，然后使用“删除资产”节点删除原始资产。务必先复制再删除，这是安全底线。
- 其他清理选项：对于“清理DDC”等，可以使用“执行控制台命令”节点，运行命令如r.cleardderiveddatacache（需确认命令可用性），或者直接调用Python的shutil.rmtree来删除Saved/DerivedDataCache目录（建议在编辑器关闭时进行）。

3.3 配置忽略列表与规则

在Tools/ProjectCleaner/Config/下创建ignore_list.json，让工具更智能。

{ "ignore_paths": [ "/Game/Art/Common/MasterMaterials/*", // 永远不要扫描的材质函数库 "/Game/Core/UI/Fonts/*", // 字体文件可能被动态加载 "/Game/Config/*" // 配置文件 ], "ignore_patterns": [ "*_BuiltData*", // 某些插件生成的数据 "*/Developers/*" // 开发者目录下的内容 ], "protected_asset_classes": [ "/Script/Engine.World", // 地图资产 "/Script/Engine.GameInstance" // 游戏实例蓝图 ] }

在你的Python扫描脚本中，在判断_is_system_asset函数时，加入对这个忽略列表的读取和匹配逻辑。

4. 深度清理：超越未引用资产

一个专业的ProjectCleaner不应止步于未引用资产。项目空间的“水分”还藏在其他地方。

4.1 清理派生数据缓存（DDC）与中间文件

DDC是UE性能的利器，但也是空间的杀手。它存储了针对你本地显卡驱动、引擎版本编译的Shader、网格体数据等。当你升级了显卡驱动或切换了开发设备，旧的DDC就可能失效。清理它们是安全的，但会导致下次打开项目时重新编译（耗时）。

手动/脚本清理：最简单的方法是关闭UE编辑器，直接删除项目目录下的Saved/DerivedDataCache文件夹。你也可以在Python脚本中添加如下函数：

import shutil def clean_derived_data_cache(project_path): ddc_path = os.path.join(project_path, "Saved", "DerivedDataCache") if os.path.exists(ddc_path): shutil.rmtree(ddc_path) print(f"已删除DDC: {ddc_path}") # 也可以清理Intermediate intermediate_path = os.path.join(project_path, "Intermediate") if os.path.exists(intermediate_path): shutil.rmtree(intermediate_path) print(f"已删除Intermediate: {intermediate_path}")

编辑器内命令：在编辑器输出日志（Output Log）中输入r.cleardderiveddatacache可以清理一部分DDC，但可能不彻底。

4.2 处理平台构建产物

为不同平台打包后，Saved目录下会生成Cooked、StagedBuilds等文件夹，Binaries和Build目录也会膨胀。

清理Cooked数据：Saved/Cooked/目录存放着针对特定平台的资源烹饪结果。如果你短期内不再需要为该平台打包，可以安全删除对应的子文件夹（如Saved/Cooked/Windows）。
清理构建中间文件：Binaries/和Build/目录下的.obj、.pdb等文件在重新构建时会再生。使用Visual Studio的“清理解决方案”功能，或直接删除这些文件夹（需要随后在IDE中重新生成项目文件），可以释放大量空间。

4.3 识别与处理重复资产

有时，同一个资源可能被以不同的名称或路径导入了多次。手动查找非常困难。你可以扩展Python脚本，通过计算资产的哈希值（如文件MD5）或比较其导入设置和源文件路径来识别重复项。UE的Python API可能不直接提供哈希，但你可以通过unreal.EditorAssetLibrary.get_metadata_tag获取一些唯一性标识进行初步比对，更精确的方法需要调用外部工具或读取文件二进制。

5. 集成到CI/CD与自动化流程

对于团队项目，将清理作为自动化流程的一部分至关重要。

创建批处理脚本：编写一个.bat（Windows）或.sh（Linux/macOS）脚本，按顺序执行清理任务。

@echo off REM cleanup_script.bat set PROJECT_PATH=D:\YourUnrealProject set UE_EDITOR="C:\Program Files\Epic Games\UE_5.3\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" echo Step 1: 运行Python脚本分析未引用资产（需在编辑器外运行） python %PROJECT_PATH%\Tools\ProjectCleaner\Python\asset_scanner.py echo Step 2: 使用UE命令行工具，运行一个特定的Editor Utility Widget（如果工具已集成到插件中） %UE_EDITOR% %PROJECT_PATH%\YourProject.uproject -run=WBP_ProjectCleaner.PerformCleanup -unattended -noshadercompile echo Step 3: 清理DDC和Intermediate（在编辑器关闭后进行） rmdir /s /q "%PROJECT_PATH%\Saved\DerivedDataCache" rmdir /s /q "%PROJECT_PATH%\Intermediate" echo 清理完成。 pause

在CI流水线中调用：在Jenkins、GitLab CI等工具的配置中，在构建步骤（Build）之前，添加一个“清理工作区”的步骤，调用上述脚本。确保此步骤配置在获取最新代码之后，这样每次构建都在一个“干净”的项目基础上进行，避免残留文件干扰。
版本控制忽略设置：确保你的.gitignore或Perforce忽略列表包含了不需要版本控制的文件，从源头上减少冗余文件被提交的可能。一个标准的UE项目.gitignore应包含：
```
# 编译生成文件 Binaries/ Build/ Intermediate/ Saved/ DerivedDataCache/ *.sln *.vcxproj *.vcxproj.filters # 平台特定文件 *.app *.ipa *.apk # 其他 .vs/ .idea/ *.opendb
```
实操心得：对于Saved文件夹，团队有时会选择性提交Saved/Config下的项目设置文件。因此，更精确的做法是忽略Saved下的其他子文件夹，如Saved/Cooked、Saved/StagedBuilds、Saved/Autosaves等，而保留Saved/Config。

6. 常见问题、排查与避坑指南

即使有了自动化工具，清理工作仍需谨慎。以下是我在实际操作中积累的一些经验和常见问题的解决方法。

6.1 资产误删与恢复

问题：工具错误地将一个正在使用的材质或蓝图判定为未引用，并将其删除，导致游戏运行时出现粉红错误（Missing Asset）。

排查与解决：

立即检查隔离区：如果你的工具设计了隔离区（Content/ToBeDeleted），第一时间去这里找回被误删的资产，直接拖回原位置即可。
检查引用分析逻辑：
- 软引用（Soft Reference）：你的扫描脚本是否正确处理了软引用？软引用（如通过SoftObjectPtr或资产路径字符串加载）在资产注册表中可能不会显示为硬依赖。你需要额外解析资产文件（如蓝图的文本源文件*.asset）来查找字符串形式的路径引用。这大大增加了复杂度，也是许多简单清理工具不准确的原因。
- 代码中的引用：C++代码中通过ConstructorHelpers::FObjectFinder或FSoftObjectPath加载的资产，不会被资产注册表捕获。这部分需要人工审计代码，并将这些资产路径加入忽略列表。
版本控制是你的安全网：在执行大规模清理前，务必提交（Commit）所有更改到版本控制系统。一旦发生误删，可以立即回滚（Revert）到清理前的状态。这是最可靠的安全措施。

6.2 清理后编辑器变慢或Shader编译卡顿

问题：清理了DDC和Intermediate后，再次打开项目，编辑器响应缓慢，且长时间显示“编译着色器”。

原因与对策：这是正常现象。DDC的清理导致引擎需要重新为所有材质和网格体编译着色器。对策如下：

分批清理：不要在紧要关头（如打包发布前）清理整个DDC。可以定期（如每周一次）进行维护性清理。
利用共享DDC：在团队环境中，可以设置一个网络共享的DDC服务器（Derived Data Cache Server），这样团队成员可以共享已编译的着色器数据，减少重复编译。清理本地DDC后，可以从共享缓存快速拉取。
保留核心DDC：更精细的做法是，只清理Saved/DerivedDataCache/下以旧驱动版本或无关平台命名的文件夹，保留当前主要开发平台（如D3D11、D3D12）的缓存。

6.3 工具扫描速度过慢或卡死

问题：对于超大型项目（数万资产），扫描脚本运行极慢，甚至内存溢出。

优化策略：

增量扫描：不要每次都全量扫描。记录上次扫描的结果和时间戳，只扫描自上次以来新增或修改的资产，更新引用关系图。
多进程/异步处理：将资产列表分块，利用Python的multiprocessing模块进行并行分析。注意UE Python API的线程安全性，最好在独立的子进程中调用。
优化算法：使用更高效的数据结构（如邻接表）存储引用关系。避免在循环中进行重复的get_referencers调用，可以先批量收集所有资产数据，再进行图分析。
提供进度反馈：在UI中显示明确的进度条和当前正在分析的资产，让用户感知到工具在运行，而非卡死。

6.4 特殊资产的处理

有些资产看似未被引用，实则不可或缺。

资产类型	为何容易被误判	处理建议
游戏实例蓝图	通常在C++代码或项目设置中指定，而非被其他资产直接引用。	将其路径（如`/Game/Core/BP_GameInstance`）加入工具的永久忽略列表。
默认地图	在`DefaultEngine.ini`的`/Script/EngineSettings.GameMapsSettings`中配置。	扫描时读取该配置文件，将`GameDefaultMap`和`GlobalDefaultGameMode`对应的资产排除。
项目设置中引用的资产	如默认玩家控制器、HUD类、物理材质等。	解析`DefaultEngine.ini`和`DefaultGame.ini`，提取所有`/Script/...`路径的资产引用。
动态加载的资产	通过`LoadObject`或`StreamableManager`在运行时按路径加载。	这最难处理。需要团队建立规范，将所有动态加载的资产路径集中管理在一个数据表或配置文件中，然后让清理工具读取这个配置文件作为白名单。

我个人在实际操作中的体会是，ProjectCleaner工具的价值，30%在于其自动化能力，70%在于其背后体现的资产管理和团队规范。一个混乱的项目，再好的清理工具也治标不治本。因此，在项目初期就建立良好的习惯至关重要：使用清晰的文件夹结构命名规范；及时删除实验性的、废弃的资产；对于必须存在的“孤立”资产（如基础材质函数库），建立一个/Game/Core/System或/Game/Art/Common目录集中存放，并明确告知所有成员和工具“此目录免检”。最后，无论工具多么智能，在执行大规模清理操作前，备份你的项目，或者确保版本控制处于一个干净、可回退的状态，这是永远不能省略的“金科玉律”。