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: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（包括）范围内的数字或包含数字的字符串。 将值设置为给定 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: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() 的值。

当使用 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> 对象的 '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 对象在当前线程中注册。 如果使用 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

URL.parse(input[, base])#

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

将字符串解析为 URL。 如果提供了 base，则它将用作解析非绝对 input URL 的基本 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 为 name 且 value 为 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 的用户名和密码部分，也称为用户信息。 此字符串子集遵循 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#

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