Строки URL и объекты URL

Строка URL — это структурированная строка, содержащая несколько значимых компонентов. При разборе возвращается объект URL со свойствами для каждого из этих компонентов.

Модуль node:url предоставляет два API для работы с URL: устаревший API, специфичный для Node.js, и более новый API, реализующий тот же стандарт URL WHATWG, который используется веб-браузерами.

Ниже приведено сравнение API WHATWG и устаревшего API. Над схемой URL 'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash' показаны свойства объекта, возвращаемого устаревшим url.parse(). Под ней показаны свойства объекта URL WHATWG.

Свойство origin URL WHATWG включает 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

Разбор строки URL с использованием API WHATWG:

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

Разбор строки URL с использованием устаревшего API:

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

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

Создание URL из отдельных компонентов и получение созданной строки

URL WHATWG можно создать из отдельных компонентов, используя либо сеттеры свойств, либо строковый литерал-шаблон:

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

API URL WHATWG

Класс: URL

Совместимый с браузерами класс URL, реализованный в соответствии со стандартом WHATWG URL. В самом стандарте можно найти примеры разобранных URL. Класс URL также доступен в глобальном объекте.

В соответствии с соглашениями браузеров все свойства объектов URL реализованы как геттеры и сеттеры в прототипе класса, а не как свойства данных самого объекта. Поэтому, в отличие от устаревших urlObject, использование ключевого слова delete для любых свойств объектов URL (например, delete myURL.protocol, delete myURL.pathname и т. д.) не даёт эффекта, но всё же возвращает true.

new URL(input[, base])

• input <string> Абсолютный или относительный URL для разбора. Если input является относительным, требуется base. Если input является абсолютным, base игнорируется. Если input не является строкой, сначала он преобразуется в строку.
• base <string> Базовый URL для разрешения относительного URL, если input не является абсолютным. Если base не является строкой, сначала он преобразуется в строку.

Создаёт новый объект URL, разбирая input относительно base. Если 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'.

Будет выброшено исключение TypeError, если input или base не являются допустимыми URL. Обратите внимание, что переданные значения будут преобразованы в строки. Например:

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

Символы Юникода в имени хоста input будут автоматически преобразованы в ASCII с помощью алгоритма Punycode.

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

Если заранее неизвестно, является ли input абсолютным URL, и указан base, рекомендуется проверить, соответствует ли origin объекта URL ожидаемому значению.

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

Недопустимые символы URL, содержащиеся в значении, присвоенном свойству hash, кодируются в процентах. Выбор символов для процентного кодирования может несколько отличаться от того, который выполняют методы 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().

Присвоение этому свойству нового значения эквивалентно созданию нового объекта URL с помощью new URL(value). Будут изменены все свойства объекта 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

Недопустимые символы URL, содержащиеся в значении, присвоенном свойству password, кодируются в процентах. Выбор символов для процентного кодирования может несколько отличаться от того, который выполняют методы 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

Недопустимые символы URL, содержащиеся в значении, присвоенном свойству pathname, кодируются в процентах. Выбор символов для процентного кодирования может несколько отличаться от того, который выполняют методы 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

Недопустимые значения протокола URL, присвоенные свойству protocol, игнорируются.

Специальные схемы

Стандарт 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

Все недопустимые символы URL, содержащиеся в значении, присвоенном свойству search, будут закодированы в процентах. Выбор символов для процентного кодирования может несколько отличаться от того, который выполняют методы url.parse() и url.format().

url.searchParams

• <URLSearchParams>

Возвращает объект URLSearchParams, представляющий параметры запроса URL. Это свойство доступно только для чтения, но предоставляемый им объект 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

Все недопустимые символы URL, содержащиеся в значении, присвоенном свойству username, будут закодированы в процентах. Выбор символов для процентного кодирования может несколько отличаться от того, который выполняют методы url.parse() и url.format().

url.toString()

• Возвращает: <string>

Метод toString() объекта URL возвращает сериализованный URL. Возвращаемое значение эквивалентно значению url.href и url.toJSON().

url.toJSON()

• Возвращает: <string>

Метод toJSON() объекта URL возвращает сериализованный 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>

Создаёт строку URL 'blob:nodedata:...', представляющую переданный объект <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 'blob:nodedata:..., возвращённая предыдущим вызовом URL.createObjectURL().

Удаляет сохранённый <Blob>, идентифицированный указанным ID. Попытка отозвать ID, который не зарегистрирован, не приведёт к ошибке.

URL.canParse(input[, base])

• input <string> Абсолютный или относительный URL для разбора. Если input является относительным, требуется base. Если input является абсолютным, base игнорируется. Если input не является строкой, сначала он преобразуется в строку.
• base <string> Базовый URL для разрешения относительного URL, если input не является абсолютным. Если base не является строкой, сначала он преобразуется в строку.
• Возвращает: <boolean>

Проверяет, можно ли разобрать input относительно base как 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> Базовый URL для разрешения относительного URL, если input не является абсолютным. Если base не является строкой, сначала он преобразуется в строку.
• Возвращает: <URL> | <null>

Разбирает строку как URL. Если указан base, он будет использоваться в качестве базового URL для разрешения неабсолютных URL input. Возвращает null, если input не является допустимым.

Класс: URLSearchParams

API URLSearchParams предоставляет доступ на чтение и запись к строке запроса объекта 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> Итерируемый объект, элементы которого являются парами «ключ-значение»

Создаёт новый объект 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, второй элемент Array — это value.

Псевдоним для urlSearchParams[@@iterator]().

urlSearchParams.forEach(fn[, thisArg])

• fn <Function> Вызывается для каждой пары «имя-значение» в строке запроса
• thisArg <Object> Используется в качестве значения this при вызове fn

Перебирает все пары «имя-значение» в строке запроса и вызывает заданную функцию.

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> Строку или null, если нет пары «имя-значение» с указанным name.

Возвращает значение первой пары «имя-значение», имя которой равно name. Если таких пар нет, возвращается null.

urlSearchParams.getAll(name)

• name <string>
• Возвращает: <string[]>

Возвращает значения всех пар «имя-значение», имя которых равно name. Если таких пар нет, возвращается пустой массив.

urlSearchParams.has(name[, value])

• name <string>
• value <string>
• Возвращает: <boolean>

Проверяет, содержит ли объект URLSearchParams пару или пары «ключ-значение» с учётом name и необязательного аргумента value.

Если указан value, возвращает true, если существует пара «имя-значение» с теми же name и value.

Если value не указан, возвращает true, если существует хотя бы одна пара «имя-значение» с именем name.

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 значение value, соответствующее name. Если уже существуют пары «имя-значение» с именем 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

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

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 string

const 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 string

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 string

const 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 string

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)

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'

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)

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'
}
*/

Устаревший API URL

Устаревший urlObject

Устаревший urlObject (require('node:url').Url или import { Url } from 'node:url') создаётся и возвращается функцией url.parse().

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 содержит полную строку 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 (?), либо объект, возвращаемый методом parse() модуля querystring. Тип свойства query — строка или объект — определяется аргументом parseQueryString, переданным в url.parse().

Например: 'query=string' или {'query': 'string'}.

Если результат возвращается в виде строки, декодирование строки запроса не выполняется. Если он возвращается в виде объекта, декодируются и ключи, и значения.

urlObject.search

Свойство search содержит всю часть URL со «строкой запроса», включая начальный символ вопроса ASCII (?).

Например: '?query=string'.

Декодирование строки запроса не выполняется.

urlObject.slashes

Свойство slashes — это boolean со значением true, если после двоеточия в protocol требуются две косые черты ASCII (/).

url.format(urlObject)

• urlObject <Object> | <string> Объект URL (возвращаемый функцией url.parse() или созданный другим способом). Если передана строка, она преобразуется в объект путём передачи в url.parse().

Метод url.format() возвращает отформатированную строку URL, полученную из urlObject.

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.
• Для всех строковых значений urlObject.protocol, которые не заканчиваются двоеточием ASCII (:), к result добавляется строка :.
• Если выполняется хотя бы одно из следующих условий, к result добавляется строка //:
  • Свойство urlObject.slashes имеет значение true;
  • 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 добавляется строка ?, за которой следует результат вызова метода stringify() модуля querystring с передачей значения 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 всегда будет присваиваться объект, возвращаемый методом parse() модуля querystring. Если false, свойство query возвращаемого объекта URL будет содержать неразобранную, недекодированную строку. По умолчанию: 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 снисходительный, нестандартный алгоритм. Он может приводить к проблемам безопасности, например к подмене имени узла и неправильной обработке имён пользователей и паролей. Не используйте его с недоверенными данными. CVE для уязвимостей url.parse() не присваиваются. Вместо него используйте API WHATWG URL.

url.resolve(from, to)

• from <string> Базовый URL, используемый, если to — относительный URL.
• to <string> Целевой URL для разрешения.

Метод url.resolve() разрешает целевой URL относительно базового 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

Чтобы получить тот же результат с помощью API WHATWG URL:

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.

API WHATWG

Стандарт URL WHATWG использует более избирательный и детализированный подход к выбору кодируемых символов, чем устаревший 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 (}).

• Набор userinfo для кодирования включает набор пути для процентного кодирования, а также кодовые точки U+002F (/), U+003A (:), U+003B (;), U+003D (=), U+0040 (@), от U+005B ([) до U+005E(^) и U+007C (|).

Набор userinfo для процентного кодирования используется исключительно для имени пользователя и паролей, закодированных в 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