HOWTO · Node.js
在 Node.js 中解析 Json
本教程演示如何在 Node.js 中解析 json
本頁內容
JSON 解析會將 JSON 文字轉換成 JavaScript 值,例如物件、陣列、字串、數字、布林值或 null。如果已經取得 JSON 文字,請在 Node.js 中使用 JSON.parse()。若要讀取本機 JSON 檔案,請先選擇檔案讀取方式,再解析讀取到的文字。以下範例使用 Node.js 的內建模組,並在需要時建立暫存輸入檔。
使用 JSON.parse() 解析 JSON 字串
將 JSON 文字傳入 JSON.parse()。傳回值是一般的 JavaScript 資料,因此你可以存取它的屬性,並在程式的其他部分使用。輸入應該是 JSON 文字。傳入已解析的物件通常是錯誤做法:JSON.parse() 會先將引數轉換成字串,而一般物件通常會變成 [object Object] 之類的文字;這不是有效的 JSON,會造成 SyntaxError。字串轉換行為不同的物件可能會產生不同結果。
執行以下範例:
本節中的程式碼以及顯示的標籤或輸出仍為英文。
const jsonText = '{"name":"Amina","role":"developer"}';
const person = JSON.parse(jsonText);
console.log(person.name);
JSON.parse() 也接受選用的 reviver 函式,可在解析文字時轉換其中的值。大多數應用程式不需要 reviver,除非有特定的轉換需求,否則可以省略。
同步載入本機 JSON 檔案
若是只載入一次的小型靜態設定檔,require() 用起來很簡潔:
本節中的程式碼以及顯示的標籤或輸出仍為英文。
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'json-')), 'settings.json');
fs.writeFileSync(file, '{"theme":"dark"}');
const settings = require(file);
console.log(settings.theme);
使用 require() 載入 JSON 是同步作業,而 Node.js 會快取載入的模組。如果檔案之後在同一個程序中變更,再次對該路徑呼叫 require() 通常會傳回快取值。若資料必須反映檔案變更,請改用 fs.readFileSync() 或 fs.readFile()。雖然可以手動清除 require.cache,但通常會讓應用程式的行為更難理解。
如果程式必須先讀完本機檔案才能繼續,請使用 fs.readFileSync()。指定 utf8 等編碼即可取得字串,接著再呼叫 JSON.parse():
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'json-')), 'settings.json');
fs.writeFileSync(file, '{"theme":"dark"}');
const text = fs.readFileSync(file, 'utf8');
const settings = JSON.parse(text);
console.log(settings.theme);
若未指定編碼,fs.readFileSync() 會傳回 Buffer,而不是字串。JSON.parse() 需要文字,因此請指定編碼,或使用 .toString('utf8') 將緩衝區轉成字串。同步讀取檔案時,事件迴圈會在讀取期間遭到阻塞;這適合用於啟動程式碼或短小的指令碼,但應避免在處理請求時執行耗時或讀取大型檔案的同步操作。
非同步讀取並解析本機 JSON 檔案
fs.readFile() 會啟動非同步檔案讀取,並在作業完成時呼叫回呼函式。請先檢查回呼中的錯誤,再進行解析,避免將不存在或無法讀取的檔案傳給 JSON.parse():
本節中的程式碼以及顯示的標籤或輸出仍為英文。
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'json-')), 'settings.json');
fs.writeFileSync(file, '{"theme":"dark"}');
fs.readFile(file, 'utf8', (err, text) => {
if (err) {
console.error(`Could not read JSON file: ${err.message}`);
return;
}
const settings = JSON.parse(text);
console.log(settings.theme);
});
console.log('Reading has started.');
檔案讀取是非同步的,因此 Node.js 在等待檔案作業期間仍可繼續處理其他工作。JSON.parse() 本身仍是同步的:讀取完成後,解析非常大的字串仍可能占用事件迴圈。如果解析失敗,產生的 SyntaxError 會在回呼函式內拋出,應在該處處理,或交由適當的錯誤處理流程處理。
處理無效 JSON 與檔案錯誤
檔案錯誤和解析錯誤的成因不同,應分開處理。讀取錯誤表示程式沒有取得文字;JSON 格式錯誤則表示程式取得的文字不符合 JSON 語法。若讀取回呼回報錯誤,請勿嘗試解析。
當輸入可能格式錯誤時,請將 JSON.parse() 放在 try...catch 中。捕捉 SyntaxError 後,可以顯示有用的訊息,或採取復原策略。避免直接將錯誤資料靜默替換成空物件:這可能會掩蓋檔案損毀,讓後續問題更難診斷。若使用同步讀取,除了處理 JSON.parse() 的解析錯誤,也要處理讀取時發生的檔案系統錯誤。
以下範例會在成功讀取後處理格式錯誤的文件:
本節中的程式碼以及顯示的標籤或輸出仍為英文。
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'json-')), 'settings.json');
fs.writeFileSync(file, '{"theme":}');
fs.readFile(file, 'utf8', (err, text) => {
if (err) {
console.log(`Could not read file: ${err.message}`);
return;
}
try {
JSON.parse(text);
console.log('JSON parsed successfully.');
} catch (error) {
if (error instanceof SyntaxError) {
console.log('The file contains malformed JSON.');
} else {
console.log(`Unexpected error: ${error.message}`);
}
}
});
如果回呼收到檔案系統錯誤,請回報或傳遞該錯誤,並在解析前返回。在以 Promise 為基礎的程式碼中也應採取相同的區分方式:處理讀取作業的拒絕,並在執行 JSON.parse() 的位置捕捉解析錯誤。
為大型或會變動的資料選擇合適方法
如果 JSON 文字已在記憶體中,直接使用 JSON.parse()。如果是只載入一次的小型穩定 JSON 設定,可使用 require(),並利用模組快取。如果簡單的啟動流程適合等到檔案可用後再繼續,可使用 fs.readFileSync()。如果程式應在檔案 I/O 等待期間繼續執行,可使用 fs.readFile(),並務必在解析前檢查它的錯誤引數。
對於非常大的 JSON 輸入,讀取整個檔案並建立完整的 JavaScript 值可能會消耗大量記憶體,而且解析大型字串仍是同步作業。串流解析器可以逐步處理適合的格式,但會增加複雜度,也可能需要額外套件,或要求資料採用適合串流處理的格式。只有在測量結果與資料格式都支持這項取捨時,才選擇串流解析。如果檔案可能變更,且需要取得最新內容,請使用檔案系統 API 再次讀取;require() 的快取不會自動更新。