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

load

定义

load() 用于在运行时加载一个资源文件（如图片、音频、场景等）。你告诉它文件的路径，它就会把文件读进内存，返回对应的资源对象。

想象你有一个书架，上面摆满了书（资源文件）。load() 就像你从书架上取下一本书——你可以随时取任何一本书，而且可以反复取同一本书（Godot 会自动缓存，不会重复加载）。

load() 和 preload() 的区别：

• load() 在运行时加载，可以用变量路径（"我不知道要加载哪个文件，等用户选了再说"）
• preload() 在编译时加载，路径必须写死（"我明确知道要用这个文件"）

函数签名

C#

// C# 中使用 GD.Load
var resource = GD.Load<Resource>("res://path/to/file.png");

GDScript

func load(path: String) -> Variant

参数说明

参数	类型	必需	说明
path	String	是	资源文件的路径，通常以 res:// 开头（项目内路径）或 user:// 开头（用户数据路径）

返回值

Variant（通常是 Resource 的子类）—— 加载成功时返回对应的资源对象（如 Texture2D、AudioStream、PackedScene 等）。加载失败时返回 null。

代码示例

基础用法：加载不同类型的资源

C#

using Godot;

public partial class LoadExample : Node
{
    public override void _Ready()
    {
        // 加载图片
        var texture = GD.Load<Texture2D>("res://icon.svg");
        GD.Print($"图片加载: {(texture != null ? "成功" : "失败")}");
        // 运行结果: 图片加载: 成功

        // 加载场景
        var scene = GD.Load<PackedScene>("res://scenes/player.tscn");
        GD.Print($"场景加载: {(scene != null ? "成功" : "失败")}");

        // 加载音频
        var audio = GD.Load<AudioStream>("res://sounds/bgm.ogg");
        GD.Print($"音频加载: {(audio != null ? "成功" : "失败")}");
    }
}

GDScript

extends Node

func _ready():
    # 加载图片
    var texture = load("res://icon.svg")
    print("图片加载: ", "成功" if texture else "失败")
    # 运行结果: 图片加载: 成功

    # 加载场景
    var scene = load("res://scenes/player.tscn")
    print("场景加载: ", "成功" if scene else "失败")

    # 加载音频
    var audio = load("res://sounds/bgm.ogg")
    print("音频加载: ", "成功" if audio else "失败")

实际场景：动态加载角色皮肤

C#

using Godot;

public partial class SkinManager : Sprite2D
{
    [Export] public string ExSkinFolder = "res://assets/skins/";

    public void ChangeSkin(string skinName)
    {
        string path = $"{ExSkinFolder}{skinName}.png";
        var texture = GD.Load<Texture2D>(path);

        if (texture != null)
        {
            Texture = texture;
            GD.Print($"皮肤切换成功: {skinName}");
        }
        else
        {
            GD.PrintErr($"找不到皮肤: {path}");
        }
    }

    public override void _Ready()
    {
        // 根据玩家选择动态加载不同皮肤
        ChangeSkin("warrior");
        // 运行结果: 皮肤切换成功: warrior
    }
}

GDScript

extends Sprite2D

@export var ex_skin_folder: String = "res://assets/skins/"

func change_skin(skin_name: String) -> void:
    var path = ex_skin_folder + skin_name + ".png"
    var texture = load(path)

    if texture:
        texture = texture
        print("皮肤切换成功: ", skin_name)
    else:
        push_error("找不到皮肤: " + path)

func _ready():
    # 根据玩家选择动态加载不同皮肤
    change_skin("warrior")
    # 运行结果: 皮肤切换成功: warrior

进阶用法：关卡加载系统

C#

using Godot;

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

    private Node _currentLevel;

    public void LoadLevel(string levelName)
    {
        // 卸载当前关卡
        if (_currentLevel != null)
        {
            _currentLevel.QueueFree();
        }

        string path = $"{ExLevelFolder}{levelName}.tscn";
        var scene = GD.Load<PackedScene>(path);

        if (scene != null)
        {
            _currentLevel = scene.Instantiate();
            AddChild(_currentLevel);
            GD.Print($"关卡加载成功: {levelName}");
        }
        else
        {
            GD.PrintErr($"关卡不存在: {path}");
        }
    }

    public override void _Ready()
    {
        LoadLevel("level_01");
        // 运行结果: 关卡加载成功: level_01
    }
}

GDScript

extends Node

@export var ex_level_folder: String = "res://scenes/levels/"

var _current_level: Node

func load_level(level_name: String) -> void:
    # 卸载当前关卡
    if _current_level:
        _current_level.queue_free()

    var path = ex_level_folder + level_name + ".tscn"
    var scene = load(path)

    if scene:
        _current_level = scene.instantiate()
        add_child(_current_level)
        print("关卡加载成功: ", level_name)
    else:
        push_error("关卡不存在: " + path)

func _ready():
    load_level("level_01")
    # 运行结果: 关卡加载成功: level_01

注意事项

1. 路径格式：资源路径必须以 res://（项目内路径）或 user://（用户数据路径）开头。不支持绝对文件系统路径如 C:\xxx。

2. 与 preload() 的选择：如果路径在编写代码时就确定了（如常量），优先使用 preload()，它在编译时就加载好了，运行时不会有延迟。如果路径是动态的（运行时才能确定），则必须使用 load()。

3. 资源缓存：Godot 会自动缓存已加载的资源。多次调用 load("res://same.png") 不会重复读取文件，而是返回同一份缓存的资源。如果需要重新加载，请使用 ResourceLoader.Load() 并传入 ResourceLoader.CacheMode.Replace 参数。

4. C# 中使用泛型：C# 中推荐使用带泛型的 GD.Load<T>() 来获取类型安全的资源引用，如 GD.Load<Texture2D>("res://icon.svg")。