FileAccess
继承： RefCounted < Object
提供用于文件读写操作的方法。
描述
这个类可以用于在用户设备的文件系统中永久存储数据，也可以从中读取数据。适用于存储游戏存档数据或玩家配置文件。
示例：如何读写文件。《数据路径》文档中提到的用户数据文件夹中会存储一个名叫 "save_game.dat" 的文件：
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 实例拥有自己的文件游标，它是文件中下一次读/写操作将发生的位置（单位为字节）。诸如 get_8()、get_16()、store_8() 和 store_16() 等函数会将文件游标向前移动读/写的字节数。可以使用 seek() 或 seek_end() 将文件游标移动到特定位置，且可以使用 get_position() 获取其位置。
FileAccess 实例被释放时会关闭对应的文件。由于这个类继承自 RefCounted，不再使用实例时会自动触发该行为。可以使用 close() 在此之前显式关闭。在 C# 中引用必须手动释放，可以通过 using 语句或直接调用 Dispose 方法来完成。
注意：要在导出后访问项目资源，建议使用 ResourceLoader 而不是 FileAccess，因为有些文件已被转换为特定于引擎的格式，并且它们的原始源文件可能并不存在于导出的 PCK 包中。如果使用 FileAccess，请确保通过在导入面板中将其导入模式更改为保留文件（按原样导出）来将文件包含在导出中；或者对于没有此选项的文件，请在导出对话框中更改非资源导出筛选器，加上文件的扩展名（例如 *.txt）。
注意：只有当进程“正常”退出时（例如通过单击窗口管理器的关闭按钮或按 Alt + F4），文件才会自动关闭。如果在项目运行时按 F8 停止项目执行，则不会关闭文件，因为游戏进程将被中止。可以通过定期调用 flush() 来解决这个问题。
教程
属性
方法
枚举
enum ModeFlags: 🔗
ModeFlags READ = 1
打开文件进行读取操作。文件游标位于文件的开头。
ModeFlags WRITE = 2
Opens the file for write operations. If the file exists, it is truncated to zero length and its contents are cleared. Otherwise, it is created.
Note: When creating a file it must be in an already existing directory. To recursively create directories for a file path, see DirAccess.make_dir_recursive().
ModeFlags READ_WRITE = 3
打开文件进行读写操作。不会截断文件。文件游标位于文件的开头。
ModeFlags WRITE_READ = 7
Opens the file for read and write operations. If the file exists, it is truncated to zero length and its contents are cleared. Otherwise, it is created. The file cursor is positioned at the beginning of the file.
Note: When creating a file it must be in an already existing directory. To recursively create directories for a file path, see 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，而不是之前。
方法说明
void close() 🔗
关闭当前打开的文件，阻止后续的读写操作。如果要将数据持久化到磁盘而不关闭文件，请使用 flush()。
注意：FileAccess 被释放时会自动关闭，释放发生在离开作用域或被赋值为 null 时。在 C# 中，使用完后必须弃置该引用，可以使用 using 语句或直接调用 Dispose 方法。
FileAccess create_temp(mode_flags: ModeFlags, 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 位。文件游标前进 1 个字节。请参阅 store_8()，详细了解哪些值可以通过这种方式存储和检索。
以整数形式返回文件中接下来的 16 位。文件游标前进 2 个字节。请参阅 store_16()，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
以整数形式返回文件中接下来的 32 位。文件游标前进 4 个字节。请参阅 store_32()，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
以整数形式返回文件中接下来的 64 位。文件游标前进 8 个字节。请参阅 store_64()，以获取有关可以通过这种方式存储和检索哪些值的详细信息。
int get_access_time(file: String) static 🔗
返回文件 file 的最后修改时间，使用 Unix 时间戳格式，出错时返回 0。这个 Unix 时间戳可以用 Time 单例转换为其他格式。
Returns the whole file as a String. Text is interpreted as being UTF-8 encoded. This ignores the file cursor and does not affect it.
PackedByteArray get_buffer(length: int) const 🔗
将文件中接下来的 length 个字节作为 PackedByteArray 返回。文件游标前进 length 个字节。
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 位作为浮点数返回。文件游标前进 8 个字节。
返回试图执行操作时发生的最后一个错误。请与 Error 中的 ERR_FILE_* 常量比较。
PackedByteArray get_extended_attribute(file: String, attribute_name: String) static 🔗
Reads the file extended attribute with name attribute_name as a byte array.
Note: This method is implemented on Linux, macOS, and Windows.
Note: Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
Note: On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
Note: On Windows, alternate data streams are used to store extended attributes.
String get_extended_attribute_string(file: String, attribute_name: String) static 🔗
Reads the file extended attribute with name attribute_name as a UTF-8 encoded string.
Note: This method is implemented on Linux, macOS, and Windows.
Note: Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
Note: On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
Note: On Windows, alternate data streams are used to store extended attributes.
PackedStringArray get_extended_attributes_list(file: String) static 🔗
Returns a list of file extended attributes.
Note: This method is implemented on Linux, macOS, and Windows.
Note: Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
Note: On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
Note: On Windows, alternate data streams are used to store extended attributes.
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 位作为浮点数返回。文件游标前进 4 个字节。
将文件中接下来的 16 位作为半精度浮点数返回。文件游标前进 2 个字节。
Returns true if the hidden attribute is set on the file at the given path.
Note: This method is implemented on iOS, BSD, macOS, and 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，即字符串的长度在开头显式存储。见 store_pascal_string()。可能包含换行符。文件游标前进至读取的字节之后。
文本按照 UTF-8 编码规则进行解析。
返回当前打开的文件的路径为String。
String get_path_absolute() const 🔗
返回当前打开的文件的绝对路径为String。
返回文件游标的位置，单位为字节，相对于文件的开头。文件读写游标由 seek() 和 seek_end() 设置，读写操作会导致游标前进。
bool get_read_only_attribute(file: String) static 🔗
Returns true if the read only attribute is set on the file at the given path.
Note: This method is implemented on iOS, BSD, macOS, and Windows.
返回文件中后续数据构成的一个浮点数。文件游标前进 4 个或 8 个字节，取决于保存文件的 Godot 构建所使用的精度。
如果保存文件的是使用 precision=single 编译的 Godot 构建（默认），则会从文件中读取 32 位。否则如果是使用 precision=double 编译的，那么读取的就是 64 位。
String get_sha256(path: String) static 🔗
返回一个表示给定路径下文件的 SHA-256 String，失败时返回一个空的 String。
int get_size(file: String) static 🔗
Returns the size of the file at the given path, in bytes, or -1 on error.
BitField[UnixPermissionFlags] get_unix_permissions(file: String) static 🔗
Returns the UNIX permissions of the file at the given path.
Note: This method is implemented on iOS, Linux/BSD, and macOS.
Variant get_var(allow_objects: bool = false) const 🔗
返回文件中的下一个 Variant 值。如果 allow_objects 为 true，则允许解码对象。这会使文件光标前进读取的字节数。
在内部，这使用与 @GlobalScope.bytes_to_var() 方法相同的解码机制，如在二进制序列化 API 文档中所述。
警告：反序列化得到的对象可能包含被执行的代码。如果序列化的对象来自不受信任的来源，请不要使用这个选项，以避免潜在的安全威胁，如远程代码执行。
如果文件当前被打开，返回 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() 来检查发生的错误。
Error remove_extended_attribute(file: String, attribute_name: String) static 🔗
Removes file extended attribute with name attribute_name.
Note: This method is implemented on Linux, macOS, and Windows.
Note: Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
Note: On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
Note: On Windows, alternate data streams are used to store extended attributes.
将文件大小修改为指定长度。文件必须使用允许写操作的模式打开。如果扩展了文件，则会追加 NUL 字符。如果截断了文件，则会丢弃从文件末尾到文件原长度之间的所有数据。
Sets the file cursor to the specified position in bytes, from the beginning of the file. This changes the value returned by get_position().
void seek_end(position: int = 0) 🔗
Sets the file cursor to the specified position in bytes, from the end of the file. This changes the value returned by get_position().
Note: This is an offset, so you should use negative numbers otherwise the file cursor will be at the end of the file.
Error set_extended_attribute(file: String, attribute_name: String, data: PackedByteArray) static 🔗
Writes file extended attribute with name attribute_name as a byte array.
Note: This method is implemented on Linux, macOS, and Windows.
Note: Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
Note: On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
Note: On Windows, alternate data streams are used to store extended attributes.
Error set_extended_attribute_string(file: String, attribute_name: String, data: String) static 🔗
Writes file extended attribute with name attribute_name as a UTF-8 encoded string.
Note: This method is implemented on Linux, macOS, and Windows.
Note: Extended attributes support depends on the file system. Attributes will be lost when the file is moved between incompatible file systems.
Note: On Linux, only "user" namespace attributes are accessible, namespace prefix should not be included.
Note: On Windows, alternate data streams are used to store extended attributes.
设置文件 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 位形式存储在文件中。文件游标前进 1 个字节。如果操作成功则返回 true。
注意：value 应该位于 [0, 255] 的区间内。任何其他的值都会溢出并环绕。
注意：出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 store_64()，或者手动转换（见 store_16() 的例子）。
将一个整数以 16 位形式存储到文件中。文件游标前进 2 个字节。如果操作成功则返回 true。
注意：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 位形式存储到文件中。文件游标前进 4 个字节。如果操作成功则返回 true。
注意：value 应该位于 [0, 2^32 - 1] 区间内。任何其他的值都会溢出并环绕。
注意：出错时，文件位置标识符的取值不确定。
要存储有符号的整数，请使用 store_64()，或者手动转换（见 store_16() 的例子）。
将一个整数以 64 位形式存储到文件中。文件游标前进 8 个字节。如果操作成功则返回 true。
注意：value 必须位于 [-2^63, 2^63 - 1] 的区间内（即有效的 int 值）。
注意：出错时，文件位置标识符的取值不确定。
bool store_buffer(buffer: PackedByteArray) 🔗
将给定的字节数组存储在文件中。文件游标前进写入的字节数。如果操作成功则返回 true。
注意：出错时，文件位置标识符的取值不确定。
bool store_csv_line(values: PackedStringArray, delim: String = ",") 🔗
Stores the given PackedStringArray in the file as a line formatted in the CSV (Comma-Separated Values) format. You can pass a different delimiter delim to use other than the default "," (comma). This delimiter must be one-character long.
Text will be encoded as UTF-8. Returns true if the operation is successful.
Note: If an error occurs, the resulting value of the file position indicator is indeterminate.
bool store_double(value: float) 🔗
将一个浮点数以 64 位的形式存储到文件中。文件游标前进 8 个字节。如果操作成功则返回 true。
注意：出错时，文件位置标识符的取值不确定。
bool store_float(value: float) 🔗
将一个浮点数以 32 位的形式存储到文件中。文件游标前进 4 个字节。如果操作成功则返回 true。
注意：出错时，文件位置标识符的取值不确定。
bool store_half(value: float) 🔗
将一个半精度浮点数以 16 位的形式存储到文件中。文件游标前进 2 个字节。如果操作成功则返回 true。
注意：出错时，文件位置标识符的取值不确定。
bool store_line(line: String) 🔗
将 line 存储到文件中，后跟一个换行符（\n），文本使用 UTF-8 编码。文件游标前进该行长度，至换行符后。写入的字节数取决于 UTF-8 编码后的字节，可能与 String.length() 不同，后者计算的是 UTF-32 码位的数量。如果操作成功则返回 true。
注意：出错时，文件位置标识符的取值不确定。
bool store_pascal_string(string: String) 🔗
将给定的 String 作为一行存储到文件中，使用 Pascal 格式（即同时存储字符串的长度）。文本使用 UTF-8 编码。文件游标的前进量为写入的字节数，取决于 UTF-8 编码后的字节，可能与 String.length() 不同，后者计算的是 UTF-32 码位的数量。如果操作成功则返回 true。
注意：出错时，文件位置标识符的取值不确定。
bool store_real(value: float) 🔗
将一个浮点数存储到文件中。文件游标前进 4 个或 8 个字节，取决于当前 Godot 构建所使用的精度。
如果所用的 Godot 构建在编译时使用了 precision=single 选项（默认），则该方法保存的是 32 位 float。否则如果编译时使用了 precision=double 选项，则保存的是 64 位 float。如果操作成功则返回 true。
注意：出错时，文件位置标识符的取值不确定。
bool store_string(string: String) 🔗
将 string 存储到文件中，不带换行符（\n），文本使用 UTF-8 编码。文件游标的前进量为 UTF-8 编码后的字节数，可能与 String.length() 不同，后者计算的是 UTF-32 码位的数量。如果操作成功则返回 true。
注意：该方法适用于写入文本文件。字符串以 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，则允许将对象进行编码（可能包含代码）。文件游标的前进量为写入的字节数。如果操作成功则返回 true。
内部使用的编码机制与 @GlobalScope.var_to_bytes() 方法相同，见《二进制序列化 API 》文档。
注意：不是所有属性都会包含在内。只会对设置了 @GlobalScope.PROPERTY_USAGE_STORAGE 标志的属性进行序列化。在你的类中覆盖 Object._get_property_list() 可以为属性添加新的用法标志。你也可以调用 Object._get_property_list() 查看属性用法的设置情况。可能的用法标志见 PropertyUsageFlags。
注意：出错时，文件位置标识符的取值不确定。