Node.js v26.0.0 說明文件

Query string#

node:querystring 模組提供了用於解析與格式化 URL 查詢字串（query string）的工具。可以透過以下方式存取：

const querystring = require('node:querystring');
copy

querystring 比 <URLSearchParams> 更具效能，但它並非標準化的 API。若效能並非關鍵，或者需要與瀏覽器程式碼保持相容性，建議使用 <URLSearchParams>。

querystring.decode()#

querystring.decode() 函式是 querystring.parse() 的別名。

querystring.encode()#

querystring.encode() 函式是 querystring.stringify() 的別名。

querystring.escape(str)#

• str <string>

querystring.escape() 方法對給定的 str 執行 URL 百分比編碼（percent-encoding），該方式已針對 URL 查詢字串的特定需求進行了最佳化。

querystring.escape() 方法由 querystring.stringify() 所使用，通常不建議直接使用。匯出此方法主要是為了讓應用程式碼在必要時，透過將 querystring.escape 指派為替代函式，來提供自訂的百分比編碼實作。

querystring.parse(str[, sep[, eq[, options]]])#

• str <string> 要解析的 URL 查詢字串。
• sep <string> 用於界定查詢字串中鍵值對的子字串。預設值： '&'。
• eq <string> 用於界定查詢字串中鍵與值的子字串。預設值： '='。
• options <Object>
  • decodeURIComponent <Function> 在解碼查詢字串中百分比編碼字元時使用的函式。預設值： querystring.unescape()。
  • maxKeys <number> 指定要解析的最大鍵數量。指定 0 以移除鍵數限制。預設值： 1000。

querystring.parse() 方法將 URL 查詢字串 (str) 解析為鍵值對的集合。

例如，查詢字串 'foo=bar&abc=xyz&abc=123' 被解析為：

{
  "foo": "bar",
  "abc": ["xyz", "123"]
}
copy

由 querystring.parse() 方法回傳的物件不會從 JavaScript Object 原型繼承。這意味著常見的 Object 方法（如 obj.toString()、obj.hasOwnProperty() 等）未被定義且無法運作。

預設情況下，查詢字串內的百分比編碼字元會被視為使用 UTF-8 編碼。如果使用其他字元編碼，則需要指定替代的 decodeURIComponent 選項。

// Assuming gbkDecodeURIComponent function already exists...

querystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null,
                  { decodeURIComponent: gbkDecodeURIComponent });
copy

querystring.stringify(obj[, sep[, eq[, options]]])#

• obj <Object> 要序列化為 URL 查詢字串的物件。
• sep <string> 用於界定查詢字串中鍵值對的子字串。預設值： '&'。
• eq <string> 用於界定查詢字串中鍵與值的子字串。預設值： '='。
• 選項 (options)
  • encodeURIComponent <Function> 在將 URL 不安全字元轉換為百分比編碼時使用的函式。預設值： querystring.escape()。

querystring.stringify() 方法透過迭代給定 obj 的「自有屬性」（own properties）來產生 URL 查詢字串。

它會序列化在 obj 中傳入的下列型別的值：<string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]>。數值必須是有限的（finite）。任何其他輸入值將被強制轉換為空字串。

querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });
// Returns 'foo=bar&baz=qux&baz=quux&corge='

querystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':');
// Returns 'foo:bar;baz:qux'
copy

預設情況下，查詢字串中需要百分比編碼的字元將被編碼為 UTF-8。如果需要其他編碼，則需要指定替代的 encodeURIComponent 選項。

// Assuming gbkEncodeURIComponent function already exists,

querystring.stringify({ w: '中文', foo: 'bar' }, null, null,
                      { encodeURIComponent: gbkEncodeURIComponent });
copy

querystring.unescape(str)#

• str <string>

querystring.unescape() 方法對給定的 str 執行 URL 百分比編碼字元的解碼。

querystring.unescape() 方法由 querystring.parse() 所使用，通常不建議直接使用。匯出此方法主要是為了讓應用程式碼在必要時，透過將 querystring.unescape 指派為替代函式，來提供自訂的解碼實作。

預設情況下，querystring.unescape() 方法會嘗試使用 JavaScript 內建的 decodeURIComponent() 方法進行解碼。如果解碼失敗，則會改用一種在遇到畸形 URL 時不會拋出錯誤的安全替代方案。