游戏引擎 / 系统课时

检查导出后缺失的资源

检查导出后缺失的资源

编辑器能加载的图片、地图或 JSON,在导出包里可能不在预期路径。本课从真实失败路径检查资源范围、动态依赖和大小写,用一个启动清单例程建立可重复的检查,而不是把全部文件一股脑加入包体。

学习目标

  • 能按路径区分资源缺失、导入和文件读取问题
  • 能核对动态加载清单与导出过滤规则

先记录失败的真实路径

在导出包中复现缺图、地图打不开或配置读取失败,记录构建编号、资源路径、错误与触发操作。检查 res:// 路径的大小写及拼接结果,不用源码目录绝对路径解释发布包。Windows 上看似正常的大小写错误,可能到 Linux 等环境才暴露。

使用 ResourceLoader 读取纹理、场景等引擎资源,用 FileAccess 读取明确作为原始文件导出的 JSON、CSV 等数据。导入后的资源可能被转换与重映射;不要以原 PNG 文件在文件系统读取中找不到,就直接断言引擎资源缺失。

如果某个场景只由运行时拼出来的路径加载,导出器未必能从静态依赖推断它。查看 Project → Export → Resources 中选择范围,确认目标场景显式包含,或采用能覆盖完整动态集合的规则。临时“导出全部”可用于对照,但还需要找出准确依赖。

用显式清单检查动态关卡

先保存 levels.json,本例只列一个关卡。清单路径属于业务数据,导出时也必须包含它本身。

json
{"levels":["res://level_a.tscn"]}

再保存最小场景 level_a.tscn。

ini
[gd_scene format=3]

[node name="LevelA" type="Node2D"]

最后保存完整检查入口 manifest.gd,执行 godot --headless --path . --script manifest.gd。这是源项目清单检查;正式包应在启动自检里执行对应资源检查,不能用这个结果代替导出验收。

gdscript
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()

预期输出(省略启动横幅):

text
validated_levels=1

路径存在且能加载只证明这一份项目输入的基本资源链;场景脚本、运行时再加载和平台插件仍需要实际运行。正式检查应覆盖清单里的每一条,并报告失败项,不能遇到一项成功就跳过剩余关卡。

检查过滤、忽略与非资源文件

导出过滤器区分资源范围与非资源文件包含规则。JSON、CSV 等业务文件需要相应包含过滤器;排除规则也可能覆盖原本选中的文件。检查文件或文件夹名称是否以点开头,这类文件不会按普通资源规则进入导出包,不要将正式业务数据放在那里。

默认排除源码缓存目录是正常行为;导入资源由导出流程处理,不应手工把整个 .godot 目录加入发布包来修复缺图。对自定义插件或原生扩展,按它们的导出要求核对平台二进制与相关文件,不能只依赖编辑器里已经安装插件。

在隔离目录复测修复

使用新的版本输出目录重新导出,把包复制到没有项目源码的地方启动,遍历动态地图、语言文件和可选内容。记录每个失败路径与包含规则。若只在一平台失败,再检查大小写、路径分隔、格式支持和平台插件,不继续扩大所有平台包体。

给启动清单建立版本归属,保证清单与资源来自同一构建。再测试清单缺失和格式错误的失败路径。修改过滤器后重新测包体和加载,确认没有把测试素材或隐私配置一起包含。完成条件是正式包在目标平台逐项加载成功并功能正确,源码检查成功只构成前置证据。

过滤规则见 Exporting projects,资源与原始文件差异见 FileAccess。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

检查导出后缺失的资源

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通