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

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

@export_global_file

定义

@export_global_file 是 GDScript 中的一个注解（annotation），用来在 Godot 编辑器的检查器面板中暴露一个全局文件路径选择器。与 @export_file 不同的是，它可以让你选择电脑上任意位置的文件，而不仅限于项目内部的 res:// 路径。

简单说，@export_file 只能在项目"家里"挑文件，@export_global_file 可以在整个电脑上找文件。比如你的游戏需要读取系统上的某个配置文件或日志文件，就需要用这个注解。

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

语法

C#

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

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

GDScript

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

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

参数说明

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

返回值

@export_global_file 是一个注解，没有返回值。变量的值是一个绝对路径字符串（如 C:/Users/xxx/config.json 或 /home/xxx/config.json），取决于操作系统。

代码示例

C#

using Godot;

public partial class ExternalFileManager : Node
{
    // ===== 基础用法：选择外部文件 =====
    [Export(PropertyHint.GlobalFile, "*.json")]
    public string ExExternalConfigPath = "";

    public override void _Ready()
    {
        if (!string.IsNullOrEmpty(ExExternalConfigPath))
        {
            GD.Print($"外部配置文件: {ExExternalConfigPath}");
        }
    }
    // 运行结果: 外部配置文件: C:/Users/Player/config.json


    // ===== 实际场景：读取外部日志文件 =====
    [Export(PropertyHint.GlobalFile, "*.txt,*.log")]
    public string ExLogFilePath = "";

    public void ReadLogFile()
    {
        if (string.IsNullOrEmpty(ExLogFilePath))
        {
            GD.PrintErr("未指定日志文件路径");
            return;
        }

        using var file = FileAccess.Open(ExLogFilePath, FileAccess.ModeFlags.Read);
        if (file != null)
        {
            int lineCount = 0;
            while (!file.EofReached())
            {
                file.GetLine();
                lineCount++;
            }
            GD.Print($"日志文件共有 {lineCount} 行");
        }
        else
        {
            GD.PrintErr($"无法读取文件: {ExLogFilePath}");
        }
    }
    // 运行结果: 日志文件共有 128 行


    // ===== 进阶用法：多外部文件路径管理 =====
    [Export(PropertyHint.GlobalFile, "*.csv")]
    public string ExDataSourcePath = "";

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

    public void PrintFileInfo()
    {
        if (!string.IsNullOrEmpty(ExDataSourcePath))
        {
            GD.Print($"数据源: {ExDataSourcePath}");
        }
        if (!string.IsNullOrEmpty(ExExternalImagePath))
        {
            var image = Image.LoadFromFile(ExExternalImagePath);
            if (image != null)
            {
                GD.Print($"图片尺寸: {image.GetWidth()}x{image.GetHeight()}");
            }
        }
    }
    // 运行结果: 数据源: C:/Data/game_data.csv
    // 运行结果: 图片尺寸: 1920x1080
}

GDScript

extends Node

# ===== 基础用法：选择外部文件 =====
@export_global_file("*.json") var ex_external_config_path: String = ""

func _ready():
    if not ex_external_config_path.is_empty():
        print("外部配置文件: %s" % ex_external_config_path)
# 运行结果: 外部配置文件: C:/Users/Player/config.json


# ===== 实际场景：读取外部日志文件 =====
@export_global_file("*.txt,*.log") var ex_log_file_path: String = ""

func read_log_file():
    if ex_log_file_path.is_empty():
        push_error("未指定日志文件路径")
        return

    var file := FileAccess.open(ex_log_file_path, FileAccess.READ)
    if file:
        var line_count := 0
        while not file.eof_reached():
            file.get_line()
            line_count += 1
        print("日志文件共有 %d 行" % line_count)
    else:
        push_error("无法读取文件: %s" % ex_log_file_path)
# 运行结果: 日志文件共有 128 行


# ===== 进阶用法：多外部文件路径管理 =====
@export_global_file("*.csv") var ex_data_source_path: String = ""
@export_global_file("*.png,*.jpg") var ex_external_image_path: String = ""

func print_file_info():
    if not ex_data_source_path.is_empty():
        print("数据源: %s" % ex_data_source_path)
    if not ex_external_image_path.is_empty():
        var image := Image.load_from_file(ex_external_image_path)
        if image:
            print("图片尺寸: %dx%d" % [image.get_width(), image.get_height()])
# 运行结果: 数据源: C:/Data/game_data.csv
# 运行结果: 图片尺寸: 1920x1080

注意事项

• @export_global_file 选择的是操作系统上的绝对路径，不是 res:// 开头的项目路径。
• 跨平台兼容性：绝对路径在不同操作系统上格式不同（Windows 用 C:/，Linux/macOS 用 /home/），如果你的游戏需要发布到多个平台，请谨慎使用。
• 导出的游戏（打包后）访问外部文件可能会受到沙盒限制，尤其是在移动端和 Web 平台。
• 如果你只需要选择项目内部的文件，请使用 @export_file 而不是 @export_global_file。
• 变量类型必须是 String。
• C# 中使用 [Export(PropertyHint.GlobalFile, "*.txt")] 的形式。