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 包中。如果使用 FileAccess，请确保通过在导入面板中将其导入模式更改为保留文件（按原样导出）来将文件包含在导出中；或者对于没有此选项的文件，请在导出对话框中更改非资源导出筛选器，加上文件的扩展名（例如 *.txt）。
注意：只有当进程“正常”退出时（例如通过单击窗口管理器的关闭按钮或按 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 方法。
FileAccess create_temp(mode_flags: int, prefix: String = "", extension: String = "", keep: bool = false) static 🔗
创建临时文件。该文件将在返回的 FileAccess 释放时释放。
如果 prefix 非空，则会将其添加为文件名的前缀，用 - 分隔。
如果 extension 非空，则会将其追加到临时文件名之后。
如果 keep 为 true，则在返回的 FileAccess 释放时不会删除该文件。
如果打开文件失败则返回 null，可以使用 get_open_error() 检查发生的错误。
如果文件光标已经读到了文件末尾，则返回 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。你可以使用 get_open_error() 来检查发生的错误。
String get_file_as_string(path: String) static 🔗
将整个 path 文件内容以 String 形式返回。文本被解释为 UTF-8 编码。
如果打开文件时发生错误，则返回空 String。可以使用 get_open_error() 来检查发生的错误。
将文件中接下来的 32 位作为浮点数返回。
将文件中接下来的 16 位作为半精度浮点数返回。
如果文件 hidden 属性已设置，则返回 true。
注意：该方法在 iOS、BSD、macOS 和 Windows 上实现。
返回文件的大小，单位为字节。如果是管道，则返回可以从管道中读取的字节数。
以 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() 调用的结果。
返回文件中按照 Pascal 格式保存的 String 字符串。
将按照 UTF-8 编码解析文本。
返回当前打开的文件的路径为String。
String get_path_absolute() const 🔗
返回当前打开的文件的绝对路径为String。
返回文件光标的位置。
bool get_read_only_attribute(file: String) static 🔗
如果文件 read only 属性已设置，则返回 true。
注意：此方法在 iOS、BSD、macOS 和 Windows 上实现。
将文件中接下来的若干位以浮点数形式返回。
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() 方法相同的解码机制。
警告：反序列化得到的对象可能包含被执行的代码。如果序列化的对象来自不受信任的来源，请不要使用这个选项，以避免潜在的安全威胁，如远程代码执行。
如果文件当前被打开，返回 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, iv: PackedByteArray = 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() 来检查发生的错误。
将文件大小修改为指定长度。文件必须使用允许写操作的模式打开。如果扩展了文件，则会追加 NUL 字符。如果截断了文件，则会丢弃从文件末尾到文件原长度之间的所有数据。
将文件的读/写光标改变到指定的位置（从文件开始的字节数）。
void seek_end(position: int = 0) 🔗
将文件的读/写光标改变到指定的位置（从文件的末端算起，以字节为单位）。
注意：这是一个偏移量，所以你应该使用负数，否则光标会在文件的末端。
设置文件 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 上实现。
将一个整数以 8 位形式存储在文件中。
注意：value 应该位于 [0, 255] 的区间内。任何其他的值都会溢出并环绕。
注意：出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 store_64()，或者手动转换（见 store_16() 的例子）。
将一个整数以 16 位形式存储到文件中。
注意：value 应该位于 [0, 2^16 - 1] 区间内。任何其他的值都会溢出并进行环绕。
注意：出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 store_64() 或者从区间 [-2^15, 2^15 - 1] 中存储一个有符号的整数（即保留一位作为符号），在读取时手动计算其符号。例如：
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
}
将一个整数以 32 位形式存储到文件中。
注意：value 应该位于 [0, 2^32 - 1] 区间内。任何其他的值都会溢出并环绕。
注意：出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 store_64()，或者手动转换（见 store_16() 的例子）。
将一个整数以 64 位形式存储到文件中。
注意：value 必须位于 [-2^63, 2^63 - 1] 的区间内（即有效的 int 值）。
注意：出错时，文件位置标识符的取值不确定。
bool store_buffer(buffer: PackedByteArray) 🔗
将给定的字节数组存储到文件中。
注意：出错时，文件位置标识符的取值不确定。
bool store_csv_line(values: PackedStringArray, delim: String = ",") 🔗
将给定的 PackedStringArray 作为 CSV（逗号分隔值）格式的行存储在文件中。你可以传递不同的分隔符 delim 以使用默认 ","（逗号）以外的其他分隔符。此分隔符的长度必须为一个字符。
将使用 UTF-8 编码文本。
注意：出错时，文件位置标识符的取值不确定。
bool store_double(value: float) 🔗
将一个浮点数以 64 位的形式存储到文件中。
注意：出错时，文件位置标识符的取值不确定。
bool store_float(value: float) 🔗
将一个浮点数以 32 位的形式存储到文件中。
注意：出错时，文件位置标识符的取值不确定。
bool store_half(value: float) 🔗
将一个半精度浮点数以 16 位的形式存储到文件中。
bool store_line(line: String) 🔗
将 line 存储到文件中，后加一个换行符（\n），文本编码为 UTF-8。
注意：出错时，文件位置标识符的取值不确定。
bool store_pascal_string(string: String) 🔗
将给定的 String 以 Pascal 格式存储在文件中（即同时存储字符串的长度）。
将使用 UTF-8 编码文本。
注意：出错时，文件位置标识符的取值不确定。
bool store_real(value: float) 🔗
将一个浮点数存储到文件中。
注意：出错时，文件位置标识符的取值不确定。
bool store_string(string: String) 🔗
将 string 存储到文件中，不带换行符（\n），文本编码为 UTF-8。
注意：本方法是用来写入文本文件的。字符串会被存储为 UTF-8 编码的缓冲区，不带字符串长度或末尾零，这意味着它不能被轻易加载回来。如果想在二进制文件中存储一个可检索的字符串，可以考虑改用 store_pascal_string()。对于从文本文件中检索字符串，可以使用 get_buffer(length).get_string_from_utf8()（如果知道长度）或 get_as_text()。
注意：出错时，文件位置标识符的取值不确定。
bool 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。
注意：出错时，文件位置标识符的取值不确定。