Godot 编辑器路径指南：深入解析 EditorPaths 单例与跨平台数据目录

• 文档
• 教程
• 游戏开发

导读

EditorPaths是 Godot 引擎中一个仅编辑器可用的单例，用于获取各操作系统标准化的数据、配置与缓存目录路径，是编辑器插件安全落盘的关键基础设施。本文以classes/class_editorpaths.rst为核心，结合tutorials/io/data_paths.rst与classes/class_projectsettings.rst、classes/class_os.rst等关联文档，完整讲解其全部 6 个方法、各平台默认路径、XDG 规范兼容、自包含（self-contained）模式，并给出可在插件中直接使用的 GDScript 示例。

EditorPaths 是什么

EditorPaths是一个editor-only（仅编辑器）单例，继承自Object（见 class_object.rst 的继承列表）。它封装了编辑器在用户系统上存放数据、配置和缓存文件的标准位置，返回的都是绝对路径（OS 原生路径，非res:///user://虚拟路径）。

它的设计初衷是：在编辑器插件中，确保文件被保存到每个操作系统上的正确位置。例如插件需要写缓存、读配置、定位已安装的导出模板时，不应硬编码路径，而应通过EditorPaths动态获取。

从文档结构看（该文档由 Godot 引擎源码自动生成，XML 来源为引擎doc/classes/EditorPaths.xml），EditorPaths对外暴露的 API 非常精简，只有 6 个方法，全部为const（无副作用，不修改任何成员变量）：

在导出项目中不可用

关键限制：EditorPaths在导出的项目中不可访问。尝试在导出项目里访问该单例会直接产生脚本错误——因为该单例不会被声明。文档明确要求：

要在导出项目中避免脚本错误，使用Engine.has_singleton()先检查该单例是否可用，再决定是否调用。

# 安全访问 EditorPaths：先检查单例是否存在 if Engine.has_singleton("EditorPaths"): var editor_paths = Engine.get_singleton("EditorPaths") print(editor_paths.get_config_dir()) else: # 运行在导出项目中：EditorPaths 不存在 print("EditorPaths is not available in exported projects")

这一检查模式是所有编辑器专用单例（EditorPaths、EditorInterface等）在运行时脚本中的标准防护姿势。

从 EditorInterface 获取 EditorPaths

虽然可以直接通过Engine.get_singleton("EditorPaths")访问，但 Godot 也提供了更规范的入口：EditorInterface.get_editor_paths()直接返回EditorPaths单例（见 class_editorinterface.rst 的方法表与get_editor_paths方法描述）。

# 在编辑器插件脚本中获取 EditorPaths var editor_paths = EditorInterface.get_editor_paths()

在_enter_tree()/_exit_tree()生命周期之外（如_plugin脚本的工具模式运行）时，两种方式等价，可任选其一。

六大方法逐一详解

get_cache_dir()：缓存目录

返回用户缓存文件夹的绝对路径，用于存放可以安全删除的临时数据（例如编辑器生成的资源缩略图、着色器缓存等）。这类数据在编辑器关闭后随时可以清除。

各平台默认路径：

- Windows: %LOCALAPPDATA%\Godot\ - macOS: ~/Library/Caches/Godot/ - Linux: ~/.cache/godot/

在 Linux/BSD 上，该路径可通过在启动前设置XDG_CACHE_HOME环境变量来覆盖（详见 data_paths.rst 的 Editor data paths 一节）。注意与OS.get_cache_dir()的区别：后者返回的是全局缓存目录，而EditorPaths.get_cache_dir()返回的是Godot 编辑器专属缓存目录（两者在默认配置下通常就是同一位置，但语义上一个属于应用级、一个属于引擎级，详见 class_os.rst 中get_cache_dir的说明）。

get_config_dir()：配置目录

返回用户配置文件夹的绝对路径，用于存放持久的用户配置文件。典型用途包括：编辑器主设置文件、编辑器布局、功能配置文件（feature profiles）、脚本模板等自定义项。

各平台默认路径：

- Windows: %APPDATA%\Godot\ （与 get_data_dir() 相同） - macOS: ~/Library/Application Support/Godot/ （与 get_data_dir() 相同） - Linux: ~/.config/godot/

值得注意的是：在 Windows 和 macOS 上，get_config_dir()与get_data_dir()返回同一个目录，而 Linux 上二者分离（~/.config与~/.local/share）。这正是 XDG 规范下配置与数据分离的体现。

仓库中有多处实际引用证实了该目录的用途：在 class_editorfeatureprofile.rst 中，通过用户界面创建的功能配置文件（.profile扩展名）即保存在feature_profiles目录下，文档明确指示用EditorPaths.get_config_dir()定位编辑器配置目录；class_editorinterface.rst 中激活功能配置文件（set_feature_profile）时也要求配置文件位于该目录，否则会报错。

get_data_dir()：数据目录

返回用户数据文件夹的绝对路径，用于存放持久化的用户数据文件，最典型的就是已安装的导出模板（export templates）。

各平台默认路径：

- Windows: %APPDATA%\Godot\ （与 get_config_dir() 相同） - macOS: ~/Library/Application Support/Godot/ （与 get_config_dir() 相同） - Linux: ~/.local/share/godot/

get_project_settings_dir()：项目级编辑器设置目录

与前三个全局目录不同，这个方法返回的是相对路径，指向当前项目专属的编辑器设置位置，通常是"res://.godot/editor"。

每个项目都会在设置路径下拥有一个唯一子目录，用于保存项目专属的编辑器设置（不同项目互不干扰）。这与res://虚拟路径相关，具体而言：

• 项目内的.godot/目录存放项目级数据（元数据、着色器缓存等），其隐藏与否由项目设置application/config/use_hidden_project_data_directory控制（默认true使用隐藏的.godot，设为false则改用非隐藏的godot目录，详见 class_projectsettings.rst）。注意修改该设置后需要重启应用，且可能影响依赖默认.godot文件夹的第三方工具或插件。
• 该方法返回的res://.godot/editor即项目设置的实际落盘位置。

# 在插件中定位项目专属编辑器设置 var settings_dir = editor_paths.get_project_settings_dir() # 返回例如 "res://.godot/editor"

由于返回的是相对res://的路径，可直接配合FileAccess、DirAccess等以res://为前缀的 API 使用，无需再经过ProjectSettings.globalize_path()转换。

get_self_contained_file() 与 is_self_contained()：自包含模式

这两个方法共同支撑 Godot 的自包含（self-contained）模式，用于创建便携式编辑器安装。

• get_self_contained_file()：返回使当前编辑器实例被视为自包含的那个文件的绝对路径；若当前编辑器实例并非自包含，则返回空字符串。
• is_self_contained()：返回true表示编辑器已被标记为自包含，false反之。

启用方式：在编辑器未运行时，于编辑器二进制文件所在目录（macOS 则是 .app 包所在目录）创建一个名为._sc_或_sc_的文件即可。

行为差异：启用后，用户的配置、数据与缓存文件全部保存到编辑器二进制旁边的editor_data/目录中，使编辑器尽量减少自身文件夹之外的文件写入，便携使用（例如放到 U 盘、CI 环境）更加容易。

各平台启用位置对照：

- Windows/Linux: 与编辑器二进制（godot.exe / godot）同目录 - macOS: .app 包同级目录（而非 .app 内部！）

macOS 专属注意事项：

• 使用自包含模式前，应手动移除 quarantine（隔离）标记（Gatekeeper 下载文件的属性），否则可能无法正常运行。
• 不要把_sc_或任何其他文件放进 .app 包内部——这会破坏数字签名，使 .app 变得不可移植。应放在 .app 包同级目录。

其他平台注意：Steam 版 Godot 默认启用自包含模式。自包含模式对导出项目不可用；若需在导出项目中相对可执行文件读写文件，应使用OS.get_executable_path()（注意仅当可执行文件位于可写位置时有效，如放在 Program Files 等只读目录则不行，详见 data_paths.rst 的 Self-contained mode 一节）。

# 检查并打印自包含状态 var editor_paths = EditorInterface.get_editor_paths() if editor_paths.is_self_contained(): print("Self-contained file: ", editor_paths.get_self_contained_file()) # 数据将写入 <编辑器二进制目录>/editor_data/ else: print("Not self-contained")

Linux/BSD 上的 XDG 规范兼容

在 Linux/BSD 平台，Godot完全遵循 XDG Base Directory Specification（FreeBSD 规范，见 data_paths.rst 引用）。这意味着可以通过设置环境变量来重定向编辑器和项目数据路径：

# 示例：将 Godot 的编辑器数据、配置与缓存全部重定向到自定义目录 export XDG_DATA_HOME=/mnt/portable/godot-data export XDG_CONFIG_HOME=/mnt/portable/godot-config export XDG_CACHE_HOME=/mnt/portable/godot-cache godot --editor

这与OS.get_cache_dir()/get_config_dir()/get_data_dir()的文档描述相互印证——它们同样声明在 Linux/BSD 上可通过上述环境变量覆盖（见 class_os.rst 对应方法）。区别在于：EditorPaths系列返回的是Godot 编辑器专用目录（即 Godot 子目录下的路径），而OS系列返回全局用户目录本身，二者不应混淆。

另外，如果使用Flatpak 打包的 Godot，编辑器数据路径会位于~/.var/app/org.godotengine.Godot/的子目录中。

插件实战：把文件写到正确的位置

综合以上 API，一个典型的编辑器插件落盘场景如下：

# tools/editor_plugin.gd —— 编辑器插件脚本示例 @tool extends EditorPlugin func _enter_tree() -> void: var paths := EditorInterface.get_editor_paths() # 1. 持久化配置 → 配置目录 var config_path := paths.get_config_dir().path_join("my_plugin.cfg") _write_if_needed(config_path) # 2. 临时数据 → 缓存目录（可安全删除） var thumb_path := paths.get_cache_dir().path_join("my_plugin/thumb_cache.bin") _write_if_needed(thumb_path) # 3. 大体积持久数据（类似导出模板的定位）→ 数据目录 var data_path := paths.get_data_dir().path_join("my_plugin/assets") _write_if_needed(data_path) # 4. 项目专属编辑器设置 → res://.godot/editor var proj_settings := paths.get_project_settings_dir() print("Project editor settings live at: ", proj_settings) func _write_if_needed(path: String) -> void: var f := FileAccess.open(path, FileAccess.WRITE) if f: f.store_string("plugin data") f.close()

要点回顾：

1. 缓存 vs 配置 vs 数据：临时可删数据放缓存目录；小而持久的用户配置放配置目录；大体积/可再下载的持久数据（如导出模板、下载的资产）放数据目录。
2. 项目级 vs 用户级：与具体项目绑定、需要随项目走的编辑器设置放get_project_settings_dir()返回的res://.godot/editor；与项目无关、属于用户偏好的放配置目录。
3. 导出项目防护：任何可能在导出项目中被执行的代码路径都要先用Engine.has_singleton("EditorPaths")检查，或仅在EditorPlugin生命周期内调用。

与 user:// 的衔接

EditorPaths管理的是编辑器自身的目录；而玩家存档等项目运行时数据走的是user://前缀，其真实位置同样由这些编辑器数据路径派生。根据 data_paths.rst 的说明：

• 默认情况下，user://文件夹创建在Godot 编辑器数据目录（即EditorPaths.get_data_dir()对应的位置）下的app_userdata/[project_name]文件夹中，使原型和测试项目保持自包含。
• 若在项目设置中启用application/config/use_custom_user_dir（默认false），user://将被创建在紧挨着编辑器数据目录的位置（即应用数据标准位置），文件夹名默认从项目名推断，也可通过application/config/custom_user_dir_name进一步定制，该值甚至可以包含路径分隔符（如Studio Name/Game Name），便于按工作室分组（详见 class_projectsettings.rst）。

桌面平台user://实际路径对照：

理解这一层关系有助于排查"编辑器里能找到的东西，导出后怎么不见了"这类路径问题——编辑器侧的EditorPaths与运行时侧的user://共享同一套操作系统目录约定，只是入口不同。

总结

EditorPaths是 Godot 编辑器插件开发中一个虽小但不可绕过的单例：它把跨平台差异封装为 6 个极简方法，让插件无需关心 Windows/macOS/Linux 各自的数据组织习惯。核心要点可以归纳为：

• 三类持久目录的语义分工：缓存（可删）、配置（小、持久）、数据（大、持久），在 Windows/macOS 上配置与数据同目录，Linux 上遵循 XDG 分离。
• 项目级设置目录res://.godot/editor与全局目录并行的两级结构。
• 自包含模式通过._sc_/_sc_标记文件启用，配合is_self_contained()检测，实现真正的便携安装。
• 导出项目不可用是最大坑点，务必用Engine.has_singleton()防护。

相关阅读：File paths in Godot projects（res:///user://与编辑器数据路径全景）、class_os.rst（OS全局目录方法对比）、class_projectsettings.rst（use_custom_user_dir、use_hidden_project_data_directory等项目设置）。

• 文档
• 教程
• 游戏开发