Node.js v21.7.2 文档

URL 字符串和 URL 对象#

URL 字符串是一个结构化的字符串，包含多个有意义的组件。解析后，将返回一个 URL 对象，其中包含每个组件的属性。

node:url 模块提供了两种用于处理 URL 的 API：一种是 Node.js 特定的传统 API，另一种是实现与 Web 浏览器使用的相同 WHATWG URL 标准 的较新 API。

以下是 WHATWG 和传统 API 之间的比较。在 URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash' 上方，显示了传统 url.parse() 返回的对象的属性。在它下面是 WHATWG URL 对象的属性。

WHATWG URL 的 `origin` 属性包含 `protocol` 和 `host`，但不包含 `username` 或 `password`。

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              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                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(All spaces in the "" line should be ignored. They are purely for formatting.) copy

使用 WHATWG API 解析 URL 字符串

const myURL =
  new URL('https://user:[email protected]:8080/p/a/t/h?query=string#hash'); copy

使用传统 API 解析 URL 字符串

import url from 'node:url';
const myURL =
  url.parse('https://user:[email protected]:8080/p/a/t/h?query=string#hash');const url = require('node:url');
const myURL =
  url.parse('https://user:[email protected]:8080/p/a/t/h?query=string#hash');copy

从组件部分构建 URL 并获取构建的字符串#

可以使用属性设置器或模板字面量字符串从组件部分构建 WHATWG URL

const myURL = new URL('https://example.org');
myURL.pathname = '/a/b/c';
myURL.search = '?d=e';
myURL.hash = '#fgh'; copy

const pathname = '/a/b/c';
const search = '?d=e';
const hash = '#fgh';
const myURL = new URL(`https://example.org${pathname}${search}${hash}`); copy

要获取构建的 URL 字符串，请使用 `href` 属性访问器

console.log(myURL.href); copy

WHATWG URL API#

类：`URL`#

与浏览器兼容的 `URL` 类，通过遵循 WHATWG URL 标准实现。 解析 URL 的示例 可以在标准本身中找到。`URL` 类也存在于全局对象上。

根据浏览器约定，`URL` 对象的所有属性都作为类原型上的 getter 和 setter 实现，而不是作为对象本身上的数据属性。因此，与 传统 `urlObject` 不同，对 `URL` 对象的任何属性使用 `delete` 关键字（例如 `delete myURL.protocol`、`delete myURL.pathname` 等）不会产生任何效果，但仍将返回 `true`。

new URL(input[, base])#

• input <string> 要解析的绝对或相对输入 URL。如果 `input` 是相对的，则需要 `base`。如果 `input` 是绝对的，则忽略 `base`。如果 `input` 不是字符串，则首先将其 转换为字符串。
• base <string> 如果 `input` 不是绝对的，则要解析的基 URL。如果 `base` 不是字符串，则首先将其 转换为字符串。

通过解析相对于base的input来创建一个新的URL对象。如果base作为字符串传递，它将被解析为等效于new URL(base)。

const myURL = new URL('/foo', 'https://example.org/');
// https://example.org/foo copy

URL构造函数作为全局对象上的属性可访问。它也可以从内置的url模块导入。

import { URL } from 'node:url';
console.log(URL === globalThis.URL); // Prints 'true'.console.log(URL === require('node:url').URL); // Prints 'true'.copy

如果input或base不是有效的URL，则会抛出TypeError。请注意，将尽力将给定值强制转换为字符串。例如

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

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

const myURL = new URL('https://測試');
// https://xn--g6w251d/ copy

在事先不知道input是否为绝对URL并提供base的情况下，建议验证URL对象的origin是否符合预期。

let myURL = new URL('http://Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https://Example.com/', 'https://example.org/');
// https://example.com/

myURL = new URL('foo://Example.com/', 'https://example.org/');
// foo://Example.com/

myURL = new URL('http:Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https:Example.com/', 'https://example.org/');
// https://example.org/Example.com/

myURL = new URL('foo:Example.com/', 'https://example.org/');
// foo:Example.com/ copy

url.hash#

• <string>

获取和设置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 copy

分配给hash属性的值中包含的无效URL字符将被百分比编码。对哪些字符进行百分比编码的选择可能与url.parse()和url.format()方法产生的结果略有不同。

url.host#

• <string>

获取和设置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 copy

分配给host属性的无效主机值将被忽略。

url.hostname#

• <string>

获取和设置URL的主机名部分。url.host和url.hostname之间的主要区别在于url.hostname不包含端口。

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

// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo

// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo copy

分配给hostname属性的无效主机名值将被忽略。

url.href#

• <string>

获取和设置序列化后的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 copy

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

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

如果分配给href属性的值不是有效的URL，则会抛出TypeError。

url.origin#

• <string>

获取URL来源的只读序列化。

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

const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Prints https://xn--g6w251d

console.log(idnURL.hostname);
// Prints xn--g6w251d copy

url.password#

• <string>

获取和设置URL的密码部分。

const myURL = new URL('https://abc:[email protected]');
console.log(myURL.password);
// Prints xyz

myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:[email protected]/ copy

分配给password属性的值中包含的无效URL字符将被百分比编码。对哪些字符进行百分比编码的选择可能与url.parse()和url.format()方法产生的结果略有不同。

url.pathname#

• <string>

获取和设置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 copy

分配给pathname属性的值中包含的无效URL字符将被百分比编码。对哪些字符进行百分比编码的选择可能与url.parse()和url.format()方法产生的结果略有不同。

url.port#

• <string>

获取和设置URL的端口部分。

端口值可以是数字，也可以是包含数字的字符串，范围在0到65535（含）之间。将值设置为给定protocol的URL对象的默认端口将导致port值变为空字符串（''）。

端口值可以为空字符串，在这种情况下，端口取决于协议/方案。

在为端口分配值时，该值将首先使用.toString()转换为字符串。

如果该字符串无效，但以数字开头，则将前导数字分配给port。如果该数字超出上面表示的范围，则将其忽略。

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 copy

包含小数点的数字，例如浮点数或科学计数法中的数字，不属于此规则的例外。假设前导数字在有效范围内，则将它们设置为 URL 的端口，直到小数点。

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

url.protocol#

• <string>

获取和设置 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/ copy

分配给protocol属性的无效 URL 协议值将被忽略。

特殊方案#

WHATWG URL 标准认为少数 URL 协议方案在解析和序列化方面是特殊的。当使用这些特殊协议之一解析 URL 时，url.protocol属性可能会更改为另一个特殊协议，但不能更改为非特殊协议，反之亦然。

例如，从http更改为https是可行的。

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

但是，从http更改为假设的fish协议不可行，因为新协议不是特殊的。

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

同样，从非特殊协议更改为特殊协议也不允许。

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

根据 WHATWG URL 标准，特殊协议方案是ftp、file、http、https、ws和wss。

url.search#

• <string>

获取和设置 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 copy

分配给search属性的值中出现的任何无效 URL 字符将被百分比编码。百分比编码哪些字符的选择可能与url.parse()和url.format()方法产生的结果略有不同。

url.searchParams#

• <URLSearchParams>

获取表示 URL 查询参数的URLSearchParams对象。此属性是只读的，但它提供的URLSearchParams对象可用于修改 URL 实例；要替换 URL 的所有查询参数，请使用url.search设置器。有关详细信息，请参阅URLSearchParams文档。

使用.searchParams修改URL时要小心，因为根据 WHATWG 规范，URLSearchParams对象使用不同的规则来确定要百分比编码哪些字符。例如，URL对象不会百分比编码 ASCII 波浪号 (~) 字符，而URLSearchParams始终会编码它。

const myURL = new URL('https://example.org/abc?foo=~bar');

console.log(myURL.search);  // prints ?foo=~bar

// Modify the URL via searchParams...
myURL.searchParams.sort();

console.log(myURL.search);  // prints ?foo=%7Ebar copy

url.username#

• <string>

获取和设置 URL 的用户名部分。

const myURL = new URL('https://abc:[email protected]');
console.log(myURL.username);
// Prints abc

myURL.username = '123';
console.log(myURL.href);
// Prints https://123:[email protected]/ copy

分配给 username 属性的任何无效 URL 字符将被 百分比编码。百分比编码的字符选择可能与 url.parse() 和 url.format() 方法生成的字符略有不同。

url.toString()#

• 返回值: <string>

URL 对象上的 toString() 方法返回序列化后的 URL。返回的值等效于 url.href 和 url.toJSON() 的值。

url.toJSON()#

• 返回值: <string>

URL 对象上的 toJSON() 方法返回序列化后的 URL。返回的值等效于 url.href 和 url.toString() 的值。

当使用 JSON.stringify() 序列化 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/"] copy

URL.createObjectURL(blob)#

• blob <Blob>
• 返回值: <string>

创建一个 'blob:nodedata:...' URL 字符串，它表示给定的 <Blob> 对象，并且可以用来稍后检索 Blob。

const {
  Blob,
  resolveObjectURL,
} = require('node:buffer');

const blob = new Blob(['hello']);
const id = URL.createObjectURL(blob);

// later...

const otherBlob = resolveObjectURL(id);
console.log(otherBlob.size); copy

注册的 <Blob> 所存储的数据将保留在内存中，直到调用 URL.revokeObjectURL() 来删除它。

Blob 对象在当前线程内注册。如果使用 Worker 线程，则在一个 Worker 内注册的 Blob 对象将不可用于其他 Worker 或主线程。

URL.revokeObjectURL(id)#

• id <string> 由先前对 URL.createObjectURL() 的调用返回的 'blob:nodedata:... URL 字符串。

删除由给定 ID 标识的存储的 <Blob>。尝试撤销未注册的 ID 将静默失败。

URL.canParse(input[, base])#

• input <string> 要解析的绝对或相对输入 URL。如果 `input` 是相对的，则需要 `base`。如果 `input` 是绝对的，则忽略 `base`。如果 `input` 不是字符串，则首先将其 转换为字符串。
• base <string> 如果 `input` 不是绝对的，则要解析的基 URL。如果 `base` 不是字符串，则首先将其 转换为字符串。
• 返回值: <boolean>

检查相对于 base 的 input 是否可以解析为 URL。

const isValid = URL.canParse('/foo', 'https://example.org/'); // true

const isNotValid = URL.canParse('/foo'); // false copy

类: URLSearchParams#

URLSearchParams API 提供对 URL 查询的读写访问。URLSearchParams 类也可以独立使用以下四种构造函数之一。URLSearchParams 类也存在于全局对象上。

WHATWG URLSearchParams 接口和 querystring 模块具有相似的目的，但 querystring 模块的目的更通用，因为它允许自定义分隔符字符 (& 和 =)。另一方面，此 API 纯粹用于 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 copy

new URLSearchParams()#

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

new URLSearchParams(string)#

• string <string> 查询字符串

将 string 解析为查询字符串，并使用它实例化一个新的 URLSearchParams 对象。如果存在，则忽略开头的 '?'。

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' copy

new URLSearchParams(obj)#

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

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

与 querystring 模块不同，不允许以数组值形式出现重复键。数组使用 array.toString() 进行字符串化，它只是用逗号连接所有数组元素。

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' copy

new URLSearchParams(iterable)#

• iterable <Iterable> 其元素为键值对的可迭代对象

使用类似于 Map 构造函数的方式，使用可迭代映射实例化一个新的 URLSearchParams 对象。iterable 可以是 Array 或任何可迭代对象。这意味着 iterable 可以是另一个 URLSearchParams，在这种情况下，构造函数将简单地创建一个提供的 URLSearchParams 的克隆。iterable 的元素是键值对，它们本身可以是任何可迭代对象。

允许重复键。

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 copy

urlSearchParams.append(name, value)#

• name <string>
• value <string>

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

urlSearchParams.delete(name[, value])#

• name <string>
• value <string>

如果提供了 value，则删除所有键为 name 且值为 value 的键值对。

如果未提供 value，则删除所有键为 name 的键值对。

urlSearchParams.entries()#

• 返回值: <Iterator>

返回一个 ES6 Iterator，用于遍历查询中的每个键值对。迭代器的每个项目都是一个 JavaScript Array。Array 的第一个项目是 name，第二个项目是 value。

是 urlSearchParams[@@iterator]() 的别名。

urlSearchParams.forEach(fn[, thisArg])#

• fn <Function> 对查询中的每个键值对调用。
• thisArg <Object> 用作调用 fn 时的 this 值。

遍历查询中的每个键值对并调用给定的函数。

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 copy

urlSearchParams.get(name)#

• name <string>
• 返回值: <string> | <null> 如果没有键为 name 的键值对，则返回字符串或 null。

返回第一个键为 name 的键值对的值。如果没有这样的对，则返回 null。

urlSearchParams.getAll(name)#

• name <string>
• 返回值: <string[]>

返回所有名称为 name 的名称-值对的值。如果不存在这样的对，则返回一个空数组。

urlSearchParams.has(name[, value])#

• name <string>
• value <string>
• 返回值: <boolean>

检查 URLSearchParams 对象是否包含基于 name 和可选 value 参数的键值对。

如果提供了 value，则当存在具有相同 name 和 value 的名称-值对时返回 true。

如果未提供 value，则如果至少存在一个名称为 name 的名称-值对，则返回 true。

urlSearchParams.keys()#

• 返回值: <Iterator>

返回每个名称-值对的名称的 ES6 Iterator。

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

urlSearchParams.set(name, value)#

• name <string>
• value <string>

将 URLSearchParams 对象中与 name 关联的值设置为 value。如果存在任何名称为 name 的预先存在的名称-值对，则将第一个这样的对的值设置为 value 并删除所有其他对。否则，将名称-值对追加到查询字符串。

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 copy

urlSearchParams.size#

参数条目的总数。

urlSearchParams.sort()#

按名称对所有现有的名称-值对进行就地排序。排序使用 稳定排序算法，因此具有相同名称的名称-值对之间的相对顺序将保留。

此方法可用于提高缓存命中率。

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 copy

urlSearchParams.toString()#

• 返回值: <string>

返回序列化为字符串的搜索参数，其中必要时对字符进行百分比编码。

urlSearchParams.values()#

• 返回值: <Iterator>

返回每个名称-值对的值的 ES6 Iterator。

urlSearchParams[Symbol.iterator]()#

• 返回值: <Iterator>

返回查询字符串中每个名称-值对的 ES6 Iterator。迭代器的每个项目都是一个 JavaScript Array。Array 的第一个项目是 name，Array 的第二个项目是 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 copy

url.domainToASCII(domain)#

• domain <string>
• 返回值: <string>

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

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

import url from 'node: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 stringconst url = require('node: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 stringcopy

url.domainToUnicode(domain)#

• domain <string>
• 返回值: <string>

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

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

import url from 'node: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 stringconst url = require('node: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 stringcopy

url.fileURLToPath(url)#

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

此函数确保百分比编码字符的正确解码，并确保跨平台有效的绝对路径字符串。

import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);

new URL('file:///C:/path/').pathname;      // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/');         // Correct:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;    // Incorrect: /foo.txt
fileURLToPath('file://nas/foo.txt');       // Correct:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;      // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');         // Correct:   /你好.txt (POSIX)

new URL('file:///hello world').pathname;   // Incorrect: /hello%20world
fileURLToPath('file:///hello world');      // Correct:   /hello world (POSIX)const { fileURLToPath } = require('node:url');
new URL('file:///C:/path/').pathname;      // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/');         // Correct:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;    // Incorrect: /foo.txt
fileURLToPath('file://nas/foo.txt');       // Correct:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;      // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');         // Correct:   /你好.txt (POSIX)

new URL('file:///hello world').pathname;   // Incorrect: /hello%20world
fileURLToPath('file:///hello world');      // Correct:   /hello world (POSIX)copy

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> 如果 URL 字符串的主机组件中出现的 Unicode 字符应直接编码，而不是 Punycode 编码，则为 true。默认值：false。
• 返回值: <string>

返回 WHATWG URL 对象的 URL String 表示形式的可定制序列化。

URL 对象同时具有 toString() 方法和 href 属性，它们返回 URL 的字符串序列化。但是，这些方法无法以任何方式进行定制。url.format(URL[, options]) 方法允许对输出进行基本定制。

import url from 'node:url';
const myURL = new URL('https://a:b@測試?abc#foo');

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

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

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://測試/?abc'const url = require('node:url');
const myURL = new URL('https://a:b@測試?abc#foo');

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

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

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

url.pathToFileURL(path)#

• path <string> 要转换为文件 URL 的路径。
• 返回值：<URL> 文件 URL 对象。

此函数确保 path 被绝对解析，并且在转换为文件 URL 时 URL 控制字符被正确编码。

import { pathToFileURL } from 'node:url';

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

new URL('/some/path%.c', 'file:');    // Incorrect: file:///some/path%.c
pathToFileURL('/some/path%.c');       // Correct:   file:///some/path%25.c (POSIX)const { pathToFileURL } = require('node: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%.c', 'file:');    // Incorrect: file:///some/path%.c
pathToFileURL('/some/path%.c');       // Correct:   file:///some/path%25.c (POSIX)copy

url.urlToHttpOptions(url)#

• url <URL> 要转换为选项对象的 WHATWG URL 对象。
• 返回值：<Object> 选项对象
  • protocol <string> 要使用的协议。
  • hostname <string> 要向其发出请求的服务器的域名或 IP 地址。
  • hash <string> URL 的片段部分。
  • search <string> URL 的序列化查询部分。
  • pathname <string> URL 的路径部分。
  • path <string> 请求路径。应包含查询字符串（如果有）。例如：'/index.html?page=12'。当请求路径包含非法字符时，将抛出异常。目前，只有空格被拒绝，但这在将来可能会改变。
  • href <string> 序列化的 URL。
  • port <number> 远程服务器的端口。
  • auth <string> 基本身份验证，例如 'user:password'，用于计算授权头。

此实用程序函数将 URL 对象转换为普通选项对象，如 http.request() 和 https.request() API 所期望的那样。

import { urlToHttpOptions } from 'node:url';
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(urlToHttpOptions(myURL));
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/const { urlToHttpOptions } = require('node:url');
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(urlToHttpOptions(myURL));
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/copy

旧版 URL API#

旧版 urlObject#

旧版 urlObject（require('node:url').Url 或 import { Url } from 'node:url'）由 url.parse() 函数创建并返回。

urlObject.auth#

auth 属性是 URL 的用户名和密码部分，也称为用户信息。此字符串子集位于协议和双斜杠（如果存在）之后，位于主机组件之前，由@分隔。该字符串要么是用户名，要么是用户名和密码，用:分隔。

例如：'user:pass'。

urlObject.hash#

hash 属性是 URL 的片段标识符部分，包括前导#字符。

例如：'#hash'。

urlObject.host#

host 属性是 URL 的完整小写主机部分，包括指定的端口（如果存在）。

例如：'sub.example.com:8080'。

urlObject.hostname#

hostname 属性是host组件的小写主机名部分，不包括端口。

例如：'sub.example.com'。

urlObject.href#

href 属性是解析的完整 URL 字符串，其中协议和主机组件都转换为小写。

例如：'http://user:[email protected]: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' 或 {'query': 'string'}。

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

urlObject.search#

search属性包含 URL 的整个“查询字符串”部分，包括前导 ASCII 问号 (?) 字符。

例如：'?query=string'。

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

urlObject.slashes#

slashes属性是一个boolean值，如果在protocol中的冒号后面需要两个 ASCII 正斜杠字符 (/)，则其值为true。

url.format(urlObject)#

• urlObject <Object> | <string> 一个 URL 对象（由 url.parse() 返回或以其他方式构造）。如果是一个字符串，则通过将其传递给 url.parse() 来将其转换为对象。

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

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

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

如果 urlObject 不是对象或字符串，url.format() 将抛出 TypeError。

格式化过程按如下方式操作

• 创建一个新的空字符串 result。
• 如果 urlObject.protocol 是一个字符串，则将其原样追加到 result。
• 否则，如果 urlObject.protocol 不是 undefined 且不是字符串，则会抛出 Error。
• 对于所有不以 ASCII 冒号 (:) 字符结尾的 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不以 ASCII 正斜杠 (/) 开头，则文字字符串 '/' 被追加到 result。
  • urlObject.pathname 的值将追加到 result 中。
• 否则，如果 urlObject.pathname 不是 undefined 且不是字符串，则会抛出一个 Error。
• 如果 urlObject.search 属性为 undefined 且 urlObject.query 属性为 Object，则将文字字符串 ? 追加到 result 中，后面跟着调用 querystring 模块的 stringify() 方法的输出，并将 urlObject.query 的值作为参数传递。
• 否则，如果 urlObject.search 是一个字符串
  • 如果 urlObject.search 的值不以 ASCII 问号 (?) 字符开头，则将文字字符串 ? 追加到 result 中。
  • urlObject.search 的值将追加到 result 中。
• 否则，如果 urlObject.search 不是 undefined 且不是字符串，则会抛出一个 Error。
• 如果 urlObject.hash 属性是一个字符串
  • 如果 urlObject.hash 的值不以 ASCII 井号 (#) 字符开头，则将文字字符串 # 追加到 result 中。
  • urlObject.hash 的值将追加到 result 中。
• 否则，如果 urlObject.hash 属性不是 undefined 且不是字符串，则会抛出一个 Error。
• 返回 result。

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

• 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 对象。

如果 urlString 不是字符串，则会抛出 TypeError。

如果 auth 属性存在但无法解码，则会抛出 URIError。

url.parse() 使用一种宽松的、非标准的算法来解析 URL 字符串。它容易受到安全问题的影响，例如 主机名欺骗 和对用户名和密码的错误处理。不要与不受信任的输入一起使用。不会为 url.parse() 漏洞发布 CVE。请改用 WHATWG URL API。

url.resolve(from, to)#

• from <string> 如果 to 是一个相对 URL，则要使用的基本 URL。
• to <string> 要解析的目标 URL。

url.resolve() 方法以类似于 Web 浏览器解析锚标签的方式解析相对于基本 URL 的目标 URL。

const url = require('node: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' copy

要使用 WHATWG URL API 达到相同的结果

function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
  if (resolvedUrl.protocol === 'resolve:') {
    // `from` is a relative URL.
    const { pathname, search, hash } = resolvedUrl;
    return pathname + search + hash;
  }
  return resolvedUrl.toString();
}

resolve('/one/two/three', 'four');         // '/one/two/four'
resolve('http://example.com/', '/one');    // 'http://example.com/one'
resolve('http://example.com/one', '/two'); // 'http://example.com/two' copy

URL 中的百分比编码#

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

传统 API#

在传统 API 中，空格 (' ') 和以下字符将在 URL 对象的属性中自动转义

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

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

WHATWG API#

WHATWG URL 标准 使用比传统 API 更具选择性和细粒度的编码字符选择方法。

WHATWG 算法定义了四个“百分比编码集”，用于描述必须进行百分比编码的字符范围。

• C0 控制百分比编码集 包括范围 U+0000 到 U+001F（含）内的代码点，以及所有大于 U+007E (~) 的代码点。

• 片段百分比编码集 包括 C0 控制百分比编码集 和代码点 U+0020 SPACE、U+0022 (")、U+003C (<)、U+003E (>) 和 U+0060 (`)。

• 路径百分比编码集 包括 C0 控制百分比编码集 和代码点 U+0020 SPACE、U+0022 (")、U+0023 (#)、U+003C (<)、U+003E (>)、U+003F (?)、U+0060 (`)、U+007B ({) 和 U+007D (})。

• 用户信息编码集 包括 路径百分比编码集 和代码点 U+002F (/)、U+003A (:)、U+003B (;)、U+003D (=)、U+0040 (@)、U+005B ([) 到 U+005E(^) 和 U+007C (|)。

用户信息百分比编码集 专用于 URL 中编码的用户名和密码。路径百分比编码集 用于大多数 URL 的路径。片段百分比编码集 用于 URL 片段。C0 控制百分比编码集 用于主机和路径，在某些特定情况下，以及所有其他情况下。

当主机名中出现非 ASCII 字符时，主机名将使用 Punycode 算法进行编码。但是请注意，主机名可能同时包含 Punycode 编码字符和百分比编码字符。

const myURL = new URL('https://%CF%80.example.com/foo');
console.log(myURL.href);
// Prints https://xn--1xa.example.com/foo
console.log(myURL.origin);
// Prints https://xn--1xa.example.com copy