[TOC] >[success] # 文件讀取api | API | 優點 | 缺點 | | --- | --- | --- | | `fs.readFileSync` | 簡單易用 | 阻塞式 I/O，可能會影響應用程序的性能 | | `fs.readFile` | 非阻塞式 I/O，不會影響應用程序的性能 | 需要使用回調函數處理讀取到的數據 | | `fs.createReadStream` | 適合讀取大型文件，不會將整個文件加載到內存中，可節省內存 | 需要使用 `pipe` 方法將數據流導向其他流或響應對象 | | `fs.promises.readFile` | 支持 Promise，使用 async/await 可以編寫更加簡潔的異步代碼 | 只在 Node.js 10.x 版本及以上支持 | | `fs.read` | 可以更加精細地控制讀取文件的過程，例如指定讀取的起始位置和長度 | 使用較為繁瑣，需要手動處理讀取到的數據 | 需要注意的是，選擇使用哪種 API 取決于具體的場景和需求。例如，如果需要讀取大型文件而又不想將整個文件加載到內存中，就可以使用 `fs.createReadStream`。如果需要編寫簡潔易讀的異步代碼，就可以使用 `fs.promises.readFile` 或者使用第三方模塊 `fs-extra` 中提供的 `fs.readFileAsync`（在 Node.js 8.x 版本及以上支持）等等。 如果你的 Node.js 版本不低于 8.x，那么你可以使用第三方模塊 `fs-extra` 中提供的 `fs.readFileAsync` 方法來讀取文件。`fs-extra` 是一個擴展了 Node.js 原生 fs 模塊功能的第三方模塊，相較于原生 fs 模塊，它提供了更加方便的 API，并且在使用上也更加簡單。`fs-extra` 中的 `fs.readFileAsync` 方法與 Node.js 原生的 `fs.promises.readFile` 方法類似，都是 Promise 形式的異步讀取文件方法，用法也相 >[info] ## 文件讀取須知 1. 當我們需要讀取一個文件時，可以使用`Node.js`中的`fs`模塊 * **fs.readFileSync(path\[, options\])**：同步讀取文件內容，返回一個Buffer對象或字符串。 * **fs.readFile(path\[, options\], callback)**：異步讀取文件內容，將內容作為回調函數的第二個參數返回。 2. 對一些flag 標簽說明 * ` r`：以只讀模式打開文件。 * `r+`：以讀寫模式打開文件，如果不存在那么拋出異常；。 * `'rs+'`: 以同步模式打開文件進行讀寫。 指示操作系統繞過本地文件系統緩存。 * `w`：以寫入模式打開文件，如果文件存在，則覆蓋該文件，如果文件不存在，則創建該文件。 * `wx`：類似于w，但是如果文件已經存在，則操作失敗。 * `w+`：以讀寫模式打開文件，如果文件存在，則覆蓋該文件，如果文件不存在，則創建該文件。 * `wx+`：類似于w+，但是如果文件已經存在，則操作失敗。 * `a`：以追加模式打開文件，如果文件不存在，則創建該文件。寫入內容在文章末尾 * `ax`：類似于a，但是如果文件已經存在，則操作失敗。 * `a+`：以讀取和追加模式打開文件，如果文件不存在，則創建該文件。寫入內容在文章末尾 * `ax+`：類似于a+，但是如果文件已經存在，則操作失敗。 * `'as'`: 以同步模式打開文件進行追加。 如果文件不存在，則創建該文件。 * `'as+'`: 以同步模式打開文件進行讀取和追加。 如果文件不存在，則創建該文件 3. 對 encoding 一些類型說明 * `'utf8'`或'`utf-8'` - UTF-8編碼格式 * `'utf16le'` - UTF-16LE編碼格式 * `'latin1'`或`'iso-8859-1'` - ISO-8859-1編碼格式 * ` 'base64'` - Base64編碼格式 * ` 'hex' `- 十六進制編碼格式 例如，我們可以使用以下代碼以UTF-8編碼格式讀取文件內容： 4. **flag參數為**'w'，但是這并不代表可以用它來進行寫入操作。實際上，當flag參數設置為'w'時，只是表示以寫入方式打開文件，但是并沒有執行實際的寫入操作,同理使用`a` 也是如此 >[danger] ### fs.readFileSync(path\[, options\]) 同步讀取 * fs.readFileSync方法的參數及其說明，其中，**path參數是必需的**，用于指定要讀取的文件的路徑。**options參數是可選的**，用于指定讀取文件的選項，其中encoding和flag屬性也是可選的。**如果未指定options參數則是使用只讀模式r并且返回一個Buffer對象，則默認以二進制格式讀取文件內容**，**如果未指定encoding，則返回一個Buffer對象，則默認以二進制格式讀取文件內容**，如果**未指定flag，則默認以只讀模式（r）打開文件。**， >[danger] ##### api 說明 | 參數 | 類型 | 說明 | | --- | --- | --- | | path | string | 要讀取的文件的路徑 | | options | object | 可選的配置對象，用于指定讀取文件的選項 | | options.encoding | string | 指定文件的編碼格式，如果未指定則返回Buffer對象 | | options.flag | string | 指定文件的打開方式，默認為'r'，可選的打開方式包括：'r', 'r+', 'rs+', 'w', 'wx', 'w+', 'wx+', 'a', 'ax', 'a+', 'ax+' | >[danger] ##### 案例 ~~~ const fs = require('fs') // node 13 以后版本可以寫成const fs = require('node:fs') // 讀取文件內容為 1111111111 文件路徑為 ./a.txt // 1.同步讀取文件只讀模式r并且返回一個Buffer對象，則默認以二進制格式讀取文件內容 const data = fs.readFileSync('./a.txt') console.log(data) // <Buffer 31 31 31 31 31 31 31 31 31 31> console.log(data.toString()) // 1111111111 toString()方法默認是utf-8 格式 將Buffer對象轉換為字符串 // 2. 同步讀取文件規定返回編碼格式utf-8 const data1 = fs.readFileSync('./a.txt', 'utf-8') console.log(data1) // 1111111111 // 3. 同步讀取文件規定返回編碼和文件讀取模式 const data2 = fs.readFileSync('./a.txt', { encoding: 'utf-8', flag: 'r' }) console.log(data1) // 1111111111 ~~~ 同步的 API 會阻塞 Node.js 事件循環和下一步的 JavaScript 執行，直到操作完成。 異常會被立即地拋出，可以使用`try…catch`來處理，也可以允許冒泡。 ~~~js const { readFileSync} = require('fs'); try { readFileSync('/tmp/hello'); } catch (err) { // 處理錯誤 } ~~~ >[danger] ### fs.readFile(path\[, options\], callback) 異步讀取 1. `fs.readFile()`是Node.js文件系統模塊中提供的一個異步文件讀取函數 2. `fs.readFile()`函數會異步讀取文件，當文件讀取完成后，會調用回調函數，將文件內容傳遞給回調函數。如果讀取文件失敗，會將錯誤對象傳遞給回調函數。需要注意的是，如果文件較大，使用`fs.readFile()`函數可能會導致性能問題，可以使用`fs.createReadStream()`函數來讀取文件流，并逐塊處理讀取的數據。 3. `path`參數表示要讀取的文件的路徑或文件的URL，可以是一個字符串、緩沖區或URL對象，也可以是一個文件描述符；`options`參數是一個可選的對象，包含編碼方式、文件讀取模式等等設置，或者是一個字符串，表示編碼方式；`callback`參數是讀取文件完成后的回調函數，回調函數有兩個參數：`err`和`data`，其中`err`為Error對象，如果讀取成功，`err`為null；`data`為文件的內容，如果指定了 4. **如果未指定options參數則是使用只讀模式r并且返回一個Buffer對象，則默認以二進制格式讀取文件內容**，**如果未指定encoding，則返回一個Buffer對象，則默認以二進制格式讀取文件內容**，如果**未指定flag，則默認以只讀模式（r）打開文件。** >[danger] ##### api說明 | 參數 | 類型 | 描述 | | --- | --- | --- | | path | string | Buffer | URL | integer | 要讀取的文件的路徑或文件的URL，可以是一個字符串、緩沖區或URL對象，也可以是一個文件描述符。 | | options | Object | string | 一個可選的參數對象，包含編碼方式、文件讀取模式等等設置，或者是一個字符串，表示編碼方式。 | | options.encoding | string | null | 字符編碼方式。默認值為null，表示讀取的是Buffer對象。如果指定了編碼方式，則返回一個字符串。 | | options.flag | string | 文件打開的模式。默認是'r'，表示只讀。具體的可選值請參考文件系統的flags支持。 | | options.signal | AbortSignal | AbortSignal對象，用于在讀取文件時中止讀取操作。 | | callback | Function | 讀取文件完成后的回調函數，回調函數有兩個參數：err和data，其中err為Error對象，如果讀取成功，err為null；data為文件的內容，如果指定了options.encoding，則data為一個字符串，否則為一個Buffer對象。 | >[danger] ##### 案例 ~~~ const fs = require('node:fs') // 讀取文件內容為 1111111111 文件路徑為 ./a.txt // 1. 異步讀取文件只讀模式r并且返回一個Buffer對象，則默認以二進制格式讀取文件內容 fs.readFile('./a.txt', (err, data) => { if (err) { console.log(err) return } console.log(data) // <Buffer 31 31 31 31 31 31 31 31 31 31> console.log(data.toString()) // 1111111111 }) // 2. 異步讀取文件規定返回編碼格式utf-8 fs.readFile('./a.txt', 'utf-8', (err, data) => { if (err) { console.log(err) return } console.log(data) // 1111111111 }) // 3. 異步讀取文件規定返回編碼和文件讀取模式 fs.readFile('./a.txt', { encoding: 'utf-8', flag: 'r' }, (err, data) => { if (err) { console.log(err) return } console.log(data) // 1111111111 }) ~~~ * `options.signal`是一個可選的參數，用于傳遞`AbortSignal`對象，用于在讀取文件時中止讀取操作。`AbortSignal`是一個可以用于終止某些操作的信號對象。當調用`AbortSignal.abort()`函數時，可以向一個或多個正在進行的異步操作發送一個中止信號以取消操作。如果在讀取文件時傳遞了一個`AbortSignal`對象，并且在讀取過程中接收到中止信號，那么`fs.readFile()`函數將停止讀取文件，并立即調用回調函數，將一個AbortError對象傳遞給它。 ~~~ const fs = require('fs') // 創建一個中止控制器 const controller = new AbortController() // 獲取中止信號 const signal = controller.signal // 讀取文件 const options = { signal } fs.readFile('./a.txt', options, (err, data) => { if (err) { // 如果是中止錯誤，打印錯誤信息 if (err.code === 'ABORT_ERR') { console.log('File read operation aborted') } else { // 否則打印錯誤信息 console.error(err) } } else { // 打印文件內容 console.log(`File contents: ${data}`) } }) // 在2秒后中止讀取文件操作 setTimeout(() => { controller.abort() // 中止讀取文件操作 }) ~~~ >[danger] ### fsPromises.readFile(path[, options]) `fsPromises.readFile(path[, options])` 是 Node.js v10.0.0 及以上版本中引入的 Promise 形式的異步讀取文件 API，它返回一個 Promise 實例，可以通過 `await` 或 `then` 方法獲取讀取到的文件內容。**該方法和 `fs.readFile` 的功能相同，只不過不需要傳遞回調函數，而是直接通過 Promise 的方式處理異步操作的結果** >[danger] ##### api說明 | 參數 | 類型 | 描述 | | --- | --- | --- | | `path` | `string` | `Buffer` | `URL` | `FileHandle` | 必需參數，文件名或 `FileHandle` 對象 | | `options` | `Object` | `string` | 可選參數，可以是一個包含以下屬性的對象或一個字符串 | | `options.encoding` | `string` | `null` | 可選參數，指定文件編碼。如果不指定編碼，則返回一個 `Buffer` 對象 | | `options.flag` | `string` | 可選參數，指定文件的打開方式。默認為 `'r'`，表示以讀取模式打開文件 | | `options.signal` | `AbortSignal` | 可選參數，允許中止正在進行的讀取文件的操作 | >[danger] ##### 案例 * 具體細節可參考**fs.readFile(path[, options], callback) 異步讀取** ~~~ const fs = require('fs') // const readFile= require('fs').promises // const readFile= require('fs/promises') fs.promises.readFile('./aaa.txt', { encoding: 'utf-8' }).then(res => { console.log("獲取到結果:", res) }).catch(err => { console.log("發生了錯誤:", err) }) ~~~ >[danger] ### fs.createReadStream(path[, options]) 1. `fs.createReadStream`方法來**創建一個可讀流，使用可讀流的方式讀取文件時，數據會被分成小塊逐步讀入內存，而不是一次性讀取整個文件**， 2. 可以通過指定要讀取的文件路徑或者直接使用這個`fd`創建通過`fs.createReadStream` 創建`ReadStream`對象 3. 通過`ReadStream`對象，**我們可以從文件中讀取數據，并將其轉換為我們需要的格式。例如，我們可以讀取一個文本文件，并將其轉換為字符串，或者讀取一個二進制文件，并將其轉換為Buffer對象** 4. 創建一個`ReadStream`對象時，它會自動將文件分成一塊塊的數據進行讀取。可以通過設置`highWaterMark`屬性來控制每塊數據的大小。**當我們讀取的數據量超過`highWaterMark`大小時，`ReadStream`對象將自動暫停讀取**，等待我們處理已經讀取的數據。當我們處理完數據后，`ReadStream`對象會自動恢復讀取，繼續讀取下一塊數據 5. 當我們不再需要`ReadStream`對象時，應該及時銷毀它，以免造成資源浪費。銷毀`ReadStream`對象后，它會自動關閉文件描述符，觸發'close'事件。如果我們希望在銷毀對象時不觸發'close'事件，可以設置`emitClose`選項為`false`。 6. 一些優缺點對照表 | 優點 | 缺點 | | --- | --- | | 內存使用效率高，減少內存使用量 | 實現復雜，需要處理多個事件和回調函數 | | 速度快，避免一次性將整個文件讀入內存的延遲 | 可讀性差，代碼結構較復雜，可讀性相對較差 | | 數據處理靈活，可以逐塊處理數據 | 不適合小文件，可能會增加代碼的復雜性，不會帶來很大的性能優勢 | | 可以控制讀取的范圍，讀取部分內容 | 可靠性差，可能出現數據丟失或不完整，需要處理錯誤和異常情況 | >[danger] ##### api 說明 `api` 參數說明，當`options.autoClose`設置為`true`時，當讀取流結束時會自動關閉底層文件描述符（file descriptor）或文件句柄（file handle），也就是說，當讀取流讀取完所有數據后，底層的文件描述符或文件句柄將被自動關閉。 當`options.emitClose`設置為`true`時，讀取流會在底層文件描述符或文件句柄關閉時觸發 'close' 事件，這個事件觸發后，讀取流的 'close' 事件也會被觸發。如果`options.emitClose`設置為`false`，則不會觸發 'close' 事件。注意，即使`options.emitClose`設置為`false`，當讀取流結束時，底層的文件描述符或文件句柄仍然會被自動關閉，除非`options.autoClose`設置為`false`。 `options.fs`參數是一個可選的文件系統對象，這個參數通常用于測試或開發環境中后續用到在了解 | 參數名 | 類型 | 描述 | 默認值 | | --- | --- | --- | --- | | path | string | Buffer | URL | 要讀取的文件的路徑或文件描述符 | 無 | | options | string | Object | 可選對象，可以包含以下屬性 | 無 | | options.flags | string | 請參閱支持的文件系統標志 | 'r' | | options.encoding | string | 編碼格式 | null | | options.fd | integer | FileHandle | 文件描述符 | null | | options.mode | integer | 文件的權限掩碼 | 0o666 | | options.autoClose | boolean | 自動關閉標志 | true | | options.emitClose | boolean | 關閉事件標志 | true | | options.start | integer | 起始位置（以字節為單位） | 0 | | options.end | integer | 結束位置（以字節為單位） | Infinity | | options.highWaterMark | integer | 每次讀取的最大字節數 | 64 \* 1024 | | options.fs | Object | null | 文件系統對象 | null | >[danger] ##### 案例 | **事件** | **描述** | | --- | --- | | `data` | 當流讀取到數據時觸發。 | | `end` | 當流讀取完所有數據時觸發。 | | `error` | 當流發生錯誤時觸發。 | ~~~ const fs = require('fs') // 1. 獲取readStream 流 const stream = fs.createReadStream('./b.txt') console.log(12) // 2. 監聽流的data事件 stream.on('data', (chunk) => { console.log(chunk.toString()) }) // 3. 監聽流的end事件 stream.on('end', () => { console.log('end') }) // 4. 監聽流的error事件 stream.on('error', (err) => { console.log(err) }) // 5. 監聽流的close事件 stream.on('close', () => { console.log('close') }) // 6. 監聽流的open事件 stream.on('open', () => { console.log('open') }) ~~~ * 使用 fd 讀取文件 ~~~ const fs = require('fs') const fd = fs.openSync('./a.txt') // 1. 獲取readStream 流 const stream = fs.createReadStream(null, { fd, highWaterMark: 3 }) console.log(12) // 2. 監聽流的data事件 stream.on('data', (chunk) => { console.log(chunk.toString()) }) // 3. 監聽流的end事件 stream.on('end', () => { console.log('end') }) // 4. 監聽流的error事件 stream.on('error', (err) => { console.log(err) }) // 5. 監聽流的close事件 stream.on('close', () => { console.log('close') }) // 6. 監聽流的open事件 stream.on('open', () => { console.log('open') }) ~~~ >[danger] ##### 案例二 | **方法** | **描述** | | --- | --- | | `pause()` | 用于暫停可讀流的數據讀取，調用該方法后，可讀流將不會再觸發 'data' 事件，直到調用`resume()`方法恢復數據讀取。該方法通常用于暫停數據讀取，以便進行某些操作或等待其他事件發生。 | | `resume()` | 用于恢復可讀流的數據讀取，調用該方法后，可讀流將繼續觸發 'data' 事件，從而讀取數據。該方法通常用于恢復數據讀取，以便繼續處理數據。 | | `pipe()` | 用于將一個可讀流連接到一個可寫流，將可讀流中的數據輸出到可寫流中。該方法會自動管理數據流動，從而實現高效的數據傳輸。該方法還可以接收一個可選的參數，用于控制數據傳輸的方式和行為，例如是否自動關閉可寫流、是否允許多個可寫流等 | | `unpipe()` | 用于停止將可讀流中的數據輸出到另一個可寫流中，取消數據傳輸。可以將一個可寫流對象作為參數傳遞給該方法，表示只取消將指定的可寫流對象中的數據輸出，如果不傳遞參數，則表示取消所有的數據輸出。該方法通常用于在數據傳輸過程中動態取消數據輸出，以便進行其他操作或處理錯誤。 | * 關于方法使用，這里只是列舉部分更多詳細需要看`ReadStream` api ***** 用可讀流和可寫流壓縮文件 ~~~js const fs = require('fs'); const zlib = require('zlib'); const readableStream = fs.createReadStream('source.txt'); const gzipStream = zlib.createGzip(); const writableStream = fs.createWriteStream('destination.txt.gz'); readableStream.pipe(gzipStream).pipe(writableStream); ~~~ 使用`fs`模塊的`createReadStream`方法創建可讀流對象`readableStream`，并將其指向源文件`source.txt`。然后，我們在`data`事件中調用`pause`方法暫停數據讀取，并在 1 秒鐘后調用`resume`方法恢復數據讀取 ~~~ const fs = require('fs'); const readableStream = fs.createReadStream('source.txt'); readableStream.on('data', (chunk) => { console.log(chunk.toString()); readableStream.pause(); setTimeout(() => { readableStream.resume(); }, 1000); }); ~~~ 使用 unpipe 方法取消數據輸出，`fs`模塊的`createReadStream`方法創建可讀流對象`readableStream`，并將其指向源文件`source.txt`。同時，我們使用`createWriteStream`方法創建兩個可寫流對象`writableStream1`和`writableStream2`，并將其分別指向兩個目標文件`destination1.txt`和`destination2.txt`。然后，我們使用`pipe`方法將可讀流和兩個可寫流連接起來，將源文件中的數據拷貝到兩個目標文件中。最后，我們在 1 秒鐘后調用`unpipe`方法取消了其中一個數據輸出流的連接，即將可讀流和`writableStream1`的連接斷開，使得數據只輸出到`writableStream2`中 ~~~ const fs = require('fs'); const readableStream = fs.createReadStream('source.txt'); const writableStream1 = fs.createWriteStream('destination1.txt'); const writableStream2 = fs.createWriteStream('destination2.txt'); const pipe1 = readableStream.pipe(writableStream1); const pipe2 = readableStream.pipe(writableStream2); setTimeout(() => { readableStream.unpipe(pipe1); }, 1000); ~~~ >[danger] ### fs.read(fd, buffer, offset, length, position, callback) 1. 當需要從文件中讀取數據時，可以使用 Node.js 的 fs 模塊提供的 fs.read() 方法。該方法的作用是從指定的文件中讀取數據，并將讀取的數據存儲到指定的 Buffer 對象中 2. 在調用` fs.read()` 方法后，`Node.js` 會嘗試從指定的文件中讀取數據，并將讀取的數據存儲到 `buffer `中。讀取的數據量由 `length `參數指定，如果讀取成功，則回調函數會被調用，并將讀取的數據、讀取的字節數和可能出現的錯誤傳遞給回調函數。 3. 在調用` fs.read`() 方法后，Node.js 會嘗試從指定的文件中讀取數據，并將讀取的數據存儲到 buffer 中。讀取的數據量由 length 參數指定，如果讀取成功，則回調函數會被調用，并將讀取的數據、讀取的字節數和可能出現的錯誤傳遞給回調函數。 >[danger] ##### api 參數 | 參數名 | 數據類型 | 描述 | | --- | --- | --- | | fd | Integer | 文件描述符，一個整數，代表文件在操作系統中的標識符。 | | buffer | Buffer | 一個 Buffer 對象，用于存儲讀取的數據。 | | offset | Integer | 寫入數據到 buffer 中的起始位置。 | | length | Integer | 讀取的字節數。 | | position | Integer | 文件中開始讀取數據的位置。可以為 null 或 -1，表示從當前文件位置開始讀取數據。 | | callback | Function | 回調函數，用于處理讀取完數據之后的操作 | >[danger] ##### 案例 ~~~ const fs = require('fs') fs.open('b.txt', (err, fd) => { if (err) { console.log(err) } else { console.log(fd) // 需要能直接操作fd 的api 進行操作讀寫 fs.read(fd, (err, data, buffer) => { if (err) { console.log(err) } else { console.log(buffer.toString(), '--') } // 關閉文件 // fs.close(fd) fs.close(fd, (err) => { if (err) { console.error(err) return } }) }) } }) ~~~ * 通過設置buffer，在 Node.js 中，Buffer 對象是用來表示二進制數據的。因為文件中的數據也是以二進制形式存儲的，所以我們需要一個能夠容納二進制數據的對象來存儲從文件中讀取的數據。 實際上，我們可以不使用 buffer 參數，而是直接將讀取到的數據存儲到一個新的 Buffer 對象中，但是，如果要讀取的文件非常大，那么每次讀取文件時都創建一個新的 Buffer 對象會非常消耗內存。因此，如果我們已經有一個足夠大的 Buffer 對象，就可以將其作為參數傳遞給`fs.read()`方法，這樣可以避免重復分配內存，提高性能。 ~~~ const fs = require('fs') const fileSize = fs.statSync('./a.txt').size console.log(fileSize) const buffer = Buffer.alloc(fileSize) const fd = fs.openSync('./a.txt') // 讀取 從文件的第20個字節開始，讀取個數不超過fileSize - 20個字節 fs.read(fd, buffer, 0, fileSize - 20, 20, (err, bytesRead, buffer) => { if (err) { console.log(err) } console.log(`${bytesRead} bytes read`, buffer.toString()) fs.close(fd, (err) => { if (err) { console.log(err) } }) }) ~~~ >[info] ## esm 的用法案例 ~~~ import { readFile as pReadFile } from 'fs/promises' import { readFileSync } from 'fs' import { readFile } from 'fs' // 1. pReadFile pReadFile('b.txt', 'utf8').then((data) => console.log(data)) // 2. readFileSync const data = readFileSync('b.txt', 'utf8') console.log(data) // 3. readFile readFile('b.txt', 'utf8', (err, data) => { if (err) throw err console.log(data) }) ~~~