Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
FileAccess¶
继承： RefCounted < Object
提供用于文件读写操作的方法。
描述¶
这个类可以用于在用户设备的文件系统中永久存储数据，也可以从中读取数据。适用于存储游戏存档数据或玩家配置文件。
下面是一个关于如何写入和读取文件的示例：
func save_to_file(content):
var file = FileAccess.open("user://save_game.dat", FileAccess.WRITE)
file.store_string(content)
func load_from_file():
var file = FileAccess.open("user://save_game.dat", FileAccess.READ)
var content = file.get_as_text()
return content
public void SaveToFile(string content)
{
using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Write);
file.StoreString(content);
}
public string LoadFromFile()
{
using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Read);
string content = file.GetAsText();
return content;
}
在上面的例子中，文件将被保存在数据路径文件中指定的用户数据文件夹中。
FileAccess 会在释放时关闭，超出作用于、赋值为 null 等情况都会导致释放。可以使用 close 在此之前显式关闭。在 C# 中，引用必须手动释放，可以通过 using 语句或直接调用 Dispose 方法来完成。
注意：要在导出后访问项目资源，建议使用 ResourceLoader 而不是 FileAccess，因为有些文件已被转换为特定于引擎的格式，并且它们的原始源文件可能并不存在于导出的 PCK 包中。
注意：只有当进程“正常”退出时（例如通过单击窗口管理器的关闭按钮或按 Alt + F4），文件才会自动关闭。如果在项目运行时按 F8 停止项目执行，则不会关闭文件，因为游戏进程将被杀死。可以通过定期调用 flush 来解决这个问题。
教程¶
属性¶
方法¶
枚举¶
enum ModeFlags: 🔗
ModeFlags READ = 1
打开文件进行读取操作。光标位于文件的开头。
ModeFlags WRITE = 2
打开文件进行写操作。如果文件不存在则会创建该文件，如果存在则会截断。
注意：创建文件必须在已有目录中执行。如果要递归创建文件路径中的目录，见 DirAccess.make_dir_recursive。
ModeFlags READ_WRITE = 3
打开文件用于读写操作。不截断文件。光标位于文件的开头。
ModeFlags WRITE_READ = 7
打开文件进行读写操作。如果文件不存在则会创建该文件，如果存在则会截断。光标位于文件的开头。
注意：创建文件必须在已有目录中执行。如果要递归创建文件路径中的目录，见 DirAccess.make_dir_recursive。
enum CompressionMode: 🔗
CompressionMode COMPRESSION_FASTLZ = 0
使用 FastLZ 压缩方法。
CompressionMode COMPRESSION_DEFLATE = 1
使用 DEFLATE 压缩方法。
CompressionMode COMPRESSION_ZSTD = 2
使用 Zstandard 压缩方法。
CompressionMode COMPRESSION_GZIP = 3
使用 gzip 压缩方法。
CompressionMode COMPRESSION_BROTLI = 4
使用 brotli 压缩方法（仅支持解压缩）。
flags UnixPermissionFlags: 🔗
UnixPermissionFlags UNIX_READ_OWNER = 256
读取所有者比特位。
UnixPermissionFlags UNIX_WRITE_OWNER = 128
写入所有者比特位。
UnixPermissionFlags UNIX_EXECUTE_OWNER = 64
执行所有者比特位。
UnixPermissionFlags UNIX_READ_GROUP = 32
读取组比特位。
UnixPermissionFlags UNIX_WRITE_GROUP = 16
写入组比特位。
UnixPermissionFlags UNIX_EXECUTE_GROUP = 8
执行组比特位。
UnixPermissionFlags UNIX_READ_OTHER = 4
读取其他比特位。
UnixPermissionFlags UNIX_WRITE_OTHER = 2
写入其他比特位。
UnixPermissionFlags UNIX_EXECUTE_OTHER = 1
执行其他比特位。
UnixPermissionFlags UNIX_SET_USER_ID = 2048
在执行比特位上设置用户 ID 。
UnixPermissionFlags UNIX_SET_GROUP_ID = 1024
在执行位上设置组 ID。
UnixPermissionFlags UNIX_RESTRICTED_DELETE = 512
限制删除（粘性）比特位。
属性说明¶
如果为 true，则文件用大端字节序读取。如果为 false，则文件以小端字节序读取。如果有疑问，请将其保留为 false，因为大多数文件都是用小端字节序编写的。
注意：big_endian 只与文件格式有关，与 CPU 类型无关。CPU 字节序不会影响写入文件的默认字节序。
注意：每当打开文件时，该选项总是被重置为 false。因此，必须在打开文件之后设置 big_endian，而不是之前。
方法说明¶
void close() 🔗
关闭当前打开的文件，阻止后续的读写操作。如果要将数据持久化到磁盘而不关闭文件，请使用 flush。
注意：FileAccess 被释放时会自动关闭，释放发生在离开作用域或被赋值为 null 时。在 C# 中，使用完后必须弃置该引用，可以使用 using 语句或直接调用 Dispose 方法。
如果文件光标已经读到了文件末尾，则返回 true。
注意：eof_reached() == false 不能用于检查是否有更多可用数据。要在有更多可用数据时循环，请使用：
while file.get_position() < file.get_length():
# 读取数据
while (file.GetPosition() < file.GetLength())
{
// 读取数据
}
bool file_exists(path: String) static 🔗
如果文件存在于给定路径中，则返回 true。
注意：许多资源类型是导入的（例如纹理或声音文件），它们的源资产不会包含在导出的游戏中，因为只使用导入的版本。有关考虑资源重新映射的替代方法，请参阅 ResourceLoader.exists。
对于非静态的相对等效项，请使用 DirAccess.file_exists。
void flush() 🔗
将文件的缓冲区写入磁盘。当关闭文件时，会自动进行刷新。这意味着你不需要在关闭文件前手动调用 flush。尽管如此，即使项目崩溃而不是正常关闭，调用 flush 仍可用于确保数据安全。
注意：只有在你真正需要的时候才调用 flush。否则，它会因不断的磁盘写入而降低性能。
以整数形式返回文件中接下来的 8 位。请参阅 store_8，详细了解哪些值可以通过这种方式存储和检索。
以整数形式返回文件中接下来的 16 位。请参阅 store_16，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
以整数形式返回文件中接下来的 32 位。请参阅store_32，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
以整数形式返回文件中接下来的 64 位。请参阅 store_64，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
String get_as_text(skip_cr: bool = false) const 🔗
以 String 形式返回整个文件。文本会按照 UTF-8 编码解析。
如果 skip_cr 为 true，解析 UTF-8 时会忽略回车符（\r，CR），因此只使用换行符（\n，LF）表示新一行的开始（Unix 规范）。
PackedByteArray get_buffer(length: int) const 🔗
将文件中接下来的 length 个字节作为 PackedByteArray 返回。
PackedStringArray get_csv_line(delim: String = ",") const 🔗
以 CSV（逗号分隔值）格式返回文件的下一个值。可以传递不同的分隔符 delim，以使用默认 ","（逗号）以外的其他分隔符。这个分隔符必须为一个字符长，且不能是双引号。
文本被解析为 UTF-8 编码。如果文本值包含分隔符，则它们必须用双引号引起来。文本值中的双引号可以通过将它们的出现次数加倍来转义。
例如，以下 CSV 行是有效的，每行将被正确解析为两个字符串：
Alice,"Hello, Bob!"
Bob,Alice! What a surprise!
Alice,"I thought you'd reply with ""Hello, world""."
请注意第二行如何省略封闭的引号，因为它不包含分隔符。然而它可以很好地使用引号，它只是为了演示目的而没有编写。第三行必须为每个需要被解析为引号而不是文本值的末尾而使用 ""。
将文件中接下来的 64 位作为浮点数返回。
返回试图执行操作时发生的最后一个错误。请与 Error 中的 ERR_FILE_* 常量比较。
PackedByteArray get_file_as_bytes(path: String) static 🔗
将整个 path 文件内容作为 PackedByteArray 返回，无需任何解码。
如果打开文件时发生错误，则返回空的 PackedByteArray。你可以使用