Node.js v25.0.0 文档

new URL(input[, base])#

• input <string> 要解析的绝对或相对输入 URL。如果 input 是相对的，则 base 是必需的。如果 input 是绝对的，则 base 会被忽略。如果 input 不是字符串，它会首先被转换为字符串。
• base <string> 如果 input 不是绝对 URL，则用作解析基准的 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:xyz@example.com');
console.log(myURL.password);
// Prints xyz

myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:123@example.com/ 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（含）之间。将值设置为 URL 对象给定 protocol 的默认端口，将导致 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 设置器。有关详细信息，请参阅 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:xyz@example.com');
console.log(myURL.username);
// Prints abc

myURL.username = '123';
console.log(myURL.href);
// Prints https://123:xyz@example.com/ 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() 的值。

当 URL 对象使用 JSON.stringify() 进行序列化时，会自动调用此方法。

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> 对象的 'blob:nodedata:...' URL 字符串，该字符串可用于稍后检索 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，则用作解析基准的 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，则用作解析基准的 URL。如果 base 不是字符串，它会首先被转换为字符串。
• 返回：<URL> | <null>

将字符串解析为 URL。如果提供了 base，它将被用作解析非绝对 input URL 的基准 URL。如果参数无法解析为有效的 URL，则返回 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> 一个可迭代对象，其元素是键值对

使用可迭代映射实例化一个新的 URLSearchParams 对象，方式类似于 <Map> 的构造函数。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[Symbol.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>

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

如果提供了 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，第二项是 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 的用户名和密码部分，也称为用户信息。此字符串子集跟在 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 属性是解析后的完整 URL 字符串，其中 protocol 和 host 组件都已转换为小写。

例如：'http://user:pass@sub.example.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' 或 {'query': 'string'}。

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

urlObject.search#

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

例如：'?query=string'。

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

urlObject.slashes#

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