Node.js v20.10.0 文档


稳定性: 2 - 稳定

源代码: lib/querystring.js

node:querystring 模块提供了用于解析和格式化网址查询字符串的实用工具。 可以使用以下方式访问它:

The node:querystring module provides utilities for parsing and formatting URL query strings. It can be accessed using:

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

querystring<URLSearchParams> 性能更高,但不是标准化的 API。 当性能不重要或需要与浏览器代码兼容时使用 <URLSearchParams>

querystring is more performant than <URLSearchParams> but is not a standardized API. Use <URLSearchParams> when performance is not critical or when compatibility with browser code is desirable.


querystring.decode() 函数是 querystring.parse() 的别名。

The querystring.decode() function is an alias for querystring.parse().


querystring.encode() 函数是 querystring.stringify() 的别名。

The querystring.encode() function is an alias for querystring.stringify().


querystring.escape() 方法以针对网址查询字符串的特定要求优化的方式对给定的 str 执行网址百分比编码。

The querystring.escape() method performs URL percent-encoding on the given str in a manner that is optimized for the specific requirements of URL query strings.

querystring.escape() 方法被 querystring.stringify() 使用,通常不会被直接使用。 导出它主要是为了允许应用代码在必要时通过将 querystring.escape 分配给替代函数来提供替换的百分比编码实现。

The querystring.escape() method is used by querystring.stringify() and is generally not expected to be used directly. It is exported primarily to allow application code to provide a replacement percent-encoding implementation if necessary by assigning querystring.escape to an alternative function.

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

  • str <string> 要解析的网址查询字符串
  • sep <string> 用于在查询字符串中分隔键值对的子字符串。 默认值: '&'
  • eq <string>。 用于分隔查询字符串中的键和值的子字符串。 默认值: '='
  • options <Object>
    • decodeURIComponent <Function> 当对查询字符串中的百分比编码字符进行解码时使用的函数。 默认值: querystring.unescape()
    • maxKeys <number> 指定要解析的最大键数。 指定 0 以删除键的计数限制。 默认值: 1000

querystring.parse() 方法将网址查询字符串 (str) 解析为键值对的集合。

The querystring.parse() method parses a URL query string (str) into a collection of key and value pairs.

例如,查询字符串 'foo=bar&abc=xyz&abc=123' 被解析为:

For example, the query string 'foo=bar&abc=xyz&abc=123' is parsed into:

  foo: 'bar',
  abc: ['xyz', '123']

querystring.parse() 方法返回的对象不是原型继承自 JavaScript Object。 这意味着 obj.toString()obj.hasOwnProperty() 等典型的 Object 方法没有定义,将不起​​作用。

The object returned by the querystring.parse() method does not prototypically inherit from the JavaScript Object. This means that typical Object methods such as obj.toString(), obj.hasOwnProperty(), and others are not defined and will not work.

默认情况下,查询字符串中的百分比编码字符将被假定为使用 UTF-8 编码。 如果使用替代的字符编码,则需要指定替代的 decodeURIComponent 选项:

By default, percent-encoded characters within the query string will be assumed to use UTF-8 encoding. If an alternative character encoding is used, then an alternative decodeURIComponent option will need to be specified:

// Assuming gbkDecodeURIComponent function already exists...

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

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

  • obj <Object> 要序列化为网址查询字符串的对象
  • sep <string> 用于在查询字符串中分隔键值对的子字符串。 默认值: '&'
  • eq <string>。 用于分隔查询字符串中的键和值的子字符串。 默认值: '='
  • options
    • encodeURIComponent <Function> 当将网址不安全的字符转换为查询字符串中的百分比编码时使用的函数。 默认值: querystring.escape()

querystring.stringify() 方法通过遍历对象的 "自有属性" 从给定的 obj 生成 URL 查询字符串。

The querystring.stringify() method produces a URL query string from a given obj by iterating through the object's "own properties".

它序列化 obj 中传递的以下类型的值: <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]> 数值必须是有限的。 任何其他输入值都将被强制为空字符串。

It serializes the following types of values passed in obj: <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]> The numeric values must be finite. Any other input values will be coerced to empty strings.

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' 

默认情况下,查询字符串中需要百分比编码的字符将被编码为 UTF-8。 如果需要替代的编码,则需要指定替代的 encodeURIComponent 选项:

By default, characters requiring percent-encoding within the query string will be encoded as UTF-8. If an alternative encoding is required, then an alternative encodeURIComponent option will need to be specified:

// Assuming gbkEncodeURIComponent function already exists,

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


querystring.unescape() 方法在给定的 str 上执行网址百分比编码字符的解码。

The querystring.unescape() method performs decoding of URL percent-encoded characters on the given str.

querystring.unescape() 方法被 querystring.parse() 使用,通常不会被直接使用。 导出它主要是为了允许应用代码在必要时通过将 querystring.unescape 分配给替代函数来提供替代的解码实现。

The querystring.unescape() method is used by querystring.parse() and is generally not expected to be used directly. It is exported primarily to allow application code to provide a replacement decoding implementation if necessary by assigning querystring.unescape to an alternative function.

默认情况下,querystring.unescape() 方法将尝试使用 JavaScript 内置的 decodeURIComponent() 方法进行解码。 如果失败,则将使用更安全的不会因格式错误的网址而抛出错误的同类方法。

By default, the querystring.unescape() method will attempt to use the JavaScript built-in decodeURIComponent() method to decode. If that fails, a safer equivalent that does not throw on malformed URLs will be used.