跳至主要內容

ResourceLoader.load

EVOCOSMOS2026/4/14大约 7 分钟

最后更新日期：2026-04-16

最后同步日期：2026-04-15 | Godot 官方原文 — ResourceLoader.load

ResourceLoader.load

定义

ResourceLoader.load 就像从书架上取下一本书——你告诉它书的名字（文件路径），它就把这本书的内容（资源对象）交给你用。在 Godot 中，"资源"包括图片、音频、字体、场景文件（.tscn）、材质、纹理等一切存储在磁盘上的文件。

你可以把它想象成快递柜：你输入取件码（文件路径），快递柜就会把对应的包裹（资源）弹出来给你。如果之前有人取过同一个包裹，快递柜会直接给你之前取的那份（缓存机制），而不会再去仓库翻找。

一句话总结

ResourceLoader.load 的作用是"从硬盘加载一个资源文件到内存中"，加载后就可以在代码中使用这个资源了。

函数签名

C#
// 泛型版本（推荐）——直接返回指定类型的资源
public static T Load<T>(string path, string typeHint = "", ResourceLoader.CacheMode cacheMode = ResourceLoader.CacheMode.Reuse) where T : class

// 非泛型版本——返回 Resource 基类，需要手动转换类型
public static Resource Load(string path, string typeHint = "", ResourceLoader.CacheMode cacheMode = ResourceLoader.CacheMode.Reuse)

参数说明

参数类型必需说明
pathstring / String是资源文件的路径，如 "res://sprites/player.png"。支持 res://（项目根目录）和 user://（用户数据目录）两种协议
typeHintstring / String否类型提示，告诉 Godot 你期望加载的资源类型（如 "Texture2D"、"PackedScene"）。可以提高加载速度，避免加载到错误的类型
cacheModeCacheMode / int否缓存模式，控制如何使用已缓存的资源（见下方说明）

缓存模式（CacheMode）

模式值说明
CacheMode.Reuse / CACHE_MODE_REUSE0默认值。如果资源已经被加载过且在缓存中，直接返回缓存的实例，不会重复加载
CacheMode.Ignore / CACHE_MODE_IGNORE1忽略缓存，总是重新加载资源，但不会更新缓存。适合需要读取最新文件内容的场景
CacheMode.Replace / CACHE_MODE_REPLACE2重新加载资源并更新缓存。适合资源文件在运行时被修改后需要刷新的场景

返回值

类型说明
T (C# 泛型) / Resource (GDScript)成功时返回加载的资源对象；如果路径无效或加载失败，返回 null

代码示例

基础用法

最简单的用法——加载一张图片作为纹理：

C#
using Godot;

public partial class TextureLoader : Node
{
    public override void _Ready()
    {
        // 加载一张图片作为纹理
        var texture = ResourceLoader.Load<Texture2D>("res://icon.svg");

        if (texture != null)
        {
            GD.Print("纹理加载成功！尺寸: " + texture.GetSize());
            // 运行结果: 纹理加载成功！尺寸: (128, 128)
        }
        else
        {
            GD.Print("纹理加载失败，请检查文件路径");
        }
    }
}

实际场景

在游戏中动态加载场景和创建实例——这是 ResourceLoader.load 最常见的用途之一。下面的例子展示了一个关卡加载系统：

C#
using Godot;

public partial class LevelManager : Node
{
    [Export] public string ExLevelPath = "res://scenes/levels/";

    private Node _currentLevel;

    public override void _Ready()
    {
        // 加载并进入第一关
        LoadLevel("level_01.tscn");
    }

    public void LoadLevel(string levelFileName)
    {
        string fullPath = ExLevelPath + levelFileName;

        // 先检查资源是否存在
        if (!ResourceLoader.Exists(fullPath))
        {
            GD.PrintErr("关卡文件不存在: " + fullPath);
            return;
        }

        // 加载场景资源
        var scene = ResourceLoader.Load<PackedScene>(fullPath);

        if (scene == null)
        {
            GD.PrintErr("关卡加载失败: " + fullPath);
            return;
        }

        // 移除当前关卡（如果有的话）
        if (_currentLevel != null)
        {
            _currentLevel.QueueFree();
        }

        // 实例化新关卡并添加到场景树
        _currentLevel = scene.Instantiate();
        AddChild(_currentLevel);

        GD.Print("关卡加载成功: " + levelFileName);
        // 运行结果: 关卡加载成功: level_01.tscn
    }
}

进阶用法

使用不同的缓存模式，以及后台线程加载资源（避免卡顿）：

C#
using Godot;

public partial class AdvancedResourceLoader : Node
{
    public override void _Ready()
    {
        // ===== 示例 1：不同缓存模式 =====
        // 默认模式：重复加载会返回同一实例（缓存命中）
        var tex1 = ResourceLoader.Load<Texture2D>("res://icon.svg");
        var tex2 = ResourceLoader.Load<Texture2D>("res://icon.svg");
        GD.Print("是否同一个实例: " + (tex1 == tex2));
        // 运行结果: 是否同一个实例: True

        // Ignore 模式：忽略缓存，从磁盘重新读取
        var tex3 = ResourceLoader.Load<Texture2D>("res://icon.svg",
            cacheMode: ResourceLoader.CacheMode.Ignore);
        GD.Print("Ignore 模式是否同一实例: " + (tex1 == tex3));
        // 运行结果: Ignore 模式是否同一实例: False

        // ===== 示例 2：批量加载资源 =====
        string[] spritePaths = {
            "res://sprites/player_idle.png",
            "res://sprites/player_run.png",
            "res://sprites/player_jump.png"
        };

        foreach (string path in spritePaths)
        {
            if (ResourceLoader.Exists(path))
            {
                var sprite = ResourceLoader.Load<Texture2D>(path);
                GD.Print("已加载: " + path + " 尺寸: " + sprite.GetSize());
            }
            else
            {
                GD.Print("文件不存在: " + path);
            }
        }
        // 运行结果:
        // 已加载: res://sprites/player_idle.png 尺寸: (64, 64)
        // 已加载: res://sprites/player_run.png 尺寸: (64, 64)
        // 已加载: res://sprites/player_jump.png 尺寸: (64, 64)

        // ===== 示例 3：使用类型提示提高加载安全性 =====
        // type_hint 确保只加载指定类型的资源
        var scene = ResourceLoader.Load<PackedScene>(
            "res://scenes/enemy.tscn",
            typeHint: "PackedScene"
        );
        GD.Print("场景加载完成，实例化测试: " + (scene != null));
        // 运行结果: 场景加载完成，实例化测试: True
    }
}

注意事项

  • 路径必须以 res:// 或 user:// 开头：res:// 指向项目根目录（最常用），user:// 指向用户数据持久化目录。不支持相对路径或绝对系统路径。
  • 加载失败返回 null：如果文件不存在或格式不正确，Load 返回 null。建议加载后检查是否为 null 再使用。
  • 缓存机制：默认情况下，同一个路径的资源只会加载一次，后续调用 Load 会返回缓存中的同一实例。这意味着如果你修改了加载后的资源对象，所有引用该资源的地方都会受影响。
  • 不要在每帧都调用 Load：资源加载涉及磁盘 I/O，应该只在需要时（如初始化、切换关卡）加载，不要放在 _Process 等每帧调用的函数中。
  • 大文件考虑异步加载：对于音频、大纹理等文件，可以使用 ResourceLoader.LoadThreadedRequest 和 ResourceLoader.LoadThreadedGet 进行后台线程加载，避免主线程卡顿。
  • C# 差异：C# 推荐使用泛型版本 ResourceLoader.Load<T>(path) 直接获得目标类型，避免手动类型转换。GDScript 中返回 Resource 基类，通常无需手动转换即可直接使用。
  • C# 简写方式：在 C# 中也可以使用 GD.Load<T>(path) 作为 ResourceLoader.Load<T>(path) 的简写形式，两者完全等价。
最近更新:
贡献者: zefeng.peng,bobokaka
EVOCOSMOS
Copyright © 2026 EVOCOSMOS