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

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

@export_file

定义

@export_file 是 GDScript 中的一个注解（annotation），用来在 Godot 编辑器的检查器面板中暴露一个文件路径选择器。使用这个注解后，你可以在编辑器里直接浏览并选择项目内部的文件（res:// 路径），文件路径会以字符串的形式保存在变量中。

简单说，它就像一个"文件选择对话框"直接嵌入到了检查器面板里。比如你需要让角色播放一段音效，就可以用 @export_file 在编辑器中选择音效文件，而不需要硬编码文件路径。

在 C# 中，对应的写法是 [Export(PropertyHint.File, "过滤字符串")]。

语法

C#

// 不带过滤器：可以选择任何文件
[Export(PropertyHint.File)]
public string ExConfigPath = "";

// 带过滤器：只能选择特定扩展名的文件
[Export(PropertyHint.File, "*.json")]
public string ExDataFile = "";

// 多种扩展名过滤器
[Export(PropertyHint.File, "*.png,*.jpg,*.jpeg")]
public string ExImagePath = "";

GDScript

# 不带过滤器：可以选择任何文件
@export_file var ex_config_path: String = ""

# 带过滤器：只能选择特定扩展名的文件
@export_file("*.json") var ex_data_file: String = ""

# 多种扩展名过滤器
@export_file("*.png,*.jpg,*.jpeg") var ex_image_path: String = ""

参数说明

参数	类型	必需	说明
filter	String	否	文件过滤器，用于限制可选文件的扩展名。格式为 "*.扩展名"，多个过滤器用逗号分隔，例如 "*.png,*.jpg"。如果不传此参数，则允许选择任何文件

返回值

@export_file 是一个注解，没有返回值。变量的值是文件路径字符串，格式为 res://路径/文件名.扩展名。

代码示例

C#

using Godot;

public partial class DataLoader : Node
{
    // ===== 基础用法：选择文件路径 =====
    [Export(PropertyHint.File, "*.json")]
    public string ExLevelDataFile = "res://data/level_01.json";

    public override void _Ready()
    {
        GD.Print($"关卡数据文件: {ExLevelDataFile}");
    }
    // 运行结果: 关卡数据文件: res://data/level_01.json


    // ===== 实际场景：加载配置文件 =====
    [Export(PropertyHint.File, "*.json")]
    public string ExEnemyConfigFile = "";

    [Export(PropertyHint.File, "*.tres")]
    public string ExMaterialFile = "";

    public void LoadEnemyConfig()
    {
        if (string.IsNullOrEmpty(ExEnemyConfigFile))
        {
            GD.PrintErr("未设置敌人配置文件路径");
            return;
        }

        var file = FileAccess.Open(ExEnemyConfigFile, FileAccess.ModeFlags.Read);
        if (file != null)
        {
            string jsonText = file.GetAsText();
            file.Close();
            GD.Print($"成功读取配置文件，内容长度: {jsonText.Length} 字符");
        }
        else
        {
            GD.PrintErr($"无法打开文件: {ExEnemyConfigFile}");
        }
    }
    // 运行结果: 成功读取配置文件，内容长度: 256 字符


    // ===== 进阶用法：多种文件类型与动态加载 =====
    [Export(PropertyHint.File, "*.ogg,*.mp3,*.wav")]
    public string ExBgmFile = "";

    [Export(PropertyHint.File, "*.png,*.jpg")]
    public string ExPortraitFile = "";

    private AudioStreamPlayer _bgmPlayer;

    public void PlayBgm()
    {
        if (string.IsNullOrEmpty(ExBgmFile)) return;

        var stream = GD.Load<AudioStream>(ExBgmFile);
        if (stream != null)
        {
            _bgmPlayer = new AudioStreamPlayer();
            AddChild(_bgmPlayer);
            _bgmPlayer.Stream = stream;
            _bgmPlayer.Play();
            GD.Print($"正在播放背景音乐: {ExBgmFile}");
        }
    }
    // 运行结果: 正在播放背景音乐: res://audio/bgm_battle.ogg
}

GDScript

extends Node

# ===== 基础用法：选择文件路径 =====
@export_file("*.json") var ex_level_data_file: String = "res://data/level_01.json"

func _ready():
    print("关卡数据文件: %s" % ex_level_data_file)
# 运行结果: 关卡数据文件: res://data/level_01.json


# ===== 实际场景：加载配置文件 =====
@export_file("*.json") var ex_enemy_config_file: String = ""
@export_file("*.tres") var ex_material_file: String = ""

func load_enemy_config():
    if ex_enemy_config_file.is_empty():
        push_error("未设置敌人配置文件路径")
        return

    var file := FileAccess.open(ex_enemy_config_file, FileAccess.READ)
    if file:
        var json_text := file.get_as_text()
        file.close()
        print("成功读取配置文件，内容长度: %d 字符" % json_text.length())
    else:
        push_error("无法打开文件: %s" % ex_enemy_config_file)
# 运行结果: 成功读取配置文件，内容长度: 256 字符


# ===== 进阶用法：多种文件类型与动态加载 =====
@export_file("*.ogg,*.mp3,*.wav") var ex_bgm_file: String = ""
@export_file("*.png,*.jpg") var ex_portrait_file: String = ""

func play_bgm():
    if ex_bgm_file.is_empty():
        return

    var stream := load(ex_bgm_file) as AudioStream
    if stream:
        var player := AudioStreamPlayer.new()
        add_child(player)
        player.stream = stream
        player.play()
        print("正在播放背景音乐: %s" % ex_bgm_file)
# 运行结果: 正在播放背景音乐: res://audio/bgm_battle.ogg

注意事项

• @export_file 选择的是项目内部路径（res:// 开头），不是电脑上的绝对路径。如果需要选择项目外部的文件，请使用 @export_global_file。
• 变量类型必须是 String，路径以 res:// 开头。
• 文件过滤器只是编辑器中的显示限制，不会阻止你手动输入其他路径。
• 即使文件不存在，路径也会被保存。加载文件前最好检查文件是否存在（FileAccess.Open 是否返回 null，或 GDScript 中用 ResourceLoader.Exists）。
• @export_file 不会实际加载文件——它只是保存路径字符串。你需要自己在代码中用 GD.Load() 或 FileAccess 来加载文件内容。
• C# 中过滤器写在 [Export(PropertyHint.File, "*.json")] 的第二个参数中。