模組fs

fs 模組是檔案系統操作模組。它提供了讀取檔案、寫入檔案、開啟檔案、關閉檔案、更改檔案權限等磁碟I/O 操作，支援同步和非同步兩種用法。fs 模組也提供了檔案監視器功能，可以監聽檔案系統中檔案和目錄的變化，並回呼指定的函數。

例如，要在fibjs 中讀取一個文件，可以使用fs 模組的readFile 方法：

1
2
var fs = require('fs');
var content = fs.readFile('/path/to/file');

如果想要非同步讀取文件，可以透過回呼來實現：

1
2
3
4
5
var fs = require('fs');
fs.readFile('/path/to/file', function(err, data) {
    if (err) throw err;
    console.log(data);
});

類似地，如果要寫入一個文件，可以使用fs 模組的writeFile 方法：

1
2
3
var fs = require('fs');
var content = 'hello, world!';
fs.writeFile('/path/to/file', content);

如果要非同步寫入文件，可以透過回呼來實現：

1
2
3
4
5
6
var fs = require('fs');
var content = 'hello, world!';
fs.writeFile('/path/to/file', content, function(err) {
    if (err) throw err;
    console.log('File saved.');
});

除了讀寫檔案之外，fs 模組還提供了一系列其他的檔案系統操作，諸如建立目錄、修改檔案權限、查詢檔案狀態等等。

一些注意點:

運行fs.watch(filename)會回傳一個繼承自EventEmitter的watcher, 它支持'change', 'changeonly', 'renameonly' 三個事件
fs.watchFile(target)和fs.unwatchFile(target)依然可以成對使用
fs.watchFile(target)會回傳一個繼承自EventEmitter的StatsWatcher對象, 調用fs.unwatchFile(target)等價於調用StatsWatcher.close().
因為uv 在Linux 上的實現,fs.watch的recursive選項僅在win32/darwin 被穩定支持. 你依然可以嘗試在Linux 中嘗試使用fs.watch('/[path](path.md)/to', { recursive: true }, handler), 但可能會發現handler被回調的時機與你預期的有差異

物件

constants

fs模組的常數對象

1fs_constants fs.constants;

靜態函數

exists

查詢指定的檔案或目錄是否存在

1
static Boolean fs.exists(String path) async;

呼叫參數:

path: String, 指定要查詢的路徑

回傳結果:

Boolean, 返回True 表示檔案或目錄存在

access

查詢使用者對指定的檔案的權限

1
2
static fs.access(String path,
    Integer mode = 0) async;

呼叫參數:

path: String, 指定要查詢的路徑
mode: Integer, 指定查詢的權限,預設為檔案是否存在

link

建立硬連結檔, windows 下不支援此方法

1
2
static fs.link(String oldPath,
    String newPath) async;

呼叫參數:

oldPath: String, 原始檔
newPath: String, 將要建立的文件

unlink

刪除指定的文件

1
static fs.unlink(String path) async;

呼叫參數:

path: String, 指定要刪除的路徑

mkdir

建立一個目錄

1
2
static fs.mkdir(String path,
    Integer mode = 0777) async;

呼叫參數:

path: String, 指定要建立的目錄名
mode: Integer, 指定檔案權限，Windows 忽略此參數，預設值: 0777

建立一個目錄

1
2
static fs.mkdir(String path,
    Object opt) async;

呼叫參數:

path: String, 指定要建立的目錄名
opt: Object, 指定建立參數

建立參數可以包含以下值：

1
2
3
4{
    recursive: false, // specify whether parent directories should be created. Default: false
    mode: 0777 // specify the file mode. Default: 0777
}

rmdir

刪除一個目錄

1
static fs.rmdir(String path) async;

呼叫參數:

path: String, 指定要刪除的目錄名

rename

重新命名一個文件

1
2
static fs.rename(String from,
    String to) async;

呼叫參數:

from: String, 指定更名的文件
to: String, 指定要修改的新檔名

copyFile

將src 拷貝到dest。預設情況下，如果dest 已經存在，則覆寫它。

1
2
3
static fs.copyFile(String from,
    String to,
    Integer mode = 0) async;

呼叫參數:

from: String, 指定要拷貝的來源檔名
to: String, 指定要拷貝的目標檔名
mode: Integer, 指定拷貝操作的修飾符，預設為 0

mode 是一個可選的整數，指定拷貝操作的行為。可以建立由兩個或更多值位元或組成的遮罩（例如fs.constants.COPYFILE_EXCL |fs.constants.COPYFILE_FICLONE）。

fs.constants.COPYFILE_EXCL - 如果dest 已存在，則拷貝操作將會失敗。
fs.constants.COPYFILE_FICLONE - 拷貝操作將嘗試建立寫入時拷貝（copy-on-write）連結。如果平台不支援寫入時拷貝，則使用後備的拷貝機制。
fs.constants.COPYFILE_FICLONE_FORCE - 拷貝操作將嘗試建立寫入時拷貝連結。如果平台不支援寫入時拷貝，則拷貝操作將失敗。

chmod

設定指定檔案的存取權限，Windows 不支援此方法

1
2
static fs.chmod(String path,
    Integer mode) async;

呼叫參數:

path: String, 指定操作的文件
mode: Integer, 指定設定的存取權限

lchmod

設定指定檔案的存取權限，若檔案是軟體連線則不改變指向檔案的權限，只在macOS、BSD 系列平台上可用

1
2
static fs.lchmod(String path,
    Integer mode) async;

呼叫參數:

path: String, 指定操作的文件
mode: Integer, 指定設定的存取權限

chown

設定指定檔案的擁有者，Windows 不支援此方法

1
2
3
static fs.chown(String path,
    Integer uid,
    Integer gid) async;

呼叫參數:

path: String, 指定設定的文件
uid: Integer, 文件擁有者使用者id
gid: Integer, 文件擁有者群組id

lchown

設定指定檔案的擁有者，如果指定的檔案是軟連線則不會改變其指向檔案的擁有者，Windows 不支援此方法

1
2
3
static fs.lchown(String path,
    Integer uid,
    Integer gid) async;

呼叫參數:

path: String, 指定設定的文件
uid: Integer, 文件擁有者使用者id
gid: Integer, 文件擁有者群組id

stat

查詢指定文件的基礎信息

1
static Stat fs.stat(String path) async;

呼叫參數:

path: String, 指定查詢的文件

回傳結果:

Stat, 返回文件的基礎訊息

lstat

查詢指定文件的基礎資訊, 和stat不同的是, 當path是一個軟連接的時候，返回的將是這個軟連接的信息而不是指向的文件的信息

1
static Stat fs.lstat(String path) async;

呼叫參數:

path: String, 指定查詢的文件

回傳結果:

Stat, 返回文件的基礎訊息

fstat

查詢指定文件的基礎信息

1
static Stat fs.fstat(FileHandle fd) async;

呼叫參數:

fd:FileHandle, 文件描述符對象

回傳結果:

Stat, 返回文件的基礎訊息

readlink

讀取指定的軟連接檔, windows 下不支援此方法

1
static String fs.readlink(String path) async;

呼叫參數:

path: String, 指定讀取的軟連線文件

回傳結果:

String, 傳回軟連線指向的檔案名

realpath

傳回指定路徑的絕對路徑，如果指定路徑中包含相對路徑也會被展開

1
static String fs.realpath(String path) async;

呼叫參數:

path: String, 指定讀取的路徑

回傳結果:

String, 返回處理後的絕對路徑

symlink

建立軟連接文件

1
2
3
static fs.symlink(String target,
    String linkpath,
    String type = "file") async;

呼叫參數:

target: String, 目標文件，可以是文件、目錄、或不存在的路徑
linkpath: String, 將被建立的軟連線文件
type: String, 建立的軟連線類型, 可選型別為'file', 'dir', 'junction', 預設為'file', 此參數只在windows上有效，當為'junction'的時候將要建立的目標路徑linkpath必須為絕對路徑, 而target則會被自動轉換為絕對路徑。

truncate

修改檔案尺寸,如果指定的長度大於來源檔案大小則用'\0'填充，否則多於的檔案內容將會遺失

1
2
static fs.truncate(String path,
    Integer len) async;

呼叫參數:

path: String, 指定被修改檔案的路徑
len: Integer, 指定修改後檔案的大小

read

根據檔案描述符，讀取檔案內容

1
2
3
4
5
static Integer fs.read(FileHandle fd,
    Buffer buffer,
    Integer offset = 0,
    Integer length = 0,
    Integer position = -1) async;

呼叫參數:

fd:FileHandle, 文件描述符對象
buffer:Buffer, 讀取結果寫入的Buffer物件
offset: Integer,Buffer寫入偏移量，預設為 0
length: Integer, 檔案讀取位元組數，預設為 0
position: Integer, 檔案讀取位置，預設為目前檔案位置

回傳結果:

Integer, 實際讀取的位元組數

fchmod

根據檔案描述符，改變檔案模式。只在POSIX 系統有效。

1
2
static fs.fchmod(FileHandle fd,
    Integer mode) async;

呼叫參數:

fd:FileHandle, 文件描述符對象
mode: Integer, 檔案的模式

fchown

根據檔案描述符，改變所有者。只在POSIX 系統有效。

1
2
3
static fs.fchown(FileHandle fd,
    Integer uid,
    Integer gid) async;

呼叫參數:

fd:FileHandle, 文件描述符對象
uid: Integer, 用戶id
gid: Integer, 組id

fdatasync

根據檔案描述符，同步資料到磁碟

1
static fs.fdatasync(FileHandle fd) async;

呼叫參數:

fd:FileHandle, 文件描述符對象

fsync

根據檔案描述符，同步資料到磁碟

1
static fs.fsync(FileHandle fd) async;

呼叫參數:

fd:FileHandle, 文件描述符對象

readdir

讀取指定目錄的檔案資訊

1
static NArray fs.readdir(String path) async;

呼叫參數:

path: String, 指定查詢的目錄

回傳結果:

讀取指定目錄的檔案資訊

1
2
static NArray fs.readdir(String path,
    Object opts = {}) async;

呼叫參數:

path: String, 指定查詢的目錄
opts: Object, 指定參數

回傳結果:

參數opts 支援的選項如下：

1
2
3{
    "recursive": false // specify whether all subdirectories should be watched or only the current directory
}

openFile

開啟文件，用於讀取，寫入，或同時讀寫

1
2
static SeekableStream fs.openFile(String fname,
    String flags = "r") async;

呼叫參數:

fname: String, 指定檔名
flags: String, 指定檔案開啟方式，預設為"r"，唯讀方式

回傳結果:

SeekableStream, 傳回開啟的文件對象

參數flags 支援的方式如下：

'r' 只讀方式，檔案不存在則拋出錯誤。
'r+' 讀寫方式，檔案不存在則拋出錯誤。
'w' 只寫方式，檔案不存在則自動創建，存在則會被清空。
'w+' 讀寫方式，檔案不存在則自動建立。
'a' 只寫添加方式，檔案不存在則自動建立。
'a+' 讀寫新增方式，檔案不存在則自動建立。

open

開啟檔案描述符

1
2
3
static FileHandle fs.open(String fname,
    String flags = "r",
    Integer mode = 0666) async;

呼叫參數:

fname: String, 指定檔名
flags: String, 指定檔案開啟方式，預設為"r"，唯讀方式
mode: Integer, 當建立檔案的時候，指定檔案的模式，預設0666

回傳結果:

FileHandle, 返回開啟的檔案描述符

參數flags 支援的方式如下：

'r' 只讀方式，檔案不存在則拋出錯誤。
'r+' 讀寫方式，檔案不存在則拋出錯誤。
'w' 只寫方式，檔案不存在則自動創建，存在則會被清空。
'w+' 讀寫方式，檔案不存在則自動建立。
'a' 只寫添加方式，檔案不存在則自動建立。
'a+' 讀寫新增方式，檔案不存在則自動建立。

close

關閉檔案描述符

1
static fs.close(FileHandle fd) async;

呼叫參數:

fd:FileHandle, 文件描述符對象

openTextStream

開啟文字文件，用於讀取，寫入，或同時讀寫

1
2
static BufferedStream fs.openTextStream(String fname,
    String flags = "r") async;

呼叫參數:

fname: String, 指定檔名
flags: String, 指定檔案開啟方式，預設為"r"，唯讀方式

回傳結果:

BufferedStream, 傳回開啟的文件對象

參數flags 支援的方式如下：

'r' 只讀方式，檔案不存在則拋出錯誤。
'r+' 讀寫方式，檔案不存在則拋出錯誤。
'w' 只寫方式，檔案不存在則自動創建，存在則會被清空。
'w+' 讀寫方式，檔案不存在則自動建立。
'a' 只寫添加方式，檔案不存在則自動建立。
'a+' 讀寫新增方式，檔案不存在則自動建立。

readTextFile

開啟文字文件，並讀取內容

1
static String fs.readTextFile(String fname) async;

呼叫參數:

fname: String, 指定檔名

回傳結果:

String, 返回文件文字內容

readFile

開啟文件，並讀取內容

1
2
static Variant fs.readFile(String fname,
    String encoding = "") async;

呼叫參數:

fname: String, 指定檔名
encoding: String, 指定解碼方式，預設不解碼

回傳結果:

Variant, 返回文件文字內容

開啟文件，並讀取內容

1
2
static Variant fs.readFile(String fname,
    Object options) async;

呼叫參數:

fname: String, 指定檔名
options: Object, 指定讀取選項

回傳結果:

Variant, 返回文件文字內容

options 支援的選項如下：

1
2
3{
    "encoding": "utf8" // specify the encoding, default is utf8.
}

readLines

開啟文件，以數組方式讀取一組文字行，行結尾標識基於EOL 屬性的設置，缺省時，posix:"\n"；windows:"\r\n"

1
2
static Array fs.readLines(String fname,
    Integer maxlines = -1);

呼叫參數:

fname: String, 指定檔名
maxlines: Integer, 指定此讀取的最大行數，預設讀取全部文字行

回傳結果:

Array, 傳回讀取的文字行數組，若無資料可讀，或連線中斷，空數組

write

根據文件描述符，寫入內容

1
2
3
4
5
static Integer fs.write(FileHandle fd,
    Buffer buffer,
    Integer offset = 0,
    Integer length = -1,
    Integer position = -1) async;

呼叫參數:

fd:FileHandle, 文件描述符對象
buffer:Buffer, 待寫入的Buffer物件
offset: Integer,Buffer資料讀取偏移量，預設為 0
length: Integer, 檔案寫入位元組數，預設為-1
position: Integer, 檔案寫入取位置，預設為目前檔案位置

回傳結果:

Integer, 實際寫入的位元組數

根據文件描述符，寫入內容

1
2
3
4
static Integer fs.write(FileHandle fd,
    String string,
    Integer position = -1,
    String encoding = "utf8") async;

呼叫參數:

fd:FileHandle, 文件描述符對象
string: String, 待寫入的字串
position: Integer, 檔案寫入取位置，預設為目前檔案位置
encoding: String, 指定解碼方式，預設解碼utf8

回傳結果:

Integer, 實際寫入的位元組數

writeTextFile

建立文字文件，並寫入內容

1
2
static fs.writeTextFile(String fname,
    String txt) async;

呼叫參數:

fname: String, 指定檔名
txt: String, 指定要寫入的字串

writeFile

建立二進位文件，並寫入內容

1
2
3
static fs.writeFile(String fname,
    Buffer data,
    String opt = "binary") async;

呼叫參數:

fname: String, 指定檔名
data:Buffer, 指定要寫入的二進位數據
opt: String, 指定寫入選項，將被忽略

建立二進位文件，並寫入內容

1
2
3
static fs.writeFile(String fname,
    Buffer data,
    Object options) async;

呼叫參數:

fname: String, 指定檔名
data:Buffer, 指定要寫入的二進位數據
options: Object, 指定寫入選項，將被忽略

建立文件，並寫入內容

1
2
3
static fs.writeFile(String fname,
    String data,
    String opt = "utf8") async;

呼叫參數:

fname: String, 指定檔名
data: String, 指定要寫入的數據
opt: String, 指定寫入選項

建立文件，並寫入內容

1
2
3
static fs.writeFile(String fname,
    String data,
    Object options) async;

呼叫參數:

fname: String, 指定檔名
data: String, 指定要寫入的數據
options: Object, 指定寫入選項

options 支援的選項如下：

1
2
3{
    "encoding": "utf8" // specify the encoding, default is utf8.
}

appendFile

建立二進位文件，並寫入內容

1
2
static fs.appendFile(String fname,
    Buffer data) async;

呼叫參數:

fname: String, 指定檔名
data:Buffer, 指定要寫入的二進位數據

setZipFS

設定zip虛擬文件映射

1
2
static fs.setZipFS(String fname,
    Buffer data);

呼叫參數:

fname: String, 指定映射路徑
data:Buffer, 指定映射的zip文件數據

clearZipFS

清除zip虛擬文件映射

1
static fs.clearZipFS(String fname = "");

呼叫參數:

fname: String, 指定映射路徑，預設清除全部快取

watch

觀察一個檔案, 傳回對應的watcher 對象

1
static FSWatcher fs.watch(String fname);

呼叫參數:

fname: String, 指定要觀察的檔案對象

回傳結果:

FSWatcher,FSWatcher物件

觀察一個檔案, 傳回對應的watcher 對象

1
2
static FSWatcher fs.watch(String fname,
    Function callback);

呼叫參數:

fname: String, 指定要觀察的檔案對象
callback: Function,(evtType: 'change' | 'rename', filename: string) => any當檔案物件改變時的處理回調

回傳結果:

FSWatcher,FSWatcher物件

觀察一個檔案, 傳回對應的watcher 對象

1
2
static FSWatcher fs.watch(String fname,
    Object options);

呼叫參數:

fname: String, 指定要觀察的檔案對象
options: Object, 觀察選項

回傳結果:

FSWatcher,FSWatcher物件

options 支援的選項如下：

1
2
3
4
5{
    "persistent": true, // specify whether the process should continue to run as long as files are being watched
    "recursive": false, // specify whether all subdirectories should be watched or only the current directory
    "encoding": "utf8", // specify the encoding, default is utf8.
}

觀察一個檔案, 傳回對應的watcher 對象

1
2
3
static FSWatcher fs.watch(String fname,
    Object options,
    Function callback);

呼叫參數:

fname: String, 指定要觀察的檔案對象
options: Object, 觀察選項
callback: Function,(evtType: 'change' | 'rename', filename: string) => any當檔案物件改變時的處理回調

回傳結果:

FSWatcher,FSWatcher物件

options 支援的選項如下：

1
2
3
4
5{
    "persistent": true, // specify whether the process should continue to run as long as files are being watched
    "recursive": false, // specify whether all subdirectories should be watched or only the current directory
    "encoding": "utf8", // specify the encoding, default is utf8.
}

watchFile

觀察一個文件, 返回對應的StatsWatcher物件

1
2
static StatsWatcher fs.watchFile(String fname,
    Function callback);

呼叫參數:

fname: String, 指定要觀察的檔案對象
callback: Function,(curStats: Stats, prevStats: Stats) => any當檔案物件的stats 發生變化時的處理回調

回傳結果:

StatsWatcher,StatsWatcher物件

觀察一個文件, 返回對應的StatsWatcher物件

1
2
3
static StatsWatcher fs.watchFile(String fname,
    Object options,
    Function callback);

呼叫參數:

fname: String, 指定要觀察的檔案對象
options: Object, 觀察選項
callback: Function,(curStats: Stats, prevStats: Stats) => any當檔案物件的stats 發生變化時的處理回調

回傳結果:

StatsWatcher,StatsWatcher物件

options 支援的選項如下：

1
2
3
4
5{
    "persistent": true, // specify whether the process should continue to run as long as files are being watched
    "recursive": false, // specify whether all subdirectories should be watched or only the current directory
    "encoding": "utf8", // specify the encoding, default is utf8.
}

unwatchFile

從觀察fname 的StatsWatcher中移除所有觀察事件的回調

1
static fs.unwatchFile(String fname);

呼叫參數:

fname: String, 指定要觀察的檔案對象

回傳結果:

StatsWatcher物件

從觀察fname 的StatsWatcher的觀察事件回呼中移除callback回調

1
2
static fs.unwatchFile(String fname,
    Function callback);

呼叫參數:

fname: String, 指定要觀察的檔案對象
callback: Function, 要移除的回調

回傳結果:

StatsWatcher物件

即便callback 不再StatsWatcher的觀察事件回調中也不會報錯

常量

SEEK_SET

seek 方式常數，移動到絕對位置

1
const fs.SEEK_SET = 0;

SEEK_CUR

seek 方式常數，移動到目前位置的相對位置

1
const fs.SEEK_CUR = 1;

SEEK_END

seek 方式常數，移動到檔案結尾的相對位置

1
const fs.SEEK_END = 2;

開發指南

基礎模組

內建對象

社群模組

模組fs

物件

constants

靜態函數

exists

access

link

unlink

mkdir

rmdir

rename

copyFile

chmod

lchmod

chown

lchown

stat

lstat

fstat

readlink

realpath

symlink

truncate

read

fchmod

fchown

fdatasync

fsync

readdir

openFile

open

close

openTextStream

readTextFile

readFile

readLines

write

writeTextFile

writeFile

appendFile

setZipFS

clearZipFS

watch

watchFile

unwatchFile

常量

SEEK_SET

SEEK_CUR

SEEK_END