Node.js v12.9.0 文档


url(URL)#

中英对照提交修改

稳定性: 2 - 稳定

url 模块用于处理与解析 URL。 使用方法如下:

const url = require('url');

URL 字符串与 URL 对象#

中英对照提交修改

URL 字符串是结构化的字符串,包含多个含义不同的组成部分。 解析字符串后返回的 URL 对象,每个属性对应字符串的各个组成部分。

url 模块提供了两套 API 来处理 URL:一个是旧版本遗留的 API,一个是实现了 WHATWG标准的新 API。

遗留的 API 还没有被废弃,保留是为了兼容已存在的应用程序。 新的应用程序应使用 WHATWG 的 API。

WHATWG 的 API 与遗留的 API 的区别如下。 在下图中,URL 'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash' 上方的是遗留的 url.parse() 返回的对象的属性。 下方的则是 WHATWG 的 URL 对象的属性。

WHATWG 的 origin 属性包括 protocolhost,但不包括 usernamepassword

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              href                                              │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │          host          │           path            │ hash  │
│          │  │                     ├─────────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │    hostname     │ port │ pathname │     search     │       │
│          │  │                     │                 │      │          ├─┬──────────────┤       │
│          │  │                     │                 │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.example.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │    hostname     │ port │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘

使用 WHATWG 的 API 解析 URL 字符串:

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

使用遗留的 API 解析 URL 字符串:

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

WHATWG 的 URL 接口#

URL 类#

中英对照提交修改

浏览器兼容的 URL 类,根据 WHATWG URL 标准实现。解析URL的示例可以在标准本身里边找到。

注意: 根据浏览器的约定, URL 对象的所有属性都是在类的原型上实现为getter和setter,而不是作为对象本身的数据属性。因此,与遗留的urlObjects不同,在 URL 对象的任何属性(例如 delete myURL.protocoldelete myURL.pathname等)上使用 delete 关键字没有任何效果,但仍返回 true

new URL(input[, base])#

中英对照提交修改

  • input <string> 要解析的输入URL
  • base <string> | <URL> 如果“input”是相对URL,则为要解析的基本URL。

通过将input解析到base上创建一个新的URL对象。如果base是一个字符串,则解析方法与new URL(base)相同。

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

如果inputbase是无效URLs,将会抛出TypeError。请注意给定值将被强制转换为字符串。例如:

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

存在于input主机名中的Unicode字符将被使用Punycode算法自动转换为ASCII。

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

Note: This feature is only available if the node executable was compiled with ICU enabled. If not, the domain names are passed through unchanged.

url.hash#

查看v10.x中文文档

Gets and sets the fragment portion of the 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. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.host#

中英对照提交修改

获取及设置URL的主机(host)部分。

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

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

如果给host属性设置的值是无效值,那么该值将被忽略。

url.hostname#

中英对照提交修改

获取及设置URL的主机名(hostname)部分。 url.hosturl.hostname之间的区别是url.hostname 包含端口。

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

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

如果给hostname属性设置的值是无效值,那么该值将被忽略。

url.href#

中英对照提交修改

获取及设置序列化的URL。

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

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

获取href属性的值等同于调用url.toString()

将此属性的值设置为新值等同于new URL(value)使用创建新的URL对象。URL对象的每个属性都将被修改。

如果给href属性设置的值是无效URL,将会抛出TypeError

url.origin#

中英对照提交修改

获取只读序列化的URL origin部分。

const { URL } = require('url');
const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
  // 输出 https://example.org
const { URL } = require('url');
const idnURL = new URL('https://你好你好');
console.log(idnURL.origin);
  // 输出 https://xn--6qqa088eba

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

url.password#

查看v10.x中文文档

Gets and sets the password portion of the 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. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.pathname#

查看v10.x中文文档

Gets and sets the path portion of the 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. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.port#

查看v10.x中文文档

Gets and sets the port portion of the URL.

The port value may be a number or 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 ('').

The port value can be an empty string in which case the port depends on the protocol/scheme:

protocolport
"ftp"21
"file"
"gopher"70
"http"80
"https"443
"ws"80
"wss"443

Upon assigning a value to the port, the value will first be converted to a string using .toString().

If that string is invalid but it begins with a number, the leading number is assigned to port. If the number lies outside the range denoted above, it is ignored.

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 which are not represented in scientific notation
// will be ignored.
myURL.port = 1e10; // 10000000000, will be range-checked as described below
console.log(myURL.port);
// Prints 1234

Numbers which contain a decimal point, such as floating-point numbers or numbers in scientific notation, are not an exception to this rule. Leading numbers up to the decimal point will be set as the URL's port, assuming they are valid:

myURL.port = 4.567e21;
console.log(myURL.port);
// Prints 4 (because it is the leading number in the string '4.567e21')

url.protocol#

中英对照提交修改

获取及设置URL的协议(protocol)部分。

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

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

如果给protocol属性设置的值是无效值,那么该值将被忽略。

特殊协议#

暂无中英对照提交修改

The WHATWG URL Standard considers a handful of URL protocol schemes to be special in terms of how they are parsed and serialized. When a URL is parsed using one of these special protocols, the url.protocol property may be changed to another special protocol but cannot be changed to a non-special protocol, and vice versa.

For instance, changing from http to https works:

const u = new URL('http://example.org');
u.protocol = 'https';
console.log(u.href);
// https://example.org

However, changing from http to a hypothetical fish protocol does not because the new protocol is not special.

const u = new URL('http://example.org');
u.protocol = 'fish';
console.log(u.href);
// http://example.org

Likewise, changing from a non-special protocol to a special protocol is also not permitted:

const u = new URL('fish://example.org');
u.protocol = 'http';
console.log(u.href);
// fish://example.org

According to the WHATWG URL Standard, special protocol schemes are ftp, file, gopher, http, https, ws, and wss.

url.search#

查看v10.x中文文档

Gets and sets the serialized query portion of the 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. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.searchParams#

中英对照提交修改

获取表示URL查询参数的URLSearchParams对象。该属性是只读的;使用url.search设置来替换URL的整个查询参数。请打开URLSearchParams文档来查看更多细节。

url.username#

查看v10.x中文文档

Gets and sets the username portion of the 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. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.toString()#

中英对照提交修改

URL对象上调用toString()方法将返回序列化的URL。返回值与url.hrefurl.toJSON()的相同。

由于需要符合标准,此方法不允许用户自定义URL的序列化过程。 如果需要更大灵活性,require('url').format()可能更合适。

url.toJSON()#

中英对照提交修改

URL对象上调用toJSON()方法将返回序列化的URL。返回值与url.hrefurl.toString()的相同。

URL对象使用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));
  // 输出 ["https://www.example.com/","https://test.example.org/"]

URLSearchParams 类#

中英对照提交修改

URLSearchParamsAPI接口提供对URLquery部分的读写权限。URLSearchParams类也能够与以下四个构造函数中的任意一个单独使用。

WHATWG URLSearchParams接口和querystring模块有相似的目的,但是querystring模块的目的更加通用,因为它可以定制分隔符(=)。但另一方面,这个API是专门为URL查询字符串而设计的。

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

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

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

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

const newSearchParams = new URLSearchParams(myURL.searchParams);
// 上面的代码等同于
// const newSearchParams = new URLSearchParams(myURL.search);

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

// newSearchParams.toString() 被隐式调用
myURL.search = newSearchParams;
console.log(myURL.href);
// 输出 https://example.org/?a=b&a=c
newSearchParams.delete('a');
console.log(myURL.href);
// 输出 https://example.org/?a=b&a=c

new URLSearchParams()#

中英对照提交修改

实例化一个新的空的URLSearchParams对象。

new URLSearchParams(string)#

中英对照提交修改

string解析成一个查询字符串, 并且使用它来实例化一个新的URLSearchParams对象.  如果string'?'打头,则'?'将会被忽略.

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

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

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

new URLSearchParams(obj)#

中英对照提交修改

  • obj <Object> 一个表示键值对集合的对象

通过使用查询哈希映射实例化一个新的URLSearchParams对象, obj的每一个属性的键和值将被强制转换为字符串。

请注意: 和 querystring 模块不同的是, 在数组的形式中,重复的键是不允许的。数组使用array.toString()进行字符串化时,只需用逗号连接所有的数组元素即可。

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

new URLSearchParams(iterable)#

中英对照提交修改

  • iterable <Iterable> 一个元素时键值对的迭代对象

以一种类似于Map的构造函数的迭代映射方式实例化一个新的URLSearchParams对象。iterable可以是一个数组或者任何迭代对象。这就意味着iterable能够使另一个URLSearchParams,这种情况下,构造函数将简单地根据提供的URLSearchParams创建一个克隆URLSearchParamsiterable的元素是键值对,并且其本身也可以是任何迭代对象。

允许重复的键。

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

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

// 使用Map对象
const map = new Map();
map.set('user', 'abc');
map.set('query', 'xyz');
params = new URLSearchParams(map);
console.log(params.toString());
  // 输出 'user=abc&query=xyz'

// 使用generator函数
function* getQueryPairs() {
  yield ['user', 'abc'];
  yield ['query', 'first'];
  yield ['query', 'second'];
}
params = new URLSearchParams(getQueryPairs());
console.log(params.toString());
  // 输出 'user=abc&query=first&query=second'

// 每个键值对必须有两个元素
new URLSearchParams([
  ['user', 'abc', 'error']
]);
  // 抛出 TypeError [ERR_INVALID_TUPLE]:
  //        每一个键值对必须是迭代的[键,值]元组

urlSearchParams.append(name, value)#

中英对照提交修改

在查询字符串中附加一个新的键值对。

urlSearchParams.delete(name)#

中英对照提交修改

删除所有键为name的键值对。

urlSearchParams.entries()#

中英对照提交修改

  • 返回: <Iterator> 在查询中的每个键值对上返回一个ES6迭代器。 迭代器的每一项都是一个JavaScript数组。 Array的第一个项是键name,Array的第二个项是值value

别名为urlSearchParams[@@iterator]().

urlSearchParams.forEach(fn[, thisArg])#

中英对照提交修改

  • fn <Function> 在查询字符串中的每个键值对的调用函数。
  • thisArg <Object>fn调用时,被用作this值的对象

在查询字符串中迭代每个键值对,并调用给定的函数。

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);
});
  // 输出:
  // a b true
  // c d true

urlSearchParams.get(name)#

中英对照提交修改

  • name <string>
  • 返回: <string> ,如果没有键值对对应给定的name则返回null

返回键是name的第一个键值对的值。如果没有对应的键值对,则返回null

urlSearchParams.getAll(name)#

中英对照提交修改

返回键是name的所有键值对的值,如果没有满足条件的键值对,则返回一个空的数组。

urlSearchParams.has(name)#

中英对照提交修改

如果存在至少一对键是name的键值对则返回 true

urlSearchParams.keys()#

中英对照提交修改

在每一个键值对上返回一个键的ES6迭代器。

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

urlSearchParams.set(name, value)#

中英对照提交修改

URLSearchParams对象中与name相对应的值设置为value。如果已经存在键为name的键值对,将第一对的值设为value并且删除其他对。如果不存在,则将此键值对附加在查询字符串后。

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

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

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

urlSearchParams.sort()#

中英对照提交修改

按现有名称就地排列所有的名称-值对。使用[稳定排序算法][]完成排序,因此保留具有相同名称的名称-值对之间的相对顺序。

特别地,该方法可以用来增加缓存命中。

const params = new URLSearchParams('query[]=abc&type=search&query[]=123');
params.sort();
console.log(params.toString());
  // 打印 query%5B%5D=abc&query%5B%5D=123&type=search

urlSearchParams.toString()#

中英对照提交修改

返回查询参数序列化后的字符串,必要时存在百分号编码字符。

urlSearchParams.values()#

中英对照提交修改

在每一个键值对上返回一个值的ES6迭代器。

urlSearchParams[Symbol.iterator]()#

中英对照提交修改

根据查询字符串,返回一个键值对形式的 ES6 Iterator。每个迭代器的项是一个 JavaScript Array。 其中, Array 的第一项是 name,第二个是 value

urlSearchParams.entries() 的别名。

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)#

中英对照提交修改

返回Punycode ASCII序列化的domain. 如果domain是无效域名,将返回空字符串。

它执行的是url.domainToUnicode()的逆运算。

const url = require('url');
console.log(url.domainToASCII('español.com'));
  // 输出 xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
  // 输出 xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
  // 输出空字符串

url.domainToUnicode(domain)#

中英对照提交修改

返回Unicode序列化的domain. 如果domain是无效域名,将返回空字符串。

它执行的是url.domainToASCII()的逆运算。

const url = require('url');
console.log(url.domainToUnicode('xn--espaol-zwa.com'));
  // 输出 español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
  // 输出 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
  // 输出空字符串

url.fileURLToPath(url)#

中英对照提交修改

  • url <URL> | <string> 被转换为路径的文件的 URL 字符串或者 URL 对象。
  • 返回: <string> 被完全解析的平台特定的 Node.js 文件路径。

此方法保证百分号编码字符解码结果的正确性,同时也确保绝对路径字符串在不同平台下的有效性。

new URL('file:///C:/path/').pathname;    // 错误: /C:/path/
fileURLToPath('file:///C:/path/');       // 正确: C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;  // 错误: /foo.txt
fileURLToPath('file://nas/foo.txt');     // 正确: \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;    // 错误: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');       // 正确: /你好.txt (POSIX)

new URL('file:///hello world').pathname; // 错误: /hello%20world
fileURLToPath('file:///hello world');    // 正确: /hello world (POSIX)

url.format(URL[, options])#

中英对照提交修改

  • URL <URL> 一个WHATWG URL对象
  • options <Object>

    • auth <boolean> 如果序列化的URL字符串应该包含用户名和密码为true,否则为false。默认为true
    • fragment <boolean> 如果序列化的URL字符串应该包含分段为true,否则为false。默认为true
    • search <boolean> 如果序列化的URL字符串应该包含搜索查询为true,否则为false。默认为true
    • unicode <boolean> true 如果出现在URL字符串主机元素里的Unicode字符应该被直接编码而不是使用Punycode编码为true,默认为false

返回一个WHATWG URL对象的可自定义序列化的URL字符串表达。

虽然URL对象的toString()方法和href属性都可以返回URL的序列化的字符串。然而,两者都不可以被自定义。而url.format(URL[, options])方法允许输出的基本自定义。

例如:

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

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

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

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

url.pathToFileURL(path)#

暂无中英对照提交修改

  • path <string> The path to convert to a File URL.
  • Returns: <URL> The file URL object.

This function ensures that path is resolved absolutely, and that the URL control characters are correctly encoded when converting into a File URL.

new URL(__filename);                // Incorrect: throws (POSIX)
new URL(__filename);                // Incorrect: C:\... (Windows)
pathToFileURL(__filename);          // Correct:   file:///... (POSIX)
pathToFileURL(__filename);          // Correct:   file:///C:/... (Windows)

new URL('/foo#1', 'file:');         // Incorrect: file:///foo#1
pathToFileURL('/foo#1');            // Correct:   file:///foo%231 (POSIX)

new URL('/some/path%.js', 'file:'); // Incorrect: file:///some/path%
pathToFileURL('/some/path%.js');    // Correct:   file:///some/path%25 (POSIX)

遗留的 URL 接口#

暂无中英对照提交修改

稳定性: 0 - 废弃: 改为使用 the WHATWG URL API 。

遗留的 urlObject#

查看v10.x中文文档

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 字符串, protocolhost 都会被转换为小写的。

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

urlObject.path#

中英对照提交修改

path 属性是一个 pathnamesearch 组成部分的串接。

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

不会对 path 执行解码。

urlObject.pathname#

中英对照提交修改

pathname 属性包含 URL 的整个路径部分。 它跟在 host (包括 port)后面,排在 queryhash 组成部分的前面且被 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)#

查看v10.x中文文档

  • urlObject <Object> | <string> A URL object (as returned by url.parse() or constructed otherwise). If a string, it is converted to an object by passing it to url.parse().

The url.format() method returns a formatted URL string derived from urlObject.

url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json'
  }
});

// => 'https://example.com/some/path?page=1&format=json'

If urlObject is not an object or a string, url.format() will throw a TypeError.

The formatting process operates as follows:

  • A new empty string result is created.
  • If urlObject.protocol is a string, it is appended as-is to result.
  • Otherwise, if urlObject.protocol is not undefined and is not a string, an Error is thrown.
  • For all string values of urlObject.protocol that do not end with an ASCII colon (:) character, the literal string : will be appended to result.
  • If either of the following conditions is true, then the literal string // will be appended to result:

    • urlObject.slashes property is true;
    • urlObject.protocol begins with http, https, ftp, gopher, or file;
  • If the value of the urlObject.auth property is truthy, and either urlObject.host or urlObject.hostname are not undefined, the value of urlObject.auth will be coerced into a string and appended to result followed by the literal string @.
  • If the urlObject.host property is undefined then:

    • If the urlObject.hostname is a string, it is appended to result.
    • Otherwise, if urlObject.hostname is not undefined and is not a string, an Error is thrown.
    • If the urlObject.port property value is truthy, and urlObject.hostname is not undefined:

      • The literal string : is appended to result, and
      • The value of urlObject.port is coerced to a string and appended to result.
  • Otherwise, if the urlObject.host property value is truthy, the value of urlObject.host is coerced to a string and appended to result.
  • If the urlObject.pathname property is a string that is not an empty string:

    • If the urlObject.pathname does not start with an ASCII forward slash (/), then the literal string '/' is appended to result.
    • The value of urlObject.pathname is appended to result.
  • Otherwise, if urlObject.pathname is not undefined and is not a string, an Error is thrown.
  • If the urlObject.search property is undefined and if the urlObject.query property is an Object, the literal string ? is appended to result followed by the output of calling the querystring module's stringify() method passing the value of urlObject.query.
  • Otherwise, if urlObject.search is a string:

    • If the value of urlObject.search does not start with the ASCII question mark (?) character, the literal string ? is appended to result.
    • The value of urlObject.search is appended to result.
  • Otherwise, if urlObject.search is not undefined and is not a string, an Error is thrown.
  • If the urlObject.hash property is a string:

    • If the value of urlObject.hash does not start with the ASCII hash (#) character, the literal string # is appended to result.
    • The value of urlObject.hash is appended to result.
  • Otherwise, if the urlObject.hash property is not undefined and is not a string, an Error is thrown.
  • result is returned.

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

查看v10.x中文文档

  • urlString <string> The URL string to parse.
  • parseQueryString <boolean> If true, the query property will always be set to an object returned by the querystring module's parse() method. If false, the query property on the returned URL object will be an unparsed, undecoded string. Default: false.
  • slashesDenoteHost <boolean> If true, the first token after the literal string // and preceding the next / will be interpreted as the host. For instance, given //foo/bar, the result would be {host: 'foo', pathname: '/bar'} rather than {pathname: '//foo/bar'}. Default: false.

The url.parse() method takes a URL string, parses it, and returns a URL object.

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)#

查看v10.x中文文档

  • from <string> The Base URL being resolved against.
  • to <string> The HREF URL being resolved.

The url.resolve() method resolves a target URL relative to a base URL in a manner similar to that of a Web browser resolving an anchor tag HREF.

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'

URL 中的百分号编码#

中英对照提交修改

允许URL只包含一定范围的字符。 任何超出该范围的字符都必须进行编码。 如何对这些字符进行编码,以及哪些字符要编码完全取决于字符在URL结构内的位置。

遗留的接口#

中英对照提交修改

在遗留的API中,空格(' ')及以下字符将自动转义为URL对象的属性:

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

例如,ASCII 空格字符(' ')被编码成 %20。 ASCII 斜杠字符(/)被编码成 %3C

WHATWG 接口#

中英对照提交修改

WHATWG URL Standard使用比遗留的API更具选择性和更精细的方法来选择使用的编码字符。

WHATWG算法定义了三个“百分比编码集”,它们描述了必须进行百分编码的字符范围:

  • C0 control percent-encode set(C0控制百分比编码集) 包括范围在U+0000 ~ U+001F(含)的代码点及大于U+007E的所有代码点。

  • path percent-encode set(路径百分比编码集) 包括 C0 control percent-encode set(C0控制百分比编码集) 的代码点 及 U+0020, U+0022, U+0023, U+003C, U+003E, U+003F, U+0060, U+007B, 和 U+007D 的代码点。

  • userinfo encode set(用户信息编码集) 包括 path percent-encode set(路径百分比编码集) 的代码点 及 U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, U+005E, 和 U+007C 的代码点。

userinfo percent-encode set(用户信息百分比编码集) 专门用于用户名和密码部分的编码。path percent-encode set(路径百分比编码集) 用于大多数URL的路径部分编码。C0 control percent-encode set(C0控制百分比编码集) 则用于所有其他情况的编码,特别地包括URL的分段部分,特殊条件下也包括主机及路径部分。

当主机名中出现非ASCII字符时,主机名将使用Punycode算法进行编码。然而,请注意,主机名可能同时 包含Punycode编码和百分比编码的字符。例如:

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