File System · Node.js 中文API文檔 0.10.18

# File System ~~~ 穩定度: 3 - 穩定 ~~~ 文件系統模塊是一個簡單包裝的標準 POSIX 文件 I/O 操作方法集。您可以通過調用`require('fs')`來獲取該模塊。文件系統模塊中的所有方法均有異步和同步版本。文件系統模塊中的異步方法需要一個完成時的回調函數作為最后一個傳入形參。回調函數的構成由您調用的異步方法所決定，通常情況下回調函數的第一個形參為返回的錯誤信息。如果異步操作執行正確并返回，該錯誤形參則為`null`或者`undefined`。如果您使用的是同步版本的操作方法，則一旦出現錯誤，會以通常的拋出錯誤的形式返回錯誤。你可以用`try`和`catch`等語句來攔截錯誤并使程序繼續進行。這里是一個異步版本的例子： ~~~ fs.unlink('/tmp/hello', function (err) { if (err) throw err; console.log('successfully deleted /tmp/hello'); }); ~~~ 這是同步版本的例子: ~~~ fs.unlinkSync('/tmp/hello') console.log('successfully deleted /tmp/hello'); ~~~ 當使用異步版本時不能保證執行順序,因此下面這個例子很容易出錯: ~~~ fs.rename('/tmp/hello', '/tmp/world', function (err) { if (err) throw err; console.log('renamed complete'); }); fs.stat('/tmp/world', function (err, stats) { if (err) throw err; console.log('stats: ' + JSON.stringify(stats)); }); ~~~ `fs.stat`有可能在`fs.rename`前執行.要等到正確的執行順序應該用下面的方法: ~~~ fs.rename('/tmp/hello', '/tmp/world', function (err) { if (err) throw err; fs.stat('/tmp/world', function (err, stats) { if (err) throw err; console.log('stats: ' + JSON.stringify(stats)); }); }); ~~~ 在繁重的任務中,*強烈推薦*使用這些函數的異步版本.同步版本會阻塞進程,直到完成處理,也就是說會暫停所有的連接. 可以使用文件名的相對路徑, 但是記住這個路徑是相對于`process.cwd()`的. 大部分的文件系統(fs)函數可以忽略回調函數(callback)這個參數.如果忽略它,將會由一個默認回調函數(callback)來重新拋出(rethrow)錯誤.要獲得原調用點的堆棧跟蹤(trace)信息,需要在環境變量里設置NODE_DEBUG. ~~~ $ env NODE_DEBUG=fs node script.js fs.js:66 throw err; ^ Error: EISDIR, read at rethrow (fs.js:61:21) at maybeCallback (fs.js:79:42) at Object.fs.readFile (fs.js:153:18) at bad (/path/to/script.js:2:17) at Object.<anonymous> (/path/to/script.js:5:1) <etc.> ~~~ ### fs.rename(oldPath, newPath, callback) 異步版本的rename函數(2).完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.renameSync(oldPath, newPath) 同步版本的rename(2). ### fs.ftruncate(fd, len, callback) 異步版本的ftruncate(2). 完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.ftruncateSync(fd, len) 同步版本的ftruncate(2). ### fs.truncate(path, len, callback) 異步版本的truncate(2). 完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.truncateSync(path, len) 同步版本的truncate(2). 異步版本的chown.完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. 異步版本的chown(2).完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.chownSync(path, uid, gid) 同步版本的chown(2). ### fs.fchown(fd, uid, gid, callback) 異步版本的fchown(2)。回調函數的參數除了出現錯誤時有一個錯誤對象外，沒有其它參數。 ### fs.fchownSync(fd, uid, gid) 同步版本的fchown(2). ### fs.lchown(path, uid, gid, callback) 異步版的lchown(2)。完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.lchownSync(path, uid, gid) 同步版本的lchown(2). ### fs.chmod(path, mode, callback) 異步版的 chmod(2). 完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.chmodSync(path, mode) 同步版的 chmod(2). ### fs.fchmod(fd, mode, callback) 異步版的 fchmod(2). 完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.fchmodSync(fd, mode) 同步版的 fchmod(2). ### fs.lchmod(path, mode, callback) 異步版的 lchmod(2). 完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. 僅在 Mac OS X 系統下可用。 ### fs.lchmodSync(path, mode) 同步版的 lchmod(2). ### fs.stat(path, callback) 異步版的 stat(2). 回調函數（callback）接收兩個參數： `(err, stats)` ，其中 `stats` 是一個 [fs.Stats](#) 對象。詳情請參考 [fs.Stats](#) ### fs.lstat(path, callback) 異步版的 lstat(2). 回調函數（callback）接收兩個參數： `(err, stats)` 其中 `stats` 是一個 `fs.Stats` 對象。 `lstat()` 與 `stat()` 相同，區別在于：若 `path` 是一個符號鏈接時（symbolic link）,讀取的是該符號鏈接本身，而不是它所鏈接到的文件。 ### fs.fstat(fd, callback) 異步版的 fstat(2). 回調函數（callback）接收兩個參數： `(err, stats)` 其中 `stats` 是一個 `fs.Stats` 對象。 `fstat()` 與 `stat()` 相同，區別在于：要讀取的文件（譯者注：即第一個參數）是一個文件描述符（file descriptor） `fd` 。 ### fs.statSync(path) 同步版的 stat(2). 返回一個 `fs.Stats` 實例。 ### fs.lstatSync(path) 同步版的 lstat(2). 返回一個 `fs.Stats` 實例。 ### fs.fstatSync(fd) 同步版的 fstat(2). 返回一個 `fs.Stats` 實例。 ### fs.link(srcpath, dstpath, callback) 異步版的 link(2). 完成時的回調函數（callback）只接受一個參數：可能出現的異常信息。 ### fs.linkSync(srcpath, dstpath) 同步版的 link(2). ### fs.symlink(srcpath, dstpath, [type], callback) 異步版的 symlink(2). 完成時的回調函數（callback）只接受一個參數：可能出現的異常信息。 `type` 可以是 `'dir'`, `'file'`, 或者`'junction'` (默認是 `'file'`)，此參數僅用于 Windows 系統（其他系統平臺會被忽略）。注意： Windows 系統要求目標路徑（譯者注：即 `dstpath` 參數）必須是一個絕對路徑，當使用 `'junction'` 時，`dstpath` 參數會自動轉換為絕對路徑。 ### fs.symlinkSync(srcpath, dstpath, [type]) 同步版的 symlink(2). ### fs.readlink(path, callback) 異步版的 readlink(2). 回調函數（callback）接收兩個參數： `(err, linkString)`. ### fs.readlinkSync(path) 同步版的 readlink(2). 返回符號鏈接（symbolic link）的字符串值。 ### fs.realpath(path, [cache], callback) 異步版的 realpath(2). 回調函數（callback）接收兩個參數： `(err, resolvedPath)`. May use `process.cwd` to resolve relative paths. `cache` is an object literal of mapped paths that can be used to force a specific path resolution or avoid additional `fs.stat` calls for known real paths. 實例： ~~~ var cache = {'/etc':'/private/etc'}; fs.realpath('/etc/passwd', cache, function (err, resolvedPath) { if (err) throw err; console.log(resolvedPath); }); ~~~ ### fs.realpathSync(path, [cache]) realpath(2) 的同步版本。返回解析出的路徑。 ### fs.unlink(path, callback) 異步版的 unlink(2). 完成時的回調函數（callback）只接受一個參數：可能出現的異常信息. ### fs.unlinkSync(path) 同步版的 unlink(2). ### fs.rmdir(path, callback) 異步版的 rmdir(2). 異步版的 link(2). 完成時的回調函數（callback）只接受一個參數：可能出現的異常信息。 ### fs.rmdirSync(path) 同步版的 rmdir(2). ### fs.mkdir(path, [mode], callback) 異步版的 mkdir(2)。異步版的 link(2). 完成時的回調函數（callback）只接受一個參數：可能出現的異常信息。文件 `mode` 默認為 `0777`。 ### fs.mkdirSync(path, [mode]) 同步版的 mkdir(2)。 ### fs.readdir(path, callback) 異步版的 readdir(3)。讀取 path 路徑所在目錄的內容。回調函數 (callback) 接受兩個參數 `(err, files)` 其中 `files` 是一個存儲目錄中所包含的文件名稱的數組，數組中不包括 `'.'` 和 `'..'`。 ### fs.readdirSync(path) 同步版的 readdir(3). 返回文件名數組，其中不包括 `'.'` 和 `'..'` 目錄. ### fs.close(fd, callback) 異步版 close(2). 完成時的回調函數(callback)只接受一個參數:可能出現的異常信息. ### fs.closeSync(fd) 同步版的 close(2). ### fs.open(path, flags, [mode], callback) 異步版的文件打開. 詳見 open(2). `flags` 可以是: - `'r'` - 以【只讀】的方式打開文件. 當文件不存在時產生異常. - `'r+'` - 以【讀寫】的方式打開文件. 當文件不存在時產生異常. - `'rs'` - 同步模式下，以【只讀】的方式打開文件. 指令繞過操作系統的本地文件系統緩存. 該功能主要用于打開 NFS 掛載的文件, 因為它可以讓你跳過默認使用的過時本地緩存. 但這實際上非常影響 I/O 操作的性能, 因此除非你確實有這樣的需求, 否則請不要使用該標志. 注意: 這并不意味著 `fs.open()` 變成了一個同步阻塞的請求. 如果你想要一個同步阻塞的請求你應該使用 `fs.openSync()`. - `'rs+'` - 同步模式下, 以【讀寫】的方式打開文件. 請謹慎使用該方式, 詳細請查看 `'rs'` 的注釋. - `'w'` - 以【只寫】的形式打開文件. 文件會被創建 (如果文件不存在) 或者覆蓋 (如果存在). - `'wx'` - 類似 `'w'` 區別是如果文件存在則操作會失敗. - `'w+'` - 以【讀寫】的方式打開文件. 文件會被創建 (如果文件不存在) 或者覆蓋 (如果存在). - `'wx+'` - 類似 `'w+'` 區別是如果文件存在則操作會失敗. - `'a'` - 以【附加】的形式打開文件，即新寫入的數據會附加在原來的文件內容之后. 如果文件不存在則會默認創建. - `'ax'` - 類似 `'a'` 區別是如果文件存在則操作會失敗. - `'a+'` - 以【讀取】和【附加】的形式打開文件. 如果文件不存在則會默認創建. - `'ax+'` - 類似 `'a+'` 區別是如果文件存在則操作會失敗. 參數 `mode` 用于設置文件模式 (permission and sticky bits), 不過前提是這個文件是已存在的. 默認情況下是 `0666`, 有可讀和可寫權限. 該 callback 接收兩個參數 `(err, fd)`. 排除 (exclusive) 標識 `'x'` （對應 open(2) 的 `O_EXCL` 標識）保證 `path` 是一個新建的文件。 POSIX 操作系統上，即使 `path` 是一個指向不存在位置的符號鏈接，也會被認定為文件存在。排除標識在網絡文件系統不能確定是否有效。在 Linux 上，無法對以追加 (append) 模式打開的文件進行指定位置的寫入操作。內核會忽略位置參數并且總是將數據追加到文件尾部。 ### fs.openSync(path, flags, [mode]) `fs.open()` 的同步版. ### fs.utimes(path, atime, mtime, callback) ### fs.utimesSync(path, atime, mtime) 更改 path 所指向的文件的時間戳。 ### fs.futimes(fd, atime, mtime, callback) ### fs.futimesSync(fd, atime, mtime) 更改文件描述符 (file discriptor) 所指向的文件的時間戳。 ### fs.fsync(fd, callback) 異步版本的 fsync(2)。回調函數僅含有一個異常 (exception) 參數。 ### fs.fsyncSync(fd) fsync(2) 的同步版本。 ### fs.write(fd, buffer, offset, length[, position], callback) 通過文件標識`fd`，向指定的文件中寫入`buffer`。 `offset` 和`length` 可以確定從哪個位置開始寫入buffer。 `position` 是參考當前文檔光標的位置，然后從該處寫入數據。如果`typeof position !== 'number'`，那么數據會從當前文檔位置寫入，請看pwrite(2)。回調中會給出三個參數 `(err, written, buffer)`，`written` 說明從`buffer`寫入的字節數。注意，`fs.write`多次地在同一個文件中使用而沒有等待回調是不安全的。在這種情況下，強烈推薦使用`fs.createWriteStream`。在 Linux 上，無法對以追加 (append) 模式打開的文件進行指定位置的寫入操作。內核會忽略位置參數并且總是將數據追加到文件尾部。 ### fs.write(fd, data[, position[, encoding]], callback) 把`data`寫入到文檔中通過指定的`fd`,如果`data`不是buffer對象的實例則會把值強制轉化成一個字符串。 `position` 是參考當前文檔光標的位置，然后從該處寫入數據。如果`typeof position !== 'number'`，那么數據會從當前文檔位置寫入，請看pwrite(2)。 `encoding` 是預期得到一個字符串編碼回調會得到這些參數 `(err, written, string)`，`written`表明傳入的`string`需要寫入的字符串長度。注意字節的寫入跟字符串寫入是不一樣的。請看[Buffer.byteLength](#). 與寫入`buffer`不同，必須寫入完整的字符串，截取字符串不是符合規定的。這是因為返回的字節的位移跟字符串的位移是不一樣的。注意，`fs.write`多次地在同一個文件中使用而沒有等待回調是不安全的。在這種情況下，強烈推薦使用`fs.createWriteStream`。在 Linux 上，無法對以追加 (append) 模式打開的文件進行指定位置的寫入操作。內核會忽略位置參數并且總是將數據追加到文件尾部。 ### fs.writeSync(fd, buffer, offset, length[, position]) ### fs.writeSync(fd, data[, position[, encoding]]) 同步版本的`fs.write()`。返回寫入的字節數。 ### fs.read(fd, buffer, offset, length, position, callback) 從指定的文檔標識符`fd`讀取文件數據。 `buffer` 是緩沖區，數據將會寫入這里。 `offset` 是開始向緩沖區 `buffer` 寫入的偏移量。 `length` 是一個整形值，指定了讀取的字節數。 `position` 是一個整形值，指定了從哪里開始讀取文件，如果`position`為`null`，將會從文件當前的位置讀取數據。回調函數給定了三個參數， `(err, bytesRead, buffer)`，分別為錯誤，讀取的字節和緩沖區。 ### fs.readSync(fd, buffer, offset, length, position) `fs.read` 函數的同步版本。返回`bytesRead`的個數。 ### fs.readFile(filename, [options], callback) - `filename` {String} - `options` {Object} - `encoding` {String | Null} default = `null` - `flag` {String} default = `'r'` - `callback` {Function} 異步讀取一個文件的全部內容。舉例： ~~~ fs.readFile('/etc/passwd', function (err, data) { if (err) throw err; console.log(data); }); ~~~ 回調函數傳遞了兩個參數 `(err, data)`, `data` 就是文件的內容。如果未指定編碼方式，原生buffer就會被返回。 ### fs.readFileSync(filename, [options]) `fs.readFile`的同步版本。返回文件名為 `filename` 的文件內容。如果 `encoding` 選項被指定，那么這個函數返回一個字符串。如果未指定，則返回一個原生buffer。 ### fs.writeFile(filename, data, [options], callback) - `filename` {String} - `data` {String | Buffer} - `options` {Object} - `encoding` {String | Null} default = `'utf8'` - `mode` {Number} default = `438` (aka `0666` in Octal) - `flag` {String} default = `'w'` - `callback` {Function} 異步的將數據寫入一個文件, 如果文件原先存在，會被替換。 `data` 可以是一個string，也可以是一個原生buffer。 `encoding` 選項會被忽視如果 `data` 不是string而是原生buffer。`encoding`缺省為 `'utf8'`。實例： ~~~ fs.writeFile('message.txt', 'Hello Node', function (err) { if (err) throw err; console.log('It\'s saved!'); //文件被保存 }); ~~~ ### fs.writeFileSync(filename, data, [options]) `fs.writeFile`的同步版本。 ### fs.appendFile(filename, data, [options], callback) - `filename` {String} - `data` {String | Buffer} - `options` {Object} - `encoding` {String | Null} default = `'utf8'` - `mode` {Number} default = `438` (aka `0666` in Octal) - `flag` {String} default = `'a'` - `callback` {Function} 異步的將數據添加到一個文件的尾部，如果文件不存在，會創建一個新的文件。 `data` 可以是一個string，也可以是原生buffer。實例： ~~~ fs.appendFile('message.txt', 'data to append', function (err) { if (err) throw err; console.log('The "data to append" was appended to file!'); //數據被添加到文件的尾部 }); ~~~ ### fs.appendFileSync(filename, data, [options]) `fs.appendFile`的同步版本。 ### fs.watchFile(filename, [options], listener) ~~~ 穩定性: 2 - 不穩定. 盡可能的話推薦使用 fs.watch 來代替。 ~~~ 監視`filename`指定的文件的改變. 回調函數 `listener` 會在文件每一次被訪問時被調用。第二個參數是可選的。如果提供此參數，`options` 應該是包含兩個成員`persistent`和`interval`的對象，其中`persistent`值為boolean類型。`persistent`指定進程是否應該在文件被監視（watch）時繼續運行，`interval`指定了目標文件被查詢的間隔，以毫秒為單位。缺省值為`{ persistent: true, interval: 5007 }`。 `listener` 有兩個參數，第一個為文件現在的狀態，第二個為文件的前一個狀態。 ~~~ fs.watchFile('message.text', function (curr, prev) { console.log('the current mtime is: ' + curr.mtime); console.log('the previous mtime was: ' + prev.mtime); }); ~~~ `listener`中的文件狀態對象類型為`fs.Stat`。如果你只想在文件被修改時被告知，而不是僅僅在被訪問時就告知，你應當在`listener`回調函數中比較下兩個狀態對象的`mtime`屬性。即`curr.mtime` 和 `prev.mtime`. ### fs.unwatchFile(filename, [listener]) ~~~ 穩定性: 2 - 不穩定. 盡可能的話推薦使用 fs.watch 來代替。 ~~~ 停止監視文件名為 `filename`的文件. 如果 `listener`