Godot 项目中的文件路径

本页面会讲解 Godot 项目中文件路径的工作原理。你会学到如何在项目中使用 res:// 和 user:// 标记来访问路径，以及 Godot 会在你的以及用户系统上的哪些位置存储项目和编辑器文件。

路径分隔符

为了让支持跨平台更方便，Godot 使用 UNIX 风格的路径分隔符（正斜杠 /）。在所有平台上都可以使用，包括 Windows。

在 Godot 里写的不是类似 C:\Projects\Game 的路径，而应该写 C:/Projects/Game。

有些路径相关的方法也支持 Windows 风格的路径分隔符（反斜杠\），不过需要写两个（\\），因为 \ 一般是用来进行字符转义的，有特殊含义。

这样就能够处理其他 Windows 程序所返回的路径了。我们仍然建议在你自己的代码里只使用正斜杠，这样才能确保一切都能正常工作。

访问项目文件夹中的文件（res://）

只要文件夹中存在名叫 project.godot 的文本文件，即便是空文件，Godot 也会认为这个文件夹中包含了一个项目。包含这个文件的文件夹是你的项目的根文件夹。

相对于这个文件夹的任何文件，都可以通过以 res:// 开头的路径访问，这个前缀代表“资源”（resource）。例如，在代码中，你可以通过 res://character.png 来访问位于项目根文件夹的 character.png 图片。

访问持久化用户数据（user://）

要存储持久化数据文件，比如玩家的存档、设置等，你会想要使用 user:// 作为路径前缀，而不是 res://。这是因为游戏运行时，项目的文件系统很可能是只读的。

user:// 前缀指向的是用户设备上的其他目录。与 res:// 不同，即便在导出后的项目中，user:// 指向的这个目录也会自动创建并且保证可写。

user:// 文件夹的位置由“项目设置”中的配置决定：

  • 默认情况下，user:// 文件夹是在编辑器数据路径中创建的 app_userdata/[项目名称] 文件夹。使用这一默认值的目的是让原型和测试项目能够在 Godot 的数据文件夹中达到自包含。

  • 如果“项目设置”中启用了 application/config/use_custom_user_dir，user:// 文件夹会与 Godot 编辑器的数据路径同级，即程序数据的标准位置。

    • 默认情况下，文件夹名称是从项目名称推导出来的，但可以使用 application/config/custom_user_dir_name 进行进一步的自定义。这个路径可以包含路径分隔符，那么比如你就可以把给定工作室的项目都分组到 工作室名称/游戏名称 这样的目录结构之下。

在桌面平台上，user:// 的实际目录路径为：

类型

位置

默认

Windows：%APPDATA%\Godot\app_userdata[项目名称]
macOS：~/Library/Application Support/Godot/app_userdata/[项目名称]
Linux：~/.local/share/godot/app_userdata/[项目名称]

自定义目录

Windows：%APPDATA%[项目名称]
macOS：~/Library/Application Support/Godot/[项目名称]
Linux：~/.local/share/godot/[项目名称]

自定义目录及名称

Windows：%APPDATA%[自定义目录名称]
macOS：~/Library/Application Support/[自定义目录名称]
Linux：~/.local/share/[自定义目录名称]

[项目名称] 基于的是项目设置中定义的应用名称，不过你可以使用特性标签来为不同平台单独进行覆盖。

在移动平台上，这个路径是与项目相关的，每个项目都不一样，并且出于安全原因无法被其他应用程序访问。

在 HTML5 导出中，user:// 会指向保存在设备的虚拟文件系统，这个文件系统使用 IndexedDB 实现。（仍然可以通过 JavaScriptBridge 与主文件系统交互。）

将路径转换为绝对路径或“本地”路径

你可以使用 ProjectSettings.globalize_path() 将类似 res://path/to/file.txt 的本地路径转换为操作系统的绝对路径。例如，可以使用 ProjectSettings.globalize_path() 在操作系统的文件管理器中通过 OS.shell_open() 打开“本地”路径，因为这个函数只接受原生操作系统路径。

要将操作系统绝对路径转换为以 res:// 或 user:// 开头的“本地”路径，请使用 ProjectSettings.localize_path()。只对指向项目根目录或者 user:// 文件夹中的文件或文件夹有效。

编辑器数据路径

根据平台的不同，编辑器会使用不同的路径来存储编辑器数据、编辑器设置、缓存。默认情况下，这些路径是：

类型

位置

编辑器数据

Windows：%APPDATA%\Godot\
macOS：~/Library/Application Support/Godot/
Linux：~/.local/share/godot/

编辑器设置

Windows：%APPDATA%\Godot\
macOS：~/Library/Application Support/Godot/
Linux：~/.config/godot/

缓存

Windows：%TEMP%\Godot\
macOS：~/Library/Caches/Godot/
Linux：~/.cache/godot/

  • 编辑器数据包含导出模板和具体项目数据。

  • 编辑器设置包含主编辑器设置的配置，以及各种针对用户的自定义信息（编辑器布局、功能配置、脚本模板等）。

  • 缓存包含编辑器生成的数据，或者临时存储的数据。当 Godot 关闭时可以放心地移除。

Godot 在所有平台上都遵守 XDG 基本目录规范。可以根据规范通过覆盖环境变量来更改编辑器和项目的数据路径。

备注

如果你使用的是 Flatpak 打包的 Godot，编辑器数据路径将位于 ~/.var/app/org.godotengine.godot/ 的子文件夹中。

自包含模式

如果你在编辑器二进制文件所在的目录下创建了名为 ._sc_ 或 _sc_ 的文件（macOS 编辑器 .app 捆绑包则是在 MacOS/Contents/ 下），Godot 就会开启自包含模式。这种模式下，Godot 会将所有编辑器数据、设置、缓存都写入一个与编辑器二进制文件位于同一目录中的名为 editor_data/ 的目录。你可以用它来创建便携安装的编辑器。

Steam 版本的 Godot 默认使用自包含模式。

备注

导出后的项目目前不支持自包含模式。要对相对于可执行文件路径的文件进行读写，请使用 OS.get_executable_path()。注意，只有可执行文件位于可写的位置时，才能够对可执行文件路径上的文件进行写操作（即不在 Program Files 或者其他普通用户只读的目录中）。