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

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

@export_global_dir

定义

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

简单说，@export_dir 只能在项目"家里"选文件夹，@export_global_dir 可以在整个电脑上选。比如你的游戏需要让玩家指定一个外部存档目录，或者读取某个系统目录下的资源，就需要这个注解。

在 C# 中，对应的写法是 [Export(PropertyHint.GlobalDir)]。

语法

C#

// 导出全局文件夹路径选择器
[Export(PropertyHint.GlobalDir)]
public string ExExternalSaveDir = "";

GDScript

# 导出全局文件夹路径选择器
@export_global_dir var ex_external_save_dir: String = ""

参数说明

@export_global_dir 不需要任何参数——它直接写在变量声明前面即可。

说明项	详情
变量类型	必须是 String
路径格式	操作系统的绝对路径（如 C:/Users/xxx/Documents 或 /home/xxx/saves）
编辑器控件	文件夹浏览按钮，点击后弹出系统级文件夹选择对话框

返回值

@export_global_dir 是一个注解，没有返回值。变量的值是一个绝对路径字符串，格式取决于操作系统。

代码示例

C#

using Godot;

public partial class SaveManager : Node
{
    // ===== 基础用法：选择外部文件夹 =====
    [Export(PropertyHint.GlobalDir)]
    public string ExExternalSaveDir = "";

    public override void _Ready()
    {
        if (!string.IsNullOrEmpty(ExExternalSaveDir))
        {
            GD.Print($"外部存档目录: {ExExternalSaveDir}");
        }
    }
    // 运行结果: 外部存档目录: C:/Users/Player/Documents/MyGameSaves


    // ===== 实际场景：管理外部存档目录 =====
    [Export(PropertyHint.GlobalDir)]
    public string ExSaveDirectory = "";

    public void EnsureSaveDirectory()
    {
        if (string.IsNullOrEmpty(ExSaveDirectory))
        {
            GD.PrintErr("未设置存档目录");
            return;
        }

        if (!DirAccess.DirExistsAbsolute(ExSaveDirectory))
        {
            var error = DirAccess.MakeDirRecursiveAbsolute(ExSaveDirectory);
            if (error == Error.Ok)
            {
                GD.Print($"已创建存档目录: {ExSaveDirectory}");
            }
            else
            {
                GD.PrintErr($"创建存档目录失败: {error}");
            }
        }
        else
        {
            GD.Print($"存档目录已存在: {ExSaveDirectory}");
        }
    }
    // 运行结果: 已创建存档目录: C:/Users/Player/Documents/MyGameSaves


    // ===== 进阶用法：多目录管理 =====
    [Export(PropertyHint.GlobalDir)]
    public string ExScreenshotDir = "";

    [Export(PropertyHint.GlobalDir)]
    public string ExLogOutputDir = "";

    public void PrintDirectoryInfo()
    {
        string[] dirs = { ExScreenshotDir, ExLogOutputDir };
        string[] names = { "截图", "日志" };

        for (int i = 0; i < dirs.Length; i++)
        {
            if (!string.IsNullOrEmpty(dirs[i]) && DirAccess.DirExistsAbsolute(dirs[i]))
            {
                GD.Print($"{names[i]}目录已就绪: {dirs[i]}");
            }
        }
    }
    // 运行结果: 截图目录已就绪: C:/Users/Player/Pictures/MyGame
    // 运行结果: 日志目录已就绪: C:/Users/Player/AppData/MyGame/Logs
}

GDScript

extends Node

# ===== 基础用法：选择外部文件夹 =====
@export_global_dir var ex_external_save_dir: String = ""

func _ready():
    if not ex_external_save_dir.is_empty():
        print("外部存档目录: %s" % ex_external_save_dir)
# 运行结果: 外部存档目录: C:/Users/Player/Documents/MyGameSaves


# ===== 实际场景：管理外部存档目录 =====
@export_global_dir var ex_save_directory: String = ""

func ensure_save_directory():
    if ex_save_directory.is_empty():
        push_error("未设置存档目录")
        return

    if not DirAccess.dir_exists_absolute(ex_save_directory):
        var err := DirAccess.make_dir_recursive_absolute(ex_save_directory)
        if err == OK:
            print("已创建存档目录: %s" % ex_save_directory)
        else:
            push_error("创建存档目录失败: %s" % err)
    else:
        print("存档目录已存在: %s" % ex_save_directory)
# 运行结果: 已创建存档目录: C:/Users/Player/Documents/MyGameSaves


# ===== 进阶用法：多目录管理 =====
@export_global_dir var ex_screenshot_dir: String = ""
@export_global_dir var ex_log_output_dir: String = ""

func print_directory_info():
    var dirs := [ex_screenshot_dir, ex_log_output_dir]
    var names := ["截图", "日志"]

    for i in range(dirs.size()):
        if not dirs[i].is_empty() and DirAccess.dir_exists_absolute(dirs[i]):
            print("%s目录已就绪: %s" % [names[i], dirs[i]])
# 运行结果: 截图目录已就绪: C:/Users/Player/Pictures/MyGame
# 运行结果: 日志目录已就绪: C:/Users/Player/AppData/MyGame/Logs

注意事项

• @export_global_dir 选择的是操作系统上的绝对路径，不是 res:// 开头的项目路径。
• 跨平台兼容性：绝对路径在不同操作系统上格式不同，如果你的游戏需要发布到多个平台，请谨慎使用。
• 导出的游戏访问外部目录可能受到系统权限限制，尤其是在 macOS、移动端和 Web 平台。
• 如果你只需要选择项目内部的文件夹，请使用 @export_dir 而不是 @export_global_dir。
• @export_global_dir 不需要任何参数，直接写 @export_global_dir 即可。
• C# 中使用 [Export(PropertyHint.GlobalDir)] 的形式。