Node.js v24.0.0 文档

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 协议值将被忽略。

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

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

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 setter。有关详细信息，请参阅 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 对象在当前线程中注册。如果使用工作线程，则在一个工作线程中注册的 Blob 对象将不适用于其他工作线程或主线程。

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

URL.parse(input[, base])#

• input <string> 要解析的绝对或相对输入 URL。 如果 input 是相对的，则需要 base。 如果 input 是绝对的，则忽略 base。 如果 input 不是字符串，则首先会 转换为字符串。
• base <string> 如果 input 不是绝对的，则针对其解析的基本 URL。 如果 base 不是字符串，则首先会 转换为字符串。
• 返回：<URL> | <null>

将字符串解析为 URL。 如果提供了 base，它将被用作基本 URL，用于解析非绝对 input URL。 如果 input 无效，则返回 null。

new URLPattern()#

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

new URLPattern(string[, baseURL][, options])#

• string <string> 一个 URL 字符串
• baseURL <string> | <undefined> 一个基本 URL 字符串
• options <Object> 选项

将 string 解析为 URL，并使用它来实例化一个新的 URLPattern 对象。

如果未指定 baseURL，则默认为 undefined。

一个选项可以具有 ignoreCase 布尔属性，如果设置为 true，则启用不区分大小写的匹配。

构造函数可能会抛出 TypeError 以指示解析失败。

new URLPattern(obj[, baseURL][, options])#

• obj <Object> 一个输入模式
• baseURL <string> | <undefined> 一个基本 URL 字符串
• options <Object> 选项

解析 Object 作为输入模式，并使用它来实例化一个新的 URLPattern 对象。对象成员可以是 protocol、username、password、hostname、port、pathname、search、hash 或 baseURL 中的任何一个。

如果未指定 baseURL，则默认为 undefined。

一个选项可以具有 ignoreCase 布尔属性，如果设置为 true，则启用不区分大小写的匹配。

构造函数可能会抛出 TypeError 以指示解析失败。

urlPattern.exec(input[, baseURL])#

• input <string> | <Object> 一个 URL 或 URL 的各个部分
• baseURL <string> | <undefined> 一个基本 URL 字符串

输入可以是字符串或提供各个 URL 部分的对象。对象成员可以是 protocol、username、password、hostname、port、pathname、search、hash 或 baseURL 中的任何一个。

如果未指定 baseURL，则默认为 undefined。

返回一个对象，其中包含一个 inputs 键，该键包含传递给函数的参数数组，以及 URL 组件的键，其中包含匹配的输入和匹配的组。

const myPattern = new URLPattern('https://node.org.cn/docs/latest/api/*.html');
console.log(myPattern.exec('https://node.org.cn/docs/latest/api/dns.html'));
// Prints:
// {
//  "hash": { "groups": {  "0": "" },  "input": "" },
//  "hostname": { "groups": {}, "input": "nodejs.org" },
//  "inputs": [
//    "https://node.org.cn/docs/latest/api/dns.html"
//  ],
//  "password": { "groups": { "0": "" }, "input": "" },
//  "pathname": { "groups": { "0": "dns" }, "input": "/docs/latest/api/dns.html" },
//  "port": { "groups": {}, "input": "" },
//  "protocol": { "groups": {}, "input": "https" },
//  "search": { "groups": { "0": "" }, "input": "" },
//  "username": { "groups": { "0": "" }, "input": "" }
// } copy

urlPattern.test(input[, baseURL])#

• input <string> | <Object> 一个 URL 或 URL 的各个部分
• baseURL <string> | <undefined> 一个基本 URL 字符串

输入可以是字符串或提供各个 URL 部分的对象。对象成员可以是 protocol、username、password、hostname、port、pathname、search、hash 或 baseURL 中的任何一个。

如果未指定 baseURL，则默认为 undefined。

返回一个布尔值，指示输入是否与当前模式匹配。

const myPattern = new URLPattern('https://node.org.cn/docs/latest/api/*.html');
console.log(myPattern.test('https://node.org.cn/docs/latest/api/dns.html'));
// Prints: true 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，Array 的第二项是 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>

将与 name 关联的 URLSearchParams 对象中的值设置为 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

urlObject.auth#

auth 属性是 URL 的用户名和密码部分，也称为 *userinfo*。此字符串子集遵循 protocol 和双斜杠（如果存在），并位于 host 组件之前，由 @ 分隔。该字符串可以是用户名，也可以是由 : 分隔的用户名和密码。

例如: 'user:pass'。

urlObject.hash#

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

例如: '#hash'。

urlObject.host#

host 属性是 URL 的完整小写主机部分，包括指定的 port。

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

urlObject.hostname#

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

例如: 'sub.example.com'。

urlObject.href#

href 属性是使用 protocol 和 host 组件转换为小写的已解析的完整 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 的整个 "query string" 部分，包括前导 ASCII 问号 (?) 字符。

例如: '?query=string'。

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

urlObject.slashes#

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