游戏引擎 / 系统课时
检查导出后缺失的资源
检查导出后缺失的资源
编辑器能加载的图片、地图或 JSON,在导出包里可能不在预期路径。本课从真实失败路径检查资源范围、动态依赖和大小写,用一个启动清单例程建立可重复的检查,而不是把全部文件一股脑加入包体。
学习目标
- 能按路径区分资源缺失、导入和文件读取问题
- 能核对动态加载清单与导出过滤规则
先记录失败的真实路径
在导出包中复现缺图、地图打不开或配置读取失败,记录构建编号、资源路径、错误与触发操作。检查 res:// 路径的大小写及拼接结果,不用源码目录绝对路径解释发布包。Windows 上看似正常的大小写错误,可能到 Linux 等环境才暴露。
使用 ResourceLoader 读取纹理、场景等引擎资源,用 FileAccess 读取明确作为原始文件导出的 JSON、CSV 等数据。导入后的资源可能被转换与重映射;不要以原 PNG 文件在文件系统读取中找不到,就直接断言引擎资源缺失。
如果某个场景只由运行时拼出来的路径加载,导出器未必能从静态依赖推断它。查看 Project → Export → Resources 中选择范围,确认目标场景显式包含,或采用能覆盖完整动态集合的规则。临时“导出全部”可用于对照,但还需要找出准确依赖。
用显式清单检查动态关卡
先保存 levels.json,本例只列一个关卡。清单路径属于业务数据,导出时也必须包含它本身。
{"levels":["res://level_a.tscn"]}再保存最小场景 level_a.tscn。
[gd_scene format=3]
[node name="LevelA" type="Node2D"]最后保存完整检查入口 manifest.gd,执行 godot --headless --path . --script manifest.gd。这是源项目清单检查;正式包应在启动自检里执行对应资源检查,不能用这个结果代替导出验收。
extends SceneTree
func _initialize() -> void:
var file := FileAccess.open("res://levels.json", FileAccess.READ)
if file == null:
push_error("levels.json missing")
quit(1)
return
var data: Variant = JSON.parse_string(file.get_as_text())
file.close()
if not data is Dictionary or not data.get("levels") is Array:
push_error("invalid level manifest")
quit(1)
return
var count := 0
for value in data["levels"]:
if not value is String or not ResourceLoader.exists(value, "PackedScene"):
push_error("level missing: %s" % value)
quit(1)
return
var scene := ResourceLoader.load(value, "PackedScene") as PackedScene
if scene == null:
quit(1)
return
count += 1 # 实际尝试加载,存在性检查不能替代加载成功。
print("validated_levels=", count)
quit()预期输出(省略启动横幅):
validated_levels=1路径存在且能加载只证明这一份项目输入的基本资源链;场景脚本、运行时再加载和平台插件仍需要实际运行。正式检查应覆盖清单里的每一条,并报告失败项,不能遇到一项成功就跳过剩余关卡。
检查过滤、忽略与非资源文件
导出过滤器区分资源范围与非资源文件包含规则。JSON、CSV 等业务文件需要相应包含过滤器;排除规则也可能覆盖原本选中的文件。检查文件或文件夹名称是否以点开头,这类文件不会按普通资源规则进入导出包,不要将正式业务数据放在那里。
默认排除源码缓存目录是正常行为;导入资源由导出流程处理,不应手工把整个 .godot 目录加入发布包来修复缺图。对自定义插件或原生扩展,按它们的导出要求核对平台二进制与相关文件,不能只依赖编辑器里已经安装插件。
在隔离目录复测修复
使用新的版本输出目录重新导出,把包复制到没有项目源码的地方启动,遍历动态地图、语言文件和可选内容。记录每个失败路径与包含规则。若只在一平台失败,再检查大小写、路径分隔、格式支持和平台插件,不继续扩大所有平台包体。
给启动清单建立版本归属,保证清单与资源来自同一构建。再测试清单缺失和格式错误的失败路径。修改过滤器后重新测包体和加载,确认没有把测试素材或隐私配置一起包含。完成条件是正式包在目标平台逐项加载成功并功能正确,源码检查成功只构成前置证据。
过滤规则见 Exporting projects,资源与原始文件差异见 FileAccess。