FS 模块

FS 模块为 XScript 提供文件系统操作功能,支持文件和目录的读取、写入、删除等操作。

功能特性

文件操作 - 读取、写入、复制、删除文件

目录操作 - 创建、删除、遍历目录

路径处理 - 路径解析和拼接

文件监听 - 监听文件变化

流式操作 - 大文件流式读写

权限管理 - 文件权限设置

同步/异步 - 支持同步和异步操作

基本使用

引入模块

文件读取

文件写入

文件操作

目录操作

路径操作

流式读写

文件监听

API 参考

文件读写

`fs.readFileSync(path, encoding)`

同步读取文件。

参数:

path (string) - 文件路径

encoding (string) - 编码,默认返回 Buffer

返回: (string|Buffer) 文件内容

`fs.writeFileSync(path, data, options)`

同步写入文件。

参数:

path (string) - 文件路径

data (string|Buffer) - 要写入的内容

options (object) - 选项

encoding (string) - 编码,默认 'utf8'

mode (number) - 文件权限

flag (string) - 文件系统标志

`fs.appendFileSync(path, data)`

追加内容到文件。

`fs.copyFileSync(src, dest)`

复制文件。

`fs.unlinkSync(path)`

删除文件。

目录操作

`fs.mkdirSync(path, options)`

创建目录。

参数:

path (string) - 目录路径

options (object) - 选项

recursive (boolean) - 递归创建

`fs.readdirSync(path, options)`

读取目录内容。

返回: (Array <string> ) 文件和目录名数组

`fs.rmdirSync(path)`

删除目录。

`fs.rmSync(path, options)`

删除文件或目录。

参数:

options.recursive (boolean) - 递归删除

options.force (boolean) - 强制删除

文件信息

`fs.statSync(path)`

获取文件信息。

返回: (Stats) 文件状态对象

size - 文件大小(字节)

mtime - 修改时间

isFile() - 是否是文件

isDirectory() - 是否是目录

`fs.existsSync(path)`

检查文件或目录是否存在。

返回: (boolean) 是否存在

实际应用场景

日志写入

批量处理文件

文件备份

目录树遍历

配置文件管理

最佳实践

错误处理 - 始终处理文件操作错误

使用异步 - 大文件操作使用异步方法

流式处理 - 超大文件使用流

路径规范 - 使用 path 模块处理路径

权限检查 - 操作前检查文件权限

及时关闭 - 使用流后及时关闭

编码指定 - 明确指定文件编码

常见错误

错误码	说明	解决方案
ENOENT	文件不存在	检查路径是否正确
EACCES	权限不足	检查文件权限
EISDIR	目标是目录	使用目录操作方法
EEXIST	文件已存在	检查或删除现有文件

扩展 API（XScript 特有）

除了标准的 Node.js fs 模块 API 外，XScript 还提供了一些额外的实用方法：

路径操作

`fs.join(path1, path2)`

拼接两个路径。

参数:

path1 (string) - 第一个路径

path2 (string) - 第二个路径

返回: (string) 拼接后的路径

`fs.parent(path)`

获取路径的父目录。

参数:

path (string) - 文件或目录路径

返回: (string) 父目录路径

目录操作

`fs.dir(path)`

读取目录内容（返回详细信息）。

参数:

path (string) - 目录路径

返回: (Array <Object>) 包含文件详细信息的数组，每个对象包含：

name (string) - 文件或目录名

isDir (boolean) - 是否是目录

size (number) - 文件大小（字节）

mode (number) - 文件权限模式

modTime (number) - 修改时间（Unix 时间戳）

文件操作

`fs.read(path)`

读取文件内容（返回 Buffer）。

参数:

path (string) - 文件路径

返回: (Buffer) 文件内容

`fs.write(content, path)`

写入文件（自定义参数顺序）。

参数:

content (string|Buffer) - 要写入的内容

path (string) - 文件路径

返回: (boolean) 是否成功

`fs.writeFrom(conn, path)`

从流（如网络连接）读取数据并写入文件。

参数:

conn (net.Conn) - 网络连接或流

path (string) - 目标文件路径

返回: (boolean) 是否成功

`fs.append(content, path)`

追加内容到文件（自定义参数顺序）。

参数:

content (string|Buffer) - 要追加的内容

path (string) - 文件路径

返回: (boolean) 是否成功

`fs.delete(path)`

删除文件或目录（递归删除）。

参数:

path (string) - 文件或目录路径

返回: (boolean) 是否成功

`fs.move(oldPath, newPath)`

移动或重命名文件。

参数:

oldPath (string) - 原路径

newPath (string) - 新路径

返回: (boolean) 是否成功

文件信息

`fs.isDir(path)`

判断路径是否是目录。

参数:

path (string) - 路径

返回: (boolean) 是否是目录

`fs.pathInfo(path)`

获取文件或目录的详细信息。

参数:

path (string) - 路径

返回: (FileInfo) 文件信息对象

工作目录

`fs.cwd()`

获取当前工作目录。

返回: (string) 当前工作目录路径

`fs.chdir(path)`

改变当前工作目录。

参数:

path (string) - 新的工作目录路径

返回: (boolean) 是否成功

`fs.userHomePath()`

获取用户主目录路径。

返回: (string) 用户主目录路径

API 兼容性说明

本模块同时支持：

Node.js 标准 API - readFileSync(), writeFileSync(), appendFileSync(), copyFileSync(), unlinkSync(), renameSync(), mkdirSync(), rmdirSync(), rmSync(), readdirSync(), statSync(), existsSync()

XScript 扩展 API - read(), write(), append(), delete(), move(), dir(), join(), parent(), isDir(), pathInfo(), cwd(), chdir(), userHomePath(), writeFrom()

您可以根据需要选择使用标准 API 或扩展 API。扩展 API 提供了更简洁的接口和一些额外功能。

fs

FS 模块#

功能特性#

基本使用#

引入模块#

文件读取#

文件写入#

文件操作#

目录操作#

路径操作#

流式读写#

文件监听#

API 参考#

文件读写#

fs.readFileSync(path, encoding)#

fs.writeFileSync(path, data, options)#

fs.appendFileSync(path, data)#

fs.copyFileSync(src, dest)#

fs.unlinkSync(path)#

目录操作#

fs.mkdirSync(path, options)#

fs.readdirSync(path, options)#

fs.rmdirSync(path)#

fs.rmSync(path, options)#

文件信息#

fs.statSync(path)#

fs.existsSync(path)#

实际应用场景#

日志写入#

批量处理文件#

文件备份#

目录树遍历#

配置文件管理#

最佳实践#

常见错误#

扩展 API（XScript 特有）#

路径操作#

fs.join(path1, path2)#

fs.parent(path)#

目录操作#

fs.dir(path)#

文件操作#

fs.read(path)#

fs.write(content, path)#

fs.writeFrom(conn, path)#

fs.append(content, path)#

fs.delete(path)#

fs.move(oldPath, newPath)#

文件信息#

fs.isDir(path)#

fs.pathInfo(path)#

工作目录#

fs.cwd()#

fs.chdir(path)#

fs.userHomePath()#

API 兼容性说明#

相关模块#

FS 模块

功能特性

基本使用

引入模块

文件读取

文件写入

文件操作

目录操作

路径操作

流式读写

文件监听

API 参考

文件读写

`fs.readFileSync(path, encoding)`

`fs.writeFileSync(path, data, options)`

`fs.appendFileSync(path, data)`

`fs.copyFileSync(src, dest)`

`fs.unlinkSync(path)`

目录操作

`fs.mkdirSync(path, options)`

`fs.readdirSync(path, options)`

`fs.rmdirSync(path)`

`fs.rmSync(path, options)`

文件信息

`fs.statSync(path)`

`fs.existsSync(path)`

实际应用场景

日志写入

批量处理文件

文件备份

目录树遍历

配置文件管理

最佳实践

常见错误

扩展 API（XScript 特有）

路径操作

`fs.join(path1, path2)`

`fs.parent(path)`

目录操作

`fs.dir(path)`

文件操作

`fs.read(path)`

`fs.write(content, path)`

`fs.writeFrom(conn, path)`

`fs.append(content, path)`

`fs.delete(path)`

`fs.move(oldPath, newPath)`

文件信息

`fs.isDir(path)`

`fs.pathInfo(path)`

工作目录

`fs.cwd()`

`fs.chdir(path)`

`fs.userHomePath()`

API 兼容性说明

相关模块