API fs

fs

可选的原生文件系统模块。

脚本 API 参考 · 宿主 BuiltInModules

启用与导入

该模块默认禁用。宿主必须在构造引擎前添加 BuiltInModules.FileSystem：

using AuroraScript.Runtime.Package;

var options = EngineOptions.Default.WithBuiltIns(builtIns =>
    builtIns.Add(BuiltInModules.FileSystem));

脚本代码随后导入裸模块路径。fs 是导入别名，不是全局对象。

import fs from "fs";

每个路径参数均接受非空 string 或 Path。相对文件系统路径使用宿主进程的工作目录；若路径应相对于导入脚本，请使用 Path.baseModule(...)。

快速参考

Member	Returns	用途
readText(path)	string	读取文本文件。
readBytes(path)	UInt8Array	读取全部字节。
writeText(path, text)	boolean	创建或替换文本。
writeBytes(path, bytes)	boolean	创建或替换字节。
appendText(path, text)	boolean	追加文本。
appendBytes(path, bytes)	boolean	追加字节。
exist(path)	boolean	检测文件或目录是否存在。
isFile(path)	boolean	检测是否为文件。
isDir(path)	boolean	检测是否为目录。
size(path)	number	获取文件字节长度。
mkDir(path)	boolean	创建目录树。
dir(path)	string[]	列出顶层名称。
copy(source, destination, overwrite?)	boolean	复制文件或目录树。
move(source, destination, overwrite?)	boolean	移动文件或目录。
delete(path, recursive?)	boolean	删除文件或目录。

读写

fs.readText(path)

fs.readText(path: string|Path): string

使用 .NET 的 UTF-8 文本文件行为读取完整文本文件。

fs.readBytes(path)

fs.readBytes(path: string|Path): UInt8Array

将完整文件读入新的 UInt8Array。

fs.writeText(path, text)

fs.writeText(path: string|Path, text: string): boolean

创建或替换文本文件并返回 true。缺失的父目录不会自动创建。

fs.writeBytes(path, bytes)

fs.writeBytes(path: string|Path, bytes: UInt8Array): boolean

创建或替换二进制文件并返回 true。缺失的父目录不会自动创建。

fs.appendText(path, text)

fs.appendText(path: string|Path, text: string): boolean

追加文本并返回 true。若文件不存在则创建，但父目录必须存在。

fs.appendBytes(path, bytes)

fs.appendBytes(path: string|Path, bytes: UInt8Array): boolean

追加字节并返回 true。若文件不存在则创建，但父目录必须存在。

import fs from "fs";

export func save(root) {
    var file = new Path(root, "logs", "latest.txt");
    fs.mkDir(file.directoryName());
    fs.writeText(file, "started\n");
    return fs.appendText(file, "ready\n");
}

检查与目录

fs.exist(path)

fs.exist(path: string|Path): boolean

当文件或目录存在时返回 true。

fs.isFile(path)

fs.isFile(path: string|Path): boolean

仅对现有文件返回 true。

fs.isDir(path)

fs.isDir(path: string|Path): boolean

仅对现有目录返回 true。

三种存在性检测对缺失路径返回 false；当底层 .NET 存在性检查报告 false 时，不会区分缺失路径与不可访问路径。

fs.size(path)

fs.size(path: string|Path): number

将现有文件的字节长度作为脚本 number 返回。缺失的文件或目录路径会抛出 AuroraRuntimeException；不计算目录聚合大小。在 Number.MAX_SAFE_INTEGER 范围内整数精度完全精确。

fs.mkDir(path)

fs.mkDir(path: string|Path): boolean

创建目录及所有缺失的父目录。目录已存在或创建成功时返回 true。

fs.dir(path)

fs.dir(path: string|Path): string[]

仅返回直接子文件与子目录的名称。非递归。结果使用序数比较排序，因此顺序确定且与文化无关。

import fs from "fs";

export func inventory(directory) {
    return {
        exists: fs.isDir(directory),
        entries: fs.dir(directory)
    };
}

复制、移动与删除

fs.copy(source, destination, overwrite = false)

fs.copy(
    source: string|Path,
    destination: string|Path,
    overwrite?: boolean
): boolean

复制文件或递归复制目录树并返回 true。

• 除非 overwrite 显式为 true，否则拒绝已存在的目标。已存在的目标目录会被合并而非清空，因此无关的目标条目会保留。
• 目录不能复制到自身或其子代中。
• 目录符号链接/重解析点会被拒绝而非跟随。
• 文件复制要求目标父目录存在。目录复制会创建目标路径及缺失的父目录。

fs.move(source, destination, overwrite = false)

fs.move(
    source: string|Path,
    destination: string|Path,
    overwrite?: boolean
): boolean

移动文件或目录并返回 true。当 overwrite = true 时，已存在的目标文件会被覆盖，已存在的目标目录会在移动前删除。目录不能移动到自身或子代中。

fs.delete(path, recursive = false)

fs.delete(path: string|Path, recursive?: boolean): boolean

删除文件或目录。路径不存在时返回 false。非空目录除非 recursive 显式为 true，否则会失败。

import fs from "fs";

export func replaceTree(source, destination) {
    if (fs.exist(destination)) {
        fs.delete(destination, true);
    }
    return fs.copy(source, destination);
}

错误与安全

无效参数类型与文件系统失败会报告为 AuroraRuntimeException。消息会标识 fs 方法与受影响的路径，但脚本不应依赖特定于操作系统的消息文本。

fs 在宿主进程身份下授予直接访问权限；不受限于脚本源根目录。在受信任的宿主代码中验证或构造路径，使用 Path.isUnderRoot 进行应用级包含性检查，并对不可信脚本依赖进程/操作系统隔离。