Godot 项目中的文件路径

This page explains how file paths work inside Godot projects. You will learn how to access paths in your projects using the res:// and user:// notations, and where Godot stores project and editor files on your and your users’ systems.

路径分隔符

To make supporting multiple platforms easier, Godot uses UNIX-style path separators (forward slash /). These work on all platforms, including Windows.

Instead of writing paths like C:\Projects\Game, in Godot, you should write C:/Projects/Game.

Windows-style path separators (backward slash \) are also supported in some path-related methods, but they need to be doubled (\\), as \ is normally used as an escape for characters with a special meaning.

This makes it possible to work with paths returned by other Windows applications. We still recommend using only forward slashes in your own code to guarantee that everything will work as intended.

Accessing files in the project folder (res://)

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

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

Accessing persistent user data (user://)

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

The user:// prefix points to a different directory on the user’s device. Unlike res://, the directory pointed at by user:// is created automatically and guaranteed to be writable to, even in an exported project.

The location of the user:// folder depends on what is configured in the Project Settings:

  • By default, the user:// folder is created within Godot’s editor data path in the app_userdata/[project_name] folder. This is the default so that prototypes and test projects stay self-contained within Godot’s data folder.

  • If application/config/use_custom_user_dir is enabled in the Project Settings, the user:// folder is created next to Godot’s editor data path, i.e. in the standard location for applications data.

    • By default, the folder name will be inferred from the project name, but it can be further customized with application/config/custom_user_dir_name. This path can contain path separators, so you can use it e.g. to group projects of a given studio with a Studio Name/Game Name structure.

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

类型

位置

Default

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

Custom dir

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

Custom dir and name

Windows: %APPDATA%[custom_user_dir_name]
macOS: ~/Library/Application Support/[custom_user_dir_name]
Linux: ~/.local/share/[custom_user_dir_name]

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

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

在 HTML5 导出中，user:// 会指向设备上由 IndexedDB 实现的虚拟文件系统。（与主文件系统的交互仍然可以通过 JavaScript 进行。）

Converting paths to absolute paths or “local” paths

You can use ProjectSettings.globalize_path() to convert a “local” path like res://path/to/file.txt to an absolute OS path. For example, ProjectSettings.globalize_path() can be used to open “local” paths in the OS file manager using OS.shell_open() since it only accepts native OS paths.

To convert an absolute OS path to a “local” path starting with res:// or user://, use ProjectSettings.localize_path(). This only works for absolute paths that point to files or folders in your project’s root or user:// folders.

编辑器数据路径

The editor uses different paths for editor data, editor settings, and cache, depending on the platform. By default, these paths are:

类型

位置

Editor data

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

Editor settings

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

缓存

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

  • Editor data contains export templates and project-specific data.

  • Editor settings contains the main editor settings configuration file as well as various other user-specific customizations (editor layouts, feature profiles, script templates, etc.).

  • Cache contains data generated by the editor, or stored temporarily. It can safely be removed when Godot is closed.

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

备注

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

自包含模式

If you create a file called ._sc_ or _sc_ in the same directory as the editor binary (or in MacOS/Contents/ for a macOS editor .app bundle), Godot will enable self-contained mode. This mode makes Godot write all editor data, settings, and cache to a directory named editor_data/ in the same directory as the editor binary. You can use it to create a portable installation of the editor.

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

备注

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