FileAccess

继承： RefCounted < Object

提供用于文件读写操作的方法。

描述

这个类可以用于在用户设备的文件系统中永久存储数据，也可以从中读取数据。适用于存储游戏存档数据或玩家配置文件。

下面是一个关于如何写入和读取文件的示例：

GDScriptC#

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 来解决这个问题。

教程

• 文件系统

• 运行时文件加载与保存

• 3D 体素演示

属性

方法

枚举

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

限制删除（粘性）比特位。

属性说明

bool big_endian 🔗

• void set_big_endian(value: bool)

• bool is_big_endian()

如果为 true，则文件用大端字节序读取。如果为 false，则文件以小端字节序读取。如果有疑问，请将其保留为 false，因为大多数文件都是用小端字节序编写的。

注意：big_endian 只与文件格式有关，与 CPU 类型无关。CPU 字节序不会影响写入文件的默认字节序。

注意：每当打开文件时，该选项总是被重置为 false。因此，必须在打开文件之后设置 big_endian，而不是之前。

方法说明

void close() 🔗

关闭当前打开的文件，阻止后续的读写操作。如果要将数据持久化到磁盘而不关闭文件，请使用 flush。

注意：**FileAccess** 被释放时会自动关闭，释放发生在离开作用域或被赋值为 null 时。在 C# 中，使用完后必须弃置该引用，可以使用 using 语句或直接调用 Dispose 方法。

bool eof_reached() const 🔗

如果文件光标已经读到了文件末尾，则返回 true。

注意：eof_reached() == false 不能用于检查是否有更多可用数据。要在有更多可用数据时循环，请使用：

GDScriptC#

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。否则，它会因不断的磁盘写入而降低性能。

int get_8() const 🔗

以整数形式返回文件中接下来的 8 位。请参阅 store_8，详细了解哪些值可以通过这种方式存储和检索。

int get_16() const 🔗

以整数形式返回文件中接下来的 16 位。请参阅 store_16，以获取有关可以通过这种方式存储和检索哪些值的详细信息。

int get_32() const 🔗

以整数形式返回文件中接下来的 32 位。请参阅store_32，以获取有关可以通过这种方式存储和检索哪些值的详细信息。

int get_64() const 🔗

以整数形式返回文件中接下来的 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""."

请注意第二行如何省略封闭的引号，因为它不包含分隔符。然而它可以很好地使用引号，它只是为了演示目的而没有编写。第三行必须为每个需要被解析为引号而不是文本值的末尾而使用 ""。

float get_double() const 🔗

将文件中接下来的 64 位作为浮点数返回。

Error get_error() const 🔗

返回试图执行操作时发生的最后一个错误。请与 Error 中的 ERR_FILE_* 常量比较。

PackedByteArray get_file_as_bytes(path: String) static 🔗

将整个 path 文件内容作为 PackedByteArray 返回，无需任何解码。

如果打开文件时发生错误，则返回空的 PackedByteArray。你可以使用 get_open_error 来检查发生的错误。

String get_file_as_string(path: String) static 🔗

将整个 path 文件内容以 String 形式返回。文本被解释为 UTF-8 编码。

如果打开文件时发生错误，则返回空 String。可以使用 get_open_error 来检查发生的错误。

float get_float() const 🔗

将文件中接下来的 32 位作为浮点数返回。

bool get_hidden_attribute(file: String) static 🔗

如果文件 hidden 属性已设置，则返回 true。

注意：该方法在 iOS、BSD、macOS 和 Windows 上实现。

int get_length() const 🔗

返回该文件的大小，单位为字节。

String get_line() const 🔗

以 String 的形式返回文件中的下一行。返回的字符串不包含换行符（\n）和回车符（\r），但是会包含开头和结尾的其他空白字符。

文本按照 UTF-8 编码规则进行解析。

String get_md5(path: String) static 🔗

返回一个给定路径文件的 MD5 字符串，如果失败则返回一个空的 String。

int get_modified_time(file: String) static 🔗

返回 file 的最后修改时间，使用 Unix 时间戳格式，出错时返回 0。这个 Unix 时间戳可以用 Time 单例转换为其他格式。

Error get_open_error() static 🔗

返回当前线程中最后一次 open 调用的结果。

String get_pascal_string() 🔗

返回文件中按照 Pascal 格式保存的 String 字符串。

将按照 UTF-8 编码解析文本。

String get_path() const 🔗

返回当前打开的文件的路径为String。

String get_path_absolute() const 🔗

返回当前打开的文件的绝对路径为String。

int get_position() const 🔗

返回文件光标的位置。

bool get_read_only_attribute(file: String) static 🔗

如果文件 read only 属性已设置，则返回 true。

注意：此方法在 iOS、BSD、macOS 和 Windows 上实现。

float get_real() const 🔗

将文件中接下来的若干位以浮点数形式返回。

String get_sha256(path: String) static 🔗

返回一个表示给定路径下文件的 SHA-256 String，失败时返回一个空的 String。

BitField[UnixPermissionFlags] get_unix_permissions(file: String) static 🔗

返回文件的 UNIX 权限。

注意：该方法在 iOS、Linux/BSD 和 macOS 上实现。

Variant get_var(allow_objects: bool = false) const 🔗

返回文件中的下一个 Variant 值。如果 allow_objects 为 true，则允许解码对象。

在内部，这使用与 @GlobalScope.bytes_to_var 方法相同的解码机制。

警告：反序列化得到的对象可能包含被执行的代码。如果序列化的对象来自不受信任的来源，请不要使用这个选项，以避免潜在的安全威胁，如远程代码执行。

bool is_open() const 🔗

如果文件当前被打开，返回 true。

FileAccess open(path: String, flags: ModeFlags) static 🔗

创建一个新的 FileAccess 对象，会根据标志来确定以写入还是读取模式打开文件。

如果打开文件失败，则返回 null 。你可以使用 get_open_error 来检查发生的错误。

FileAccess open_compressed(path: String, mode_flags: ModeFlags, compression_mode: CompressionMode = 0) static 🔗

创建一个新的 FileAccess 对象，并打开一个压缩文件以进行读取或写入。

注意：open_compressed 只能读取 Godot 保存的文件，不能读取第三方压缩格式。有关解决方法，请参阅 GitHub 问题 #28999。

如果打开文件失败，则返回 null。可以使用 get_open_error 来检查发生的错误。

FileAccess open_encrypted(path: String, mode_flags: ModeFlags, key: PackedByteArray) static 🔗

创建一个新的 FileAccess 对象，并以写入或读取模式打开一个加密文件。需要传入一个二进制密钥来加密/解密它。

注意：提供的密钥必须是 32 字节长。

如果打开文件失败，则返回 null。可以使用 get_open_error 来检查发生的错误。

FileAccess open_encrypted_with_pass(path: String, mode_flags: ModeFlags, pass: String) static 🔗

创建一个新的 FileAccess 对象，以写或读的模式打开一个加密文件。你需要传递一个密码来加密/解密它。

如果打开文件失败，则返回 null 。你可以使用 get_open_error 来检查发生的错误。

Error resize(length: int) 🔗

将文件大小修改为指定长度。文件必须使用允许写操作的模式打开。如果扩展了文件，则会追加 NUL 字符。如果截断了文件，则会丢弃从文件末尾到文件原长度之间的所有数据。

void seek(position: int) 🔗

将文件的读/写光标改变到指定的位置（从文件开始的字节数）。

void seek_end(position: int = 0) 🔗

将文件的读/写光标改变到指定的位置（从文件的末端算起，以字节为单位）。

注意：这是一个偏移量，所以你应该使用负数，否则光标会在文件的末端。

Error set_hidden_attribute(file: String, hidden: bool) static 🔗

设置文件 hidden 属性。

注意：该方法在 iOS、BSD、macOS 和 Windows 上实现。

Error set_read_only_attribute(file: String, ro: bool) static 🔗

设置文件 read only 属性。

注意：该方法在 iOS、BSD、macOS 和 Windows 上实现。

Error set_unix_permissions(file: String, permissions: BitField[UnixPermissionFlags]) static 🔗

设置文件的 UNIX 权限。

注意：该方法在 iOS、Linux/BSD 和 macOS 上实现。

void store_8(value: int) 🔗

将一个整数以 8 位形式存储在文件中。

注意：value 应该位于 [0, 255] 的区间内。任何其他的值都会溢出并环绕。

要存储有符号的整数，请使用 store_64，或者手动转换（见 store_16 的例子）。

void store_16(value: int) 🔗

将一个整数以 16 位形式存储在文件中。

注意：value 应该位于 [0, 2^16 - 1] 区间内。任何其他的值都会溢出并进行环绕。

要存储有符号的整数，请使用 store_64 或者从区间 [-2^15, 2^15 - 1] 中存储一个有符号的整数（即保留一位作为符号），在读取时手动计算其符号。例如：

GDScriptC#

const MAX_15B = 1 << 15
const MAX_16B = 1 << 16
func unsigned16_to_signed(unsigned):
    return (unsigned + MAX_15B) % MAX_16B - MAX_15B
func _ready():
    var f = FileAccess.open("user://file.dat", FileAccess.WRITE_READ)
    f.store_16(-42) # 发生环绕，存储 65494 (2^16 - 42)。
    f.store_16(121) # 在范围内，存储 121。
    f.seek(0) # 回到开头，读取存储的值。
    var read1 = f.get_16() # 65494
    var read2 = f.get_16() # 121
    var converted1 = unsigned16_to_signed(read1) # -42
    var converted2 = unsigned16_to_signed(read2) # 121

public override void _Ready()
{
    using var f = FileAccess.Open("user://file.dat", FileAccess.ModeFlags.WriteRead);
    f.Store16(unchecked((ushort)-42)); // 发生环绕，存储 65494 (2^16 - 42)。
    f.Store16(121); // 在范围内，存储 121。
    f.Seek(0); // 回到开头，读取存储的值。
    ushort read1 = f.Get16(); // 65494
    ushort read2 = f.Get16(); // 121
    short converted1 = (short)read1; // -42
    short converted2 = (short)read2; // 121
}

void store_32(value: int) 🔗

将一个整数以 32 位形式存储在文件中。

注意：value 应该位于 [0, 2^32 - 1] 区间内。任何其他的值都会溢出并环绕。

要存储有符号的整数，请使用 store_64，或者手动转换（见 store_16 的例子）。

void store_64(value: int) 🔗

将一个整数以 64 位形式存储在文件中。

注意：value 必须位于 [-2^63, 2^63 - 1] 的区间内（即有效的 int 值）。

void store_buffer(buffer: PackedByteArray) 🔗

在文件中存储给定的字节数组。

void store_csv_line(values: PackedStringArray, delim: String = “,”) 🔗

将给定的 PackedStringArray 作为 CSV（逗号分隔值）格式的行存储在文件中。你可以传递不同的分隔符 delim 以使用默认 ","（逗号）以外的其他分隔符。此分隔符的长度必须为一个字符。

将使用 UTF-8 编码文本。

void store_double(value: float) 🔗

将一个浮点数以 64 位形式存储在文件中。

void store_float(value: float) 🔗

将一个浮点数以 32 位形式存储在文件中。

void store_line(line: String) 🔗

将 line 附加到文件末尾，并在后面加上一个换行符（\n），将使用 UTF-8 编码文本。

void store_pascal_string(string: String) 🔗

将给定的 String 以 Pascal 格式存储在文件中（即同时存储字符串的长度）。

将使用 UTF-8 编码文本。

void store_real(value: float) 🔗

将浮点数存储在文件中。

void store_string(string: String) 🔗

将 string 追加到文件中，不带换行，且将文本编码为 UTF-8。

注意：本方法是用来写入文本文件的。字符串会被存储为 UTF-8 编码的缓冲区，不带字符串长度或末尾零，这意味着它不能被轻易加载回来。如果想在二进制文件中存储一个可检索的字符串，可以考虑改用 store_pascal_string。对于从文本文件中检索字符串，可以使用 get_buffer(length).get_string_from_utf8()（如果知道长度）或 get_as_text。

void store_var(value: Variant, full_objects: bool = false) 🔗

在文件中存储任何 Variant 值。如果 full_objects 为 true，则允许编码对象（并且可能包含代码）。

在内部，这使用与 @GlobalScope.var_to_bytes 方法相同的编码机制。

注意：并非所有属性都包括在内。只有配置了 @GlobalScope.PROPERTY_USAGE_STORAGE 标志集的属性才会被序列化。可以通过覆盖类中的 Object._get_property_list 方法来向属性添加新的使用标志。还可以通过调用 Object._get_property_list 来检查属性使用的配置方式。有关可能的使用标志，请参阅 PropertyUsageFlags。