Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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_diruser:// 文件夹会与 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/[自定义目录名称]

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

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

On HTML5 exports, user:// will refer to a virtual filesystem stored on the device via IndexedDB. (Interaction with the main filesystem can still be performed through the JavaScriptBridge singleton.)

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

你可以使用 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 或者其他普通用户只读的目录中)。