URL

稳定性: 2 - 稳定的
url 模块提供了一些实用函数，用于 URL 处理与解析。 可以通过以下方式使用：

const url = require('url');

URL 字符串与 URL 对象

一个 URL 字符串是一个结构化的字符串，它包含多个有意义的组成部分。 当被解析时，会返回一个 URL 对象，它包含每个组成部分作为属性。

The url module provides two APIs for working with URLs: a legacy API that is Node.js specific, and a newer API that implements the same WHATWG URL Standard used by web browsers.

Note: While the Legacy API has not been deprecated, it is maintained solely for backwards compatibility with existing applications. New application code should use the WHATWG API.

A comparison between the WHATWG and Legacy APIs is provided below. Above the URL 'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash', properties of an object returned by the legacy url.parse() are shown. Below it are properties of a WHATWG URL object.

Note: WHATWG URL's origin property includes protocol and host, but not username or password.

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                            href                                             │
├──────────┬──┬─────────────────────┬─────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │        host         │           path            │ hash  │
│          │  │                     ├──────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │   hostname   │ port │ pathname │     search     │       │
│          │  │                     │              │      │          ├─┬──────────────┤       │
│          │  │                     │              │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.host.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │   hostname   │ port │          │                │       │
│          │  │          │          ├──────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │        host         │          │                │       │
├──────────┴──┼──────────┴──────────┼─────────────────────┤          │                │       │
│   origin    │                     │       origin        │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴─────────────────────┴──────────┴────────────────┴───────┤
│                                            href                                             │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
(请忽略字符串中的空格，它们只是为了格式化)

Parsing the URL string using the WHATWG API:

const { URL } = require('url');
const myURL =
  new URL('https://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash');

Note: In Web Browsers, the WHATWG URL class is a global that is always available. In Node.js, however, the URL class must be accessed via require('url').URL.

Parsing the URL string using the Legacy API:

const url = require('url');
const myURL =
  url.parse('https://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash');

The WHATWG URL API

新增于: v7.0.0
Note: Using the delete keyword on URL objects (e.g. delete myURL.protocol, delete myURL.pathname, etc) has no effect but will still return true.

Class: URL

Constructor: new URL(input[, base])

• input <string> The input URL to parse
• base <string> | <URL> The base URL to resolve against if the input is not absolute.

Creates a new URL object by parsing the input relative to the base. If base is passed as a string, it will be parsed equivalent to new URL(base).

const { URL } = require('url');
const myURL = new URL('/foo', 'https://example.org/');
  // https://example.org/foo

A TypeError will be thrown if the input or base are not valid URLs. Note that an effort will be made to coerce the given values into strings. For instance:

const { URL } = require('url');
const myURL = new URL({ toString: () => 'https://example.org/' });
  // https://example.org/

Unicode characters appearing within the hostname of input will be automatically converted to ASCII using the Punycode algorithm.

const { URL } = require('url');
const myURL = new URL('https://你好你好');
  // https://xn--6qqa088eba/

Additional examples of parsed URLs may be found in the WHATWG URL Standard.

url.hash

• <string>

Gets and sets the fragment portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
  // Prints #bar

myURL.hash = 'baz';
console.log(myURL.href);
  // Prints https://example.org/foo#baz

Invalid URL characters included in the value assigned to the hash property are percent-encoded. Note that the selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.host

• <string>

Gets and sets the host portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
  // Prints example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
  // Prints https://example.com:82/foo

Invalid host values assigned to the host property are ignored.

url.hostname

• <string>

Gets and sets the hostname portion of the URL. The key difference between url.host and url.hostname is that url.hostname does not include the port.

const { URL } = require('url');
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
  // Prints example.org

myURL.hostname = 'example.com:82';
console.log(myURL.href);
  // Prints https://example.com:81/foo

Invalid hostname values assigned to the hostname property are ignored.

url.href

• <string>

Gets and sets the serialized URL.

const { URL } = require('url');
const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
  // Prints https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
  // Prints https://example.com/bar

Getting the value of the href property is equivalent to calling url.toString().

Setting the value of this property to a new value is equivalent to creating a new URL object using new URL(value). Each of the URL object's properties will be modified.

If the value assigned to the href property is not a valid URL, a TypeError will be thrown.

url.origin

• <string>

Gets the read-only serialization of the URL's origin. Unicode characters that may be contained within the hostname will be encoded as-is without Punycode encoding.

const { URL } = require('url');
const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
  // Prints https://example.org

const { URL } = require('url');
const idnURL = new URL('https://你好你好');
console.log(idnURL.origin);
  // Prints https://你好你好

console.log(idnURL.hostname);
  // Prints xn--6qqa088eba

url.password

• <string>

Gets and sets the password portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.password);
  // Prints xyz

myURL.password = '123';
console.log(myURL.href);
  // Prints https://abc:123@example.com

Invalid URL characters included in the value assigned to the password property are percent-encoded. Note that the selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.pathname

• <string>

Gets and sets the path portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://example.org/abc/xyz?123');
console.log(myURL.pathname);
  // Prints /abc/xyz

myURL.pathname = '/abcdef';
console.log(myURL.href);
  // Prints https://example.org/abcdef?123

Invalid URL characters included in the value assigned to the pathname property are percent-encoded. Note that the selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.port

• <string>

Gets and sets the port portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
  // Prints 8888

// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
  // Prints the empty string
console.log(myURL.href);
  // Prints https://example.org/

myURL.port = 1234;
console.log(myURL.port);
  // Prints 1234
console.log(myURL.href);
  // Prints https://example.org:1234/

// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
  // Prints 1234

// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
  // Prints 5678

// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
  // Prints 1234

// Out-of-range numbers are ignored
myURL.port = 1e10;
console.log(myURL.port);
  // Prints 1234

The port value may be set as either a number or as a String containing a number in the range 0 to 65535 (inclusive). Setting the value to the default port of the URL objects given protocol will result in the port value becoming the empty string ('').

If an invalid string is assigned to the port property, but it begins with a number, the leading number is assigned to port. Otherwise, or if the number lies outside the range denoted above, it is ignored.

url.protocol

• <string>

Gets and sets the protocol portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://example.org');
console.log(myURL.protocol);
  // Prints https:

myURL.protocol = 'ftp';
console.log(myURL.href);
  // Prints ftp://example.org/

Invalid URL protocol values assigned to the protocol property are ignored.

url.search

• <string>

Gets and sets the serialized query portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);
  // Prints ?123

myURL.search = 'abc=xyz';
console.log(myURL.href);
  // Prints https://example.org/abc?abc=xyz

Any invalid URL characters appearing in the value assigned the search property will be percent-encoded. Note that the selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.searchParams

• <URLSearchParams>

Gets the URLSearchParams object representing the query parameters of the URL. This property is read-only; to replace the entirety of query parameters of the URL, use the url.search setter. See URLSearchParams documentation for details.

url.username

• <string>

Gets and sets the username portion of the URL.

const { URL } = require('url');
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.username);
  // Prints abc

myURL.username = '123';
console.log(myURL.href);
  // Prints https://123:xyz@example.com/

Any invalid URL characters appearing in the value assigned the username property will be percent-encoded. Note that the selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.toString()

• Returns: <string>

The toString() method on the URL object returns the serialized URL. The value returned is equivalent to that of url.href and url.toJSON().

Because of the need for standard compliance, this method does not allow users to customize the serialization process of the URL. For more flexibility, require('url').format() method might be of interest.

url.toJSON()

• Returns: <string>

The toJSON() method on the URL object returns the serialized URL. The value returned is equivalent to that of url.href and url.toString().

This method is automatically called when an URL object is serialized with JSON.stringify().

const { URL } = require('url');
const myURLs = [
  new URL('https://www.example.com'),
  new URL('https://test.example.org')
];
console.log(JSON.stringify(myURLs));
  // Prints ["https://www.example.com/","https://test.example.org/"]

Class: URLSearchParams

新增于: v7.5.0
The URLSearchParams API provides read and write access to the query of a URL. The URLSearchParams class can also be used standalone with one of the four following constructors.

The WHATWG URLSearchParams interface and the querystring module have similar purpose, but the purpose of the querystring module is more general, as it allows the customization of delimiter characters (& and =). On the other hand, this API is designed purely for URL query strings.

const { URL, URLSearchParams } = require('url');

const myURL = new URL('https://example.org/?abc=123');
console.log(myURL.searchParams.get('abc'));
  // Prints 123

myURL.searchParams.append('abc', 'xyz');
console.log(myURL.href);
  // Prints https://example.org/?abc=123&abc=xyz

myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
console.log(myURL.href);
  // Prints https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams);
// The above is equivalent to
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c');
console.log(myURL.href);
  // Prints https://example.org/?a=b
console.log(newSearchParams.toString());
  // Prints a=b&a=c

// newSearchParams.toString() is implicitly called
myURL.search = newSearchParams;
console.log(myURL.href);
  // Prints https://example.org/?a=b&a=c
newSearchParams.delete('a');
console.log(myURL.href);
  // Prints https://example.org/?a=b&a=c

Constructor: new URLSearchParams()

Instantiate a new empty URLSearchParams object.

Constructor: new URLSearchParams(string)

• string <string> A query string

Parse the string as a query string, and use it to instantiate a new URLSearchParams object. A leading '?', if present, is ignored.

const { URLSearchParams } = require('url');
let params;

params = new URLSearchParams('user=abc&query=xyz');
console.log(params.get('user'));
  // Prints 'abc'
console.log(params.toString());
  // Prints 'user=abc&query=xyz'

params = new URLSearchParams('?user=abc&query=xyz');
console.log(params.toString());
  // Prints 'user=abc&query=xyz'

Constructor: new URLSearchParams(obj)

新增于: v7.10.0

• obj <Object> An object representing a collection of key-value pairs

Instantiate a new URLSearchParams object with a query hash map. The key and value of each property of obj are always coerced to strings.

Note: Unlike querystring module, duplicate keys in the form of array values are not allowed. Arrays are stringified using array.toString(), which simply joins all array elements with commas.

const { URLSearchParams } = require('url');
const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second']
});
console.log(params.getAll('query'));
  // Prints [ 'first,second' ]
console.log(params.toString());
  // Prints 'user=abc&query=first%2Csecond'

Constructor: new URLSearchParams(iterable)

新增于: v7.10.0

• iterable <Iterable> An iterable object whose elements are key-value pairs

Instantiate a new URLSearchParams object with an iterable map in a way that is similar to Map's constructor. iterable can be an Array or any iterable object. That means iterable can be another URLSearchParams, in which case the constructor will simply create a clone of the provided URLSearchParams. Elements of iterable are key-value pairs, and can themselves be any iterable object.

Duplicate keys are allowed.

const { URLSearchParams } = require('url');
let params;

// Using an array
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second']
]);
console.log(params.toString());
  // Prints 'user=abc&query=first&query=second'

// Using a Map object
const map = new Map();
map.set('user', 'abc');
map.set('query', 'xyz');
params = new URLSearchParams(map);
console.log(params.toString());
  // Prints 'user=abc&query=xyz'

// Using a generator function
function* getQueryPairs() {
  yield ['user', 'abc'];
  yield ['query', 'first'];
  yield ['query', 'second'];
}
params = new URLSearchParams(getQueryPairs());
console.log(params.toString());
  // Prints 'user=abc&query=first&query=second'

// Each key-value pair must have exactly two elements
new URLSearchParams([
  ['user', 'abc', 'error']
]);
  // Throws TypeError [ERR_INVALID_TUPLE]:
  //        Each query pair must be an iterable [name, value] tuple

urlSearchParams.append(name, value)

• name <string>
• value <string>

Append a new name-value pair to the query string.

urlSearchParams.delete(name)

• name <string>

Remove all name-value pairs whose name is name.

urlSearchParams.entries()

• Returns: <Iterator>

Returns an ES6 Iterator over each of the name-value pairs in the query. Each item of the iterator is a JavaScript Array. The first item of the Array is the name, the second item of the Array is the value.

Alias for urlSearchParams[@@iterator]().

urlSearchParams.forEach(fn[, thisArg])

• fn <Function> Function invoked for each name-value pair in the query.
• thisArg <Object> Object to be used as this value for when fn is called

Iterates over each name-value pair in the query and invokes the given function.

const { URL } = require('url');
const myURL = new URL('https://example.org/?a=b&c=d');
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams);
});
  // Prints:
  // a b true
  // c d true

urlSearchParams.get(name)

• name <string>
• Returns: <string> or null if there is no name-value pair with the given name.

Returns the value of the first name-value pair whose name is name. If there are no such pairs, null is returned.

urlSearchParams.getAll(name)

• name <string>
• Returns: <Array>

Returns the values of all name-value pairs whose name is name. If there are no such pairs, an empty array is returned.

urlSearchParams.has(name)

• name <string>
• Returns: <boolean>

Returns true if there is at least one name-value pair whose name is name.

urlSearchParams.keys()

• Returns: <Iterator>

Returns an ES6 Iterator over the names of each name-value pair.

const { URLSearchParams } = require('url');
const params = new URLSearchParams('foo=bar&foo=baz');
for (const name of params.keys()) {
  console.log(name);
}
  // Prints:
  // foo
  // foo

urlSearchParams.set(name, value)

• name <string>
• value <string>

Sets the value in the URLSearchParams object associated with name to value. If there are any pre-existing name-value pairs whose names are name, set the first such pair's value to value and remove all others. If not, append the name-value pair to the query string.

const { URLSearchParams } = require('url');

const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
  // Prints foo=bar&foo=baz&abc=def

params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
  // Prints foo=def&abc=def&xyz=opq

urlSearchParams.sort()

新增于: v7.7.0
Sort all existing name-value pairs in-place by their names. Sorting is done with a stable sorting algorithm, so relative order between name-value pairs with the same name is preserved.

This method can be used, in particular, to increase cache hits.

const { URLSearchParams } = require('url');
const params = new URLSearchParams('query[]=abc&type=search&query[]=123');
params.sort();
console.log(params.toString());
  // Prints query%5B%5D=abc&query%5B%5D=123&type=search

urlSearchParams.toString()

• Returns: <string>

Returns the search parameters serialized as a string, with characters percent-encoded where necessary.

urlSearchParams.values()

• Returns: <Iterator>

Returns an ES6 Iterator over the values of each name-value pair.

urlSearchParams[@@iterator]()

• Returns: <Iterator>

Returns an ES6 Iterator over each of the name-value pairs in the query string. Each item of the iterator is a JavaScript Array. The first item of the Array is the name, the second item of the Array is the value.

Alias for urlSearchParams.entries().

const { URLSearchParams } = require('url');
const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
  // Prints:
  // foo bar
  // xyz baz

url.domainToASCII(domain)

新增于: v7.4.0

• domain <string>
• Returns: <string>

Returns the Punycode ASCII serialization of the domain. If domain is an invalid domain, the empty string is returned.

It performs the inverse operation to url.domainToUnicode().

const url = require('url');
console.log(url.domainToASCII('español.com'));
  // Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
  // Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
  // Prints an empty string

url.domainToUnicode(domain)

新增于: v7.4.0

• domain <string>
• Returns: <string>

Returns the Unicode serialization of the domain. If domain is an invalid domain, the empty string is returned.

It performs the inverse operation to url.domainToASCII().

const url = require('url');
console.log(url.domainToUnicode('xn--espaol-zwa.com'));
  // Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
  // Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
  // Prints an empty string

url.format(URL[, options])

新增于: v7.6.0

• URL <URL> A WHATWG URL object
• options <Object>
  • auth <boolean> true if the serialized URL string should include the username and password, false otherwise. Defaults to true.
  • fragment <boolean> true if the serialized URL string should include the fragment, false otherwise. Defaults to true.
  • search <boolean> true if the serialized URL string should include the search query, false otherwise. Defaults to true.
  • unicode <boolean> true if Unicode characters appearing in the host component of the URL string should be encoded directly as opposed to being Punycode encoded. Defaults to false.

Returns a customizable serialization of a URL String representation of a WHATWG URL object.

The URL object has both a toString() method and href property that return string serializations of the URL. These are not, however, customizable in any way. The url.format(URL[, options]) method allows for basic customization of the output.

For example:

const { URL } = require('url');
const myURL = new URL('https://a:b@你好你好?abc#foo');

console.log(myURL.href);
  // Prints https://a:b@xn--6qqa088eba/?abc#foo

console.log(myURL.toString());
  // Prints https://a:b@xn--6qqa088eba/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
  // Prints 'https://你好你好/?abc'

Legacy URL API

Legacy urlObject

The legacy urlObject (require('url').Url) is created and returned by the url.parse() function.

urlObject.auth

auth 属性是 URL 的用户名与密码部分。 该字符串跟在 protocol 和双斜杠（如果有）的后面，排在 host 部分的前面且被一个 ASCII 的 at 符号（@）分隔。 该字符的格式为 {username}[:{password}]，[:{password}] 部分是可选的。

例如：'user:pass'

urlObject.hash

hash 属性包含 URL 的碎片部分，包括开头的 ASCII 哈希字符（）。

例如：'#hash'

urlObject.host

host 属性是 URL 的完整的小写的主机部分，包括 port（如果有）。

例如：'sub.host.com:8080'

urlObject.hostname

hostname 属性是 host 组成部分排除 port 之后的小写的主机名部分。

例如：'sub.host.com'

urlObject.href

href 属性是解析后的完整的 URL 字符串，protocol 和 host 都会被转换为小写的。

例如：'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'

urlObject.path

path 属性是一个 pathname 与 search 组成部分的串接。

例如：'/p/a/t/h?query=string'

不会对 path 执行解码。

urlObject.pathname

pathname 属性包含 URL 的整个路径部分。 它跟在 host （包括 port）后面，排在 query 或 hash 组成部分的前面且被 ASCII 问号（?）或哈希字符（）分隔。

例如：'/p/a/t/h'

不会对路径字符串执行解码。

urlObject.port

port 属性是 host 组成部分中的数值型的端口部分。

例如：'8080'

urlObject.protocol

protocol 属性表明 URL 的小写的协议体制。

例如：'http:'

urlObject.query

query 属性是不含开头 ASCII 问号（?）的查询字符串，或一个被 querystring 模块的 parse() 方法返回的对象。 query 属性是一个字符串还是一个对象是由传入 url.parse() 的 parseQueryString 参数决定的。

例如：'query=string' or {'query': 'string'}

如果返回一个字符串，则不会对查询字符串执行解码。 如果返回一个对象，则键和值都会被解码。

urlObject.search

search 属性包含 URL 的整个查询字符串部分，包括开头的 ASCII 问号字符（?）。

例如：'?query=string'

不会对查询字符串执行解码。

urlObject.slashes

slashes 属性是一个 boolean，如果 protocol 中的冒号后面跟着两个 ASCII 斜杠字符（/），则值为 true。

url.format(urlObject)

新增于: v0.1.25

• urlObject <Object> | <string> 一个 URL 对象（就像 url.parse() 返回的）。 如果是一个字符串，则通过 url.parse() 转换为一个对象。

url.format() 方法返回一个从 urlObject 格式化后的 URL 字符串。

如果 urlObject 不是一个对象或字符串，则 url.parse() 抛出 TypeError。

格式化过程如下：

• 创建一个新的空字符串 result。
• 如果 urlObject.protocol 是一个字符串，则它会被原样添加到 result。
• 否则，如果 urlObject.protocol 不是 undefined 也不是一个字符串，则抛出 Error。
• 对于不是以 : 结束的 urlObject.protocol，: 会被添加到 result。
• 如果以下条件之一为真，则 // 会被添加到 result：
  • urlObject.slashes 属性为真；
  • urlObject.protocol 以 http、https、ftp、gopher 或 file 开头；
• 如果 urlObject.auth 属性的值为真，且 urlObject.host 或 urlObject.hostname 不为 undefined，则 urlObject.auth 会被添加到 result，且后面带上 @。
• 如果 urlObject.host 属性为 undefined，则：
  • 如果 urlObject.hostname 是一个字符串，则它会被添加到 result。
  • 否则，如果 urlObject.hostname 不是 undefined 也不是一个字符串，则抛出 Error。
  • 如果 urlObject.port 属性的值为真，且 urlObject.hostname 不为 undefined：
    • : 会被添加到 result。
    • urlObject.port 的值会被添加到 result。
• 否则，如果 urlObject.host 属性的值为真，则 urlObject.host 的值会被添加到 result。
• 如果 urlObject.pathname 属性是一个字符串且不是一个空字符串：
  • 如果 urlObject.pathname 不是以 / 开头，则 / 会被添加到 result。
  • urlObject.pathname 的值会被添加到 result。
• 否则，如果 urlObject.pathname 不是 undefined 也不是一个字符串，则抛出 Error。
• 如果 urlObject.search 属性为 undefined 且 urlObject.query 属性是一个 Object，则 ? 会被添加到 result，后面跟上把 urlObject.query 的值传入 querystring 模块的 stringify() 方法的调用结果。
• 否则，如果 urlObject.search 是一个字符串：
  • 如果 urlObject.search 的值不是以 ? 开头，则 ? 会被添加到 result。
  • urlObject.search 的值会被添加到 result。
• 否则，如果 urlObject.search 不是 undefined 也不是一个字符串，则抛出 Error。
• 如果 urlObject.hash 属性是一个字符串：
  • 如果 urlObject.hash 的值不是以 开头，则 会被添加到 result。
  • urlObject.hash 的值会被添加到 result。
• 否则，如果 urlObject.hash 属性不是 undefined 也不是一个字符串，则抛出 Error。
• 返回 result。

url.parse(urlString[, parseQueryString[, slashesDenoteHost]])

新增于: v0.1.25

• urlString <string> 要解析的 URL 字符串。
• parseQueryString <boolean> 如果为 true，则 query 属性总会通过 querystring 模块的 parse() 方法生成一个对象。 如果为 false，则返回的 URL 对象上的 query 属性会是一个未解析、未解码的字符串。 默认为 false。
• slashesDenoteHost <boolean> 如果为 true，则 // 之后至下一个 / 之前的字符串会被解析作为 host。 例如，//foo/bar 会被解析为 {host: 'foo', pathname: '/bar'} 而不是 {pathname: '//foo/bar'}。 默认为 false。

url.parse() 方法会解析一个 URL 字符串并返回一个 URL 对象。

A TypeError is thrown if urlString is not a string.

A URIError is thrown if the auth property is present but cannot be decoded.

url.resolve(from, to)

版本历史

• from <string> 解析时相对的基本 URL。
• to <string> 要解析的超链接 URL。

url.resolve() 方法会以一种 Web 浏览器解析超链接的方式把一个目标 URL 解析成相对于一个基础 URL。

例子：

const url = require('url');
url.resolve('/one/two/three', 'four');         // '/one/two/four'
url.resolve('http://example.com/', '/one');    // 'http://example.com/one'
url.resolve('http://example.com/one', '/two'); // 'http://example.com/two'

Percent-Encoding in URLs

URLs are permitted to only contain a certain range of characters. Any character falling outside of that range must be encoded. How such characters are encoded, and which characters to encode depends entirely on where the character is located within the structure of the URL.

Legacy API

Within the Legacy API, spaces (' ') and the following characters will be automatically escaped in the properties of URL objects:

< > " ` \r \n \t { } | \ ^ '

For example, the ASCII space character (' ') is encoded as %20. The ASCII forward slash (/) character is encoded as %3C.

WHATWG API

The WHATWG URL Standard uses a more selective and fine grained approach to selecting encoded characters than that used by the Legacy API.

The WHATWG algorithm defines three "percent-encode sets" that describe ranges of characters that must be percent-encoded:

• The C0 control percent-encode set includes code points in range U+0000 to U+001F (inclusive) and all code points greater than U+007E.
• The path percent-encode set includes the C0 control percent-encode set and code points U+0020, U+0022, U+0023, U+003C, U+003E, U+003F, U+0060, U+007B, and U+007D.
• The userinfo encode set includes the path percent-encode set and code points U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, U+005E, and U+007C.

The userinfo percent-encode set is used exclusively for username and passwords encoded within the URL. The path percent-encode set is used for the path of most URLs. The C0 control percent-encode set is used for all other cases, including URL fragments in particular, but also host and path under certain specific conditions.

When non-ASCII characters appear within a hostname, the hostname is encoded using the Punycode algorithm. Note, however, that a hostname may contain both Punycode encoded and percent-encoded characters. For example:

const { URL } = require('url');
const myURL = new URL('https://%CF%80.com/foo');
console.log(myURL.href);
  // Prints https://xn--1xa.com/foo
console.log(myURL.origin);
  // Prints https://π.com