Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

FileAccess¶

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

描述¶

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

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

func save(content):
    var file = FileAccess.open("user://save_game.dat", FileAccess.WRITE)
    file.store_string(content)

func load():
    var file = FileAccess.open("user://save_game.dat", FileAccess.READ)
    var content = file.get_as_text()
    return content

public void Save(string content)
{
    using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Write);
    file.StoreString(content);
}

public string Load()
{
    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 来解决这个问题。

教程¶

属性¶

bool	big_endian

方法¶

void	close ( )
bool	eof_reached ( ) const
bool	file_exists ( String path ) static
void	flush ( )
int	get_8 ( ) const
int	get_16 ( ) const
int	get_32 ( ) const
int	get_64 ( ) const
String	get_as_text ( bool skip_cr=false ) const
PackedByteArray	get_buffer ( int length ) const
PackedStringArray	get_csv_line ( String delim="," ) const
float	get_double ( ) const
Error	get_error ( ) const
PackedByteArray	get_file_as_bytes ( String path ) static
String	get_file_as_string ( String path ) static
float	get_float ( ) const
bool	get_hidden_attribute ( String file ) static
int	get_length ( ) const
String	get_line ( ) const
String	get_md5 ( String path ) static
int	get_modified_time ( String file ) static
Error	get_open_error ( ) static
String	get_pascal_string ( )
String	get_path ( ) const
String	get_path_absolute ( ) const
int	get_position ( ) const
bool	get_read_only_attribute ( String file ) static
float	get_real ( ) const
String	get_sha256 ( String path ) static
BitField<UnixPermissionFlags>	get_unix_permissions ( String file ) static
Variant	get_var ( bool allow_objects=false ) const
bool	is_open ( ) const
FileAccess	open ( String path, ModeFlags flags ) static
FileAccess	open_compressed ( String path, ModeFlags mode_flags, CompressionMode compression_mode=0 ) static
FileAccess	open_encrypted ( String path, ModeFlags mode_flags, PackedByteArray key ) static
FileAccess	open_encrypted_with_pass ( String path, ModeFlags mode_flags, String pass ) static
void	seek ( int position )
void	seek_end ( int position=0 )
Error	set_hidden_attribute ( String file, bool hidden ) static
Error	set_read_only_attribute ( String file, bool ro ) static
Error	set_unix_permissions ( String file, BitField<UnixPermissionFlags> permissions ) static
void	store_8 ( int value )
void	store_16 ( int value )
void	store_32 ( int value )
void	store_64 ( int value )
void	store_buffer ( PackedByteArray buffer )
void	store_csv_line ( PackedStringArray values, String delim="," )
void	store_double ( float value )
void	store_float ( float value )
void	store_line ( String line )
void	store_pascal_string ( String string )
void	store_real ( float value )
void	store_string ( String string )
void	store_var ( Variant value, bool full_objects=false )

枚举¶

enum ModeFlags:

ModeFlags READ = 1

打开文件进行读取操作。光标位于文件的开头。

ModeFlags WRITE = 2

打开文件进行写操作。如果文件不存在，则创建该文件，如果存在则截断。

ModeFlags READ_WRITE = 3

打开文件用于读写操作。不截断文件。光标位于文件的开头。

ModeFlags WRITE_READ = 7

打开文件进行读写操作。如果文件不存在，则创建该文件，如果存在则截断。光标位于文件的开头。

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 ( bool value )
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 不能用于检查是否有更多可用数据。要在有更多可用数据时循环，请使用：

while file.get_position() < file.get_length():
    # 读取数据

while (file.GetPosition() < file.GetLength())
{
    // 读取数据
}

bool file_exists ( String path ) 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 ( bool skip_cr=false ) const

以 String 形式返回整个文件。文本会按照 UTF-8 编码解析。

如果 skip_cr 为 true，解析 UTF-8 时会忽略回车符（\r，CR），因此只使用换行符（\n，LF）表示新一行的开始（Unix 规范）。

PackedByteArray get_buffer ( int length ) const

将文件中接下来的 length 个字节作为 PackedByteArray 返回。

PackedStringArray get_csv_line ( String delim="," ) 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 ( String path ) static

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

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

String get_file_as_string ( String path ) static

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

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

float get_float ( ) const

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

bool get_hidden_attribute ( String file ) static

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

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

int get_length ( ) const

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

String get_line ( ) const

将文件中的下一行作为 String 字符串返回。

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

String get_md5 ( String path ) static

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

int get_modified_time ( String file ) 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 ( String file ) static

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

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

float get_real ( ) const

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

String get_sha256 ( String path ) static

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

BitField<UnixPermissionFlags> get_unix_permissions ( String file ) static

返回文件的 UNIX 权限。

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

Variant get_var ( bool allow_objects=false ) const

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

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

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

bool is_open ( ) const

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

FileAccess open ( String path, ModeFlags flags ) static

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

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

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

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

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

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

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

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

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

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

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

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

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

void seek ( int position )

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

void seek_end ( int position=0 )

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

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

Error set_hidden_attribute ( String file, bool hidden ) static

设置文件 hidden 属性。

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

Error set_read_only_attribute ( String file, bool ro ) static

设置文件 read only 属性。

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

Error set_unix_permissions ( String file, BitField<UnixPermissionFlags> permissions ) static

设置文件的 UNIX 权限。

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

void store_8 ( int value )

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

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

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

void store_16 ( int value )

将一个整数以 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
}

void store_32 ( int value )

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

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

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

void store_64 ( int value )

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

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

void store_buffer ( PackedByteArray buffer )

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

void store_csv_line ( PackedStringArray values, String delim="," )

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

将使用 UTF-8 编码文本。

void store_double ( float value )

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

void store_float ( float value )

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

void store_line ( String line )

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

void store_pascal_string ( String string )

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

将使用 UTF-8 编码文本。

void store_real ( float value )

将浮点数存储在文件中。

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 ( Variant value, bool full_objects=false )

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

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

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