飞翔的鱼丸
Node.js 教程收录了这篇文章
File System（文件系统）
NodeJS 通过 fs 内置模块提供对文件的操作。fs 模块提供的 API 基本上可以分为以下三类：
1，文件属性读写。其中常用的有 fs.stat、fs.chmod、fs.chown 等等。
2，文件内容读写。其中常用的有 fs.readFile、fs.readdir、fs.writeFile、fs.mkdir 等等。
3，底层文件操作。其中常用的有 fs.open、fs.read、fs.write、fs.close 等等。
接口的三种风格：异步、同步和期约
Node.js 文件系统（fs 模块）模块中的方法均有异步和同步版本，例如读取文件内容的函数有异步的 fs.readFile() 和同步的 fs.readFileSync()。
异步的方法函数最后一个参数为回调函数，回调函数的第一个参数包含了错误信息(error)。
建议大家使用异步方法，比起同步，异步方法性能更高，速度更快，而且没有阻塞。
var fs = require("fs");
// 异步读取
fs.readFile('input.txt', function (err, data) {
if (err) {
return console.error(err);
}
console.log("异步读取: " + data.toString());
});
// 同步读取
var data = fs.readFileSync('input.txt');
console.log("同步读取: " + data.toString());
console.log("程序执行完毕。");
// 期约
import fs from 'node:fs/promises';
try {
let data = await fs.readFile('input.txt');
console.log(data.toString());
} catch (error) {
console.error(error.message);
}
检查文件是否存在
之前使用 fs.exists(path,callback) 和 fs.existsSync(path) 检查文件存在。新版本已经标记 fs.exists() 为废弃。建议使用 fs.stat() 或者 fs.access() 代替。
检查文件权限
import { access, open, close } from 'node:fs';
access('myfile', (err) => {
if (!err) {
console.error('myfile already exists');
return;
}
open('myfile', 'wx', (err, fd) => {
if (err) throw err;
try {
writeMyData(fd);
} finally {
close(fd, (err) => {
if (err) throw err;
});
}
});
});
F_OK 是否存在，R_OK 可读、W_OK 可写、X_OK 可执行。通过 access 函数 的第二个参数指定。
举例：
import { access, constants } from 'node:fs';
const file = 'package.json';
// 检查文件是否存在
access(file, constants.F_OK, (err) => {
console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
});
// 检查文件是否可读和可写
access(file, constants.R_OK | constants.W_OK, (err) => {
console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
});
获取文件信息
fs.stat(path, callback)
参数：
path - 文件路径。 callback - 回调函数，带有两个参数如：(err, stats), stats 是 fs.Stats 对象。
fs.stat(path)执行后，会将stats类的实例返回给其回调函数。可以通过stats类中的提供方法判断文件的相关属性。例如判断是否为文件：
var fs = require('fs');
fs.stat('/Users/test/test.txt', function (err, stats) {
console.log(stats);
console.log(stats.isFile()); //true
})
stats类中的方法有：
stats.isFile() 如果是文件返回 true，否则返回 false。 stats.isDirectory() 如果是目录返回 true，否则返回 false。 stats.isBlockDevice() 如果是块设备返回 true，否则返回 false。 stats.isCharacterDevice() 如果是字符设备返回 true，否则返回 false。 stats.isSymbolicLink() 如果是软链接返回 true，否则返回 false。 stats.isFIFO() 如果是FIFO，返回true，否则返回 false。FIFO是UNIX中的一种特殊类型的命令管道。 stats.isSocket() 如果是 Socket 返回 true，否则返回 false。
期约风格
try {
let res = await fs.stat('/root/input.txt');
console.log(res.isFile());
} catch (error) {
console.log(error.message);
}
打开文件
以下为在异步模式下打开文件的语法格式：
fs.open(path, flags[, mode], callback)
参数：
path - 文件的路径。 flags - 文件打开的行为。具体值详见下文。 mode - 设置文件模式(权限)，文件创建默认权限为 0666(可读，可写)。 callback - 回调函数，带有两个参数如：callback(err, fd)。
flags 参数可以是以下值：
r 以读取模式打开文件。如果文件不存在抛出异常。 r+ 以读写模式打开文件。如果文件不存在抛出异常。 rs 以同步的方式读取文件。 rs+ 以同步的方式读取和写入文件。 w 以写入模式打开文件，如果文件不存在则创建。 wx 类似 'w'，但是如果文件路径存在，则文件写入失败。 w+ 以读写模式打开文件，如果文件不存在则创建。 wx+ 类似 'w+'， 但是如果文件路径存在，则文件读写失败。 a 以追加模式打开文件，如果文件不存在则创建。 ax 类似 'a'， 但是如果文件路径存在，则文件追加失败。 a+ 以读取追加模式打开文件，如果文件不存在则创建。 ax+ 类似 'a+'， 但是如果文件路径存在，则文件读取追加失败。
例子：
// 异步打开文件
console.log("准备打开文件！");
fs.open('input.txt', 'r+', function(err, fd) {
if (err) {
return console.error(err);
}
console.log("文件打开成功！");
});
写入文件
fs.writeFile(file, data[, options], callback)
writeFile 直接打开文件默认是 w 模式，所以如果文件存在，该方法写入的内容会覆盖旧的文件内容。
参数：
file - 文件名或文件描述符。
data - 要写入文件的数据，可以是 String(字符串) 或 Buffer(缓冲) 对象。
options - 该参数是一个对象，包含 {encoding, mode, flag}。默认编码为 utf8, 模式为 0666 ， flag 为 'w'
callback - 回调函数，回调函数只包含错误信息参数(err)，在写入失败时返回。
例子：
var fs = require("fs");
console.log("准备写入文件");
fs.writeFile('input.txt', '我是通 过fs.writeFile 写入文件的内容', function(err) {
if (err) {
return console.error(err);
}
console.log("数据写入成功！");
});
读取文件
fs.read(fd, buffer, offset, length, position, callback)
该方法使用了文件描述符来读取文件。
参数：
fd - 通过 fs.open() 方法返回的文件描述符。 buffer - 数据写入的缓冲区。 offset - 缓冲区写入的写入偏移量。 length - 要从文件中读取的字节数。 position - 文件读取的起始位置，如果 position 的值为 null，则会从当前文件指针的位置读取。 callback - 回调函数，有三个参数err, bytesRead, buffer，err 为错误信息， bytesRead 表示读取的字节数，buffer 为缓冲区对象。
例子：
var fs = require("fs");
var buf = new Buffer.alloc(1024);
console.log("准备打开已存在的文件！");
fs.open('input.txt', 'r+', function(err, fd) {
if (err) {
return console.error(err);
}
console.log("文件打开成功！");
console.log("准备读取文件：");
fs.read(fd, buf, 0, buf.length, 0, function(err, bytes){
if (err){
console.log(err);
}
console.log(bytes + " 字节被读取");
// 仅输出读取的字节
if(bytes > 0){
console.log(buf.slice(0, bytes).toString());
}
});
});
关闭文件
fs.close(fd, callback)
该方法使用了文件描述符来读取文件。
参数：
fd - 通过 fs.open() 方法返回的文件描述符。
callback - 回调函数，没有参数。
fs.close(fd, function (err) {
if (err) {
console.log(err);
}
console.log("文件关闭成功");
});
截取文件
以下为异步模式下截取文件的语法格式：
fs.ftruncate(fd, len, callback)
该方法使用了文件描述符来读取文件。
参数：
fd - 通过 fs.open() 方法返回的文件描述符。 len - 文件内容截取的长度。 callback - 回调函数，没有参数。
例子：
var fs = require("fs");
var buf = new Buffer.alloc(1024);
console.log("准备打开文件！");
fs.open('input.txt', 'r+', function(err, fd) {
if (err) {
return console.error(err);
}
console.log("文件打开成功！");
console.log("截取10字节内的文件内容，超出部分将被去除。");
// 截取文件
fs.ftruncate(fd, 10, function(err){
if (err){
console.log(err);
}
console.log("文件截取成功。");
console.log("读取相同的文件");
fs.read(fd, buf, 0, buf.length, 0, function(err, bytes){
if (err){
console.log(err);
}
// 仅输出读取的字节
if(bytes > 0){
console.log(buf.slice(0, bytes).toString());
}
// 关闭文件
fs.close(fd, function(err){
if (err){
console.log(err);
}
console.log("文件关闭成功！");
});
});
});
});
删除文件
fs.unlink(path, callback)
参数：
path - 文件路径。 callback - 回调函数，没有参数。
例子：
var fs = require("fs");
console.log("准备删除文件！");
fs.unlink('input.txt', function(err) {
if (err) {
return console.error(err);
}
console.log("文件删除成功！");
});
Path（路径）
操作文件时难免不与文件路径打交道。NodeJS 提供了 path 内置模块来简化路径相关操作，并提升代码可读性。以下分别介绍几个常用的 API。
path.normalize
将传入的路径转换为标准路径，具体讲的话，除了解析路径中的.与..外，还能去掉多余的斜杠。如果有程序需要使用路径作为某些数据的索引，但又允许用户随意输入路径时，就需要使用该方法保证路径的唯一性。以下是一个例子：
var cache = {};
function store(key, value) {
cache[path.normalize(key)] = value;
}
store('foo/bar', 1);
store('foo//baz//../bar', 2);
console.log(cache); // => { "foo/bar": 2 }
注意： 标准化之后的路径里的斜杠在 Windows 系统下是\，而在 Linux 系统下是/。如果想保证任何系统下都使用/作为路径分隔符的话，需要用.replace(/\\/g, '/')再替换一下标准路径。
path.join
将传入的多个路径拼接为标准路径。该方法可避免手工拼接路径字符串的繁琐，并且能在不同系统下正确使用相应的路径分隔符。以下是一个例子：
path.join('foo/', 'baz/', '../bar'); // => "foo/bar"
path.extname
当我们需要根据不同文件扩展名做不同操作时，该方法就显得很好用。以下是一个例子：
path.extname('foo/bar.js'); // => ".js"
path 模块提供的其余方法也不多，稍微看一下官方文档就能全部掌握。
创建目录
fs.mkdir(path[, options], callback)
参数：
path - 文件路径。 options 参数可以是： recursive - 是否以递归的方式创建目录，默认为 false。 mode - 设置目录权限，默认为 0777。 callback - 回调函数，没有参数。
例子：
var fs = require("fs");
// tmp 目录必须存在
console.log("创建目录 /tmp/test/");
fs.mkdir("/tmp/test/",function(err){
if (err) {
return console.error(err);
}
console.log("目录创建成功。");
});
//可以添加 recursive: true 参数，不管创建的目录 /tmp 和 /tmp/a 是否存在：
fs.mkdir('/tmp/a/apple', { recursive: true }, (err) => {
if (err) throw err;
});
读取目录
fs.readdir(path, callback)
参数：
path - 文件路径。 callback - 回调函数，回调函数带有两个参数err, files，err 为错误信息，files 为 目录下的文件数组列表。
例子：
var fs = require("fs");
console.log("查看 /tmp 目录");
fs.readdir("/tmp/",function(err, files){
if (err) {
return console.error(err);
}
files.forEach( function (file){
console.log( file );
});
});
删除目录
fs.rmdir(path, callback)
参数：
path - 文件路径。 callback - 回调函数，没有参数。
例子：
var fs = require("fs");
// 执行前创建一个空的 /tmp/test 目录
console.log("准备删除目录 /tmp/test");
fs.rmdir("/tmp/test",function(err){
if (err) {
return console.error(err);
}
console.log("读取 /tmp 目录");
fs.readdir("/tmp/",function(err, files){
if (err) {
return console.error(err);
}
files.forEach( function (file){
console.log( file );
});
});
});
获取文件名
path.basename('/var/www/test.html')
path.basename('C:\\temp\\test.html')
path.posix.basename('C:\\temp\\test.html')
path.win32.basename('C:\\temp\\test.html')
Stream（数据流）
当内存中无法一次装下需要处理的数据时，或者一边读取一边处理更加高效时，我们就需要用到数据流。NodeJS中通过各种 Stream 来提供对数据流的操作。
小文件拷贝
fs.writeFileSync(dst, fs.readFileSync(src));
大文件拷贝
上边的程序拷贝一些小文件没啥问题，但这种一次性把所有文件内容都读取到内存中后再一次性写入磁盘的方式不适合拷贝大文件，内存会爆仓。对于大文件，我们只能读一点写一点，直到完成拷贝。因此上边的程序需要改造如下。
fs.createReadStream(src).pipe(fs.createWriteStream(dst));
以上边的大文件拷贝程序为例，我们可以为数据来源创建一个只读数据流，示例如下：
var rs = fs.createReadStream(pathname);
rs.on('data', function (chunk) {
doSomething(chunk);
});
rs.on('end', function () {
cleanUp();
});
注意： Stream 基于事件机制工作，所有 Stream 的实例都继承于 NodeJS 提供的 EventEmitter。
上边的代码中 data 事件会源源不断地被触发，不管 doSomething 函数是否处理得过来。代码可以继续做如下改造，以解决这个问题。
var rs = fs.createReadStream(src);
rs.on('data', function (chunk) {
rs.pause();
doSomething(chunk, function () {
rs.resume();
});
});
rs.on('end', function () {
cleanUp();
});
以上代码给 doSomething 函数加上了回调，因此我们可以在处理数据前暂停数据读取，并在处理数据后继续读取数据。
此外，我们也可以为数据目标创建一个只写数据流，示例如下：
var rs = fs.createReadStream(src);
var ws = fs.createWriteStream(dst);
rs.on('data', function (chunk) {
ws.write(chunk);
});
rs.on('end', function () {
ws.end();
});
我们把 doSomething 换成了往只写数据流里写入数据后，以上代码看起来就像是一个文件拷贝程序了。但是以上代码存在上边提到的问题，如果写入速度跟不上读取速度的话，只写数据流内部的缓存会爆仓。我们可以根据.write方法的返回值来判断传入的数据是写入目标了，还是临时放在了缓存了，并根据 drain 事件来判断什么时候只写数据流已经将缓存中的数据写入目标，可以传入下一个待写数据了。因此代码可以改造如下：
var rs = fs.createReadStream(src);
var ws = fs.createWriteStream(dst);
rs.on('data', function (chunk) {
if (ws.write(chunk) === false) {
rs.pause();
}
});
rs.on('end', function () {
ws.end();
});
ws.on('drain', function () {
rs.resume();
});
以上代码实现了数据从只读数据流到只写数据流的搬运，并包括了防爆仓控制。因为这种使用场景很多，例如上边的大文件拷贝程序，NodeJS 直接提供了.pipe方法来做这件事情，其内部实现方式与上边的代码类似。
参考：
http://nodejs.org/api/fs.html
http://nodejs.org/api/stream.html
https://nodejs.org/api/path.html
修改时间 2022-11-12