URL

URL parsing, components, relative resolution, and why a successful parse is not a safety check, verified in Node.js 22.23.3.

模块页正文目前为英文。

The URL API parses and composes absolute URLs. new URL(input, base) resolves a relative input against a base. URL.canParse returns a boolean instead of throwing. These interfaces are Web APIs, not ECMAScript language built-ins such as String.

Examples were checked in Node.js 22.23.3, which provides URL as a global. This is not a browser visual test. A successful parse is not a validation that the URL is safe to request, render, or open. The examples never call fetch or open a page.

Examples were checked in Node.js 22.23.3, which provides these Web APIs as built-in globals. This is not a browser DOM test, and the examples do not send network requests. See the MDN documentation for the complete API, including browser support.

Web APIs overview → · JavaScript tutorial and built-in APIs →

API index

APISummary
new URL(), URL.canParse()Parse an absolute or relative URL, read its components, or test whether it can be parsed without throwing.
URL parsing pitfallsShow that javascript: URLs, data: URLs, path normalization, and userinfo-as-host all parse successfully.

Constructor, components, and canParse

new URL("https://User:[email protected]:8080/path/page?q=1#hash") fills href, origin, protocol, username, password, host, hostname, port, pathname, search, and hash. origin does not include the userinfo. host includes the port when the port is present; hostname does not.

new URL("/rel?x=1", "https://example.com/base/dir") resolves to https://example.com/rel?x=1. URL.canParse is true for that pair and for an absolute https URL, and false for "not a url". new URL throws TypeError for an invalid absolute string and for a relative string with no base.

new URL(), URL.canParse()

new URL(url)
new URL(url, base)
URL.canParse(url)
URL.canParse(url, base)

Parse an absolute or relative URL, read its components, or test whether it can be parsed without throwing.

ParameterDescription
urlAn absolute URL string, or a relative URL when base is provided.
baseAn absolute URL used to resolve a relative url. Required when url is relative.

Returns: A URL object, or a boolean from canParse. The example prints selected components and two TypeError names.

Throws

  • TypeError — Thrown by the constructor when url cannot be parsed, including a relative URL without a base. Measured in Node.js 22.23.3.
  • URL.canParse was available in this Node.js 22.23.3 runtime. Check MDN if you need older browser support.
javascript
const absolute = new URL("https://User:[email protected]:8080/path/page?q=1#hash");
console.log(absolute.href);
console.log(absolute.origin);
console.log(absolute.protocol, absolute.username, absolute.password);
console.log(absolute.host, absolute.hostname, absolute.port);
console.log(absolute.pathname, absolute.search, absolute.hash);

const relative = new URL("/rel?x=1", "https://example.com/base/dir");
console.log(relative.href);

console.log(URL.canParse("https://example.com/"));
console.log(URL.canParse("/rel", "https://example.com/"));
console.log(URL.canParse("not a url"));

try {
  new URL("not a url");
} catch (error) {
  console.log(error.name);
}
try {
  new URL("/rel");
} catch (error) {
  console.log(error.name);
}

Expected output

https://User:[email protected]:8080/path/page?q=1#hash
https://example.com:8080
https: User Pass
example.com:8080 example.com 8080
/path/page ?q=1 #hash
https://example.com/rel?x=1
true
true
false
TypeError
TypeError

Related: URLSearchParams

MDN documentation →

Parsing is not a safety check

The constructor accepts many strings that are valid URLs and unsafe as untrusted input. javascript:example and data:text/plain,hi both parse. https://example.com/a/../../b is normalized to pathname /b. None of these checks whether the result is safe to fetch, to use as a redirect, or to treat as a same-origin path.

https://[email protected]/path is especially easy to misread. The hostname and origin are evil.example; example.com is the username. If you only inspect href, you can miss that. Always read hostname or origin when the authority matters, and do not treat URL parsing as validation.

URL parsing pitfalls

new URL(url)

Show that javascript: URLs, data: URLs, path normalization, and userinfo-as-host all parse successfully.

Returns: URL objects whose components reveal the parsed authority and path, not a pass or fail safety result.

  • The example does not load these URLs. javascript: and data: behavior in a browser document was not measured here.
javascript
const script = new URL("javascript:example");
console.log(script.protocol, script.hostname, script.href);

const data = new URL("data:text/plain,hi");
console.log(data.protocol, data.href);

const dotted = new URL("https://example.com/a/../../b");
console.log(dotted.pathname, dotted.href);

const userinfo = new URL("https://[email protected]/path");
console.log(userinfo.username, userinfo.hostname, userinfo.origin, userinfo.href);

Expected output

javascript:  javascript:example
data: data:text/plain,hi
/b https://example.com/b
example.com evil.example https://evil.example https://[email protected]/path

MDN documentation →