iDoc.dev

한국어

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
Русский
العربية

한국어

English
简体中文
Español
Français
Português
Deutsch
Italiano
日本語
Русский
العربية

테마

URL ​

[Stable: 2 - Stable]

Stable: 2 안정성: 2 - 안정됨

소스 코드: lib/url.js

node:url 모듈은 URL 확인 및 구문 분석을 위한 유틸리티를 제공합니다. 다음을 사용하여 액세스할 수 있습니다:

js
import url from 'node:url'
js
const url = require('node:url')

URL 문자열과 URL 객체 ​

URL 문자열은 의미 있는 여러 구성 요소를 포함하는 구조화된 문자열입니다. 구문 분석되면 이러한 각 구성 요소에 대한 속성을 포함하는 URL 객체가 반환됩니다.

node:url 모듈은 URL 작업을 위한 두 가지 API를 제공합니다. 하나는 Node.js 특정의 레거시 API이고 다른 하나는 웹 브라우저에서 사용되는 것과 동일한 WHATWG URL 표준을 구현하는 최신 API입니다.

WHATWG와 레거시 API의 비교는 아래에 제공됩니다. URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash' 위에 레거시 url.parse()에서 반환된 객체의 속성이 표시됩니다. 아래에는 WHATWG URL 객체의 속성이 표시됩니다.

WHATWG URL의 origin 속성에는 protocol 및 host가 포함되지만 username 또는 password는 포함되지 않습니다.

text
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              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                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
( "" 줄의 모든 공백은 무시해야 합니다. 순전히 형식을 위한 것입니다.)

WHATWG API를 사용하여 URL 문자열 구문 분석:

js
const myURL = new URL('https://user::8080/p/a/t/h?query=string#hash')

레거시 API를 사용하여 URL 문자열 구문 분석:

js
import url from 'node:url'
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')
js
const url = require('node:url')
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')

구성 요소에서 URL 구성 및 구성된 문자열 가져오기 ​

속성 설정자 또는 템플릿 리터럴 문자열을 사용하여 구성 요소 부분에서 WHATWG URL을 구성할 수 있습니다.

js
const myURL = new URL('https://example.org')
myURL.pathname = '/a/b/c'
myURL.search = '?d=e'
myURL.hash = '#fgh'
js
const pathname = '/a/b/c'
const search = '?d=e'
const hash = '#fgh'
const myURL = new URL(`https://example.org${pathname}${search}${hash}`)

구성된 URL 문자열을 가져오려면 href 속성 접근자를 사용하십시오.

js
console.log(myURL.href)

WHATWG URL API ​

클래스: URL ​

[기록]

버전변경 사항
v10.0.0이제 클래스를 전역 객체에서 사용할 수 있습니다.
v7.0.0, v6.13.0다음에서 추가됨: v7.0.0, v6.13.0

WHATWG URL 표준에 따라 구현된 브라우저 호환 URL 클래스입니다. 구문 분석된 URL의 예는 표준 자체에서 찾을 수 있습니다. URL 클래스는 전역 객체에서도 사용할 수 있습니다.

브라우저 규칙에 따라 URL 객체의 모든 속성은 객체 자체의 데이터 속성 대신 클래스 프로토타입에서 getter 및 setter로 구현됩니다. 따라서 레거시 urlObject와 달리 URL 객체의 모든 속성(예: delete myURL.protocol, delete myURL.pathname 등)에서 delete 키워드를 사용해도 아무런 효과가 없지만 여전히 true를 반환합니다.

new URL(input[, base]) ​

[기록]

버전변경 사항
v20.0.0, v18.17.0ICU 요구 사항이 제거되었습니다.
  • input <string> 구문 분석할 절대 또는 상대 입력 URL입니다. input이 상대적인 경우 base가 필요합니다. input이 절대적인 경우 base는 무시됩니다. input이 문자열이 아니면 먼저 문자열로 변환됩니다.
  • base <string> input이 절대적이지 않은 경우 기준으로 확인할 기본 URL입니다. base가 문자열이 아니면 먼저 문자열로 변환됩니다.

base에 상대적인 input을 구문 분석하여 새 URL 객체를 만듭니다. base가 문자열로 전달되면 new URL(base)와 동일하게 구문 분석됩니다.

js
const myURL = new URL('/foo', 'https://example.org/')
// https://example.org/foo

URL 생성자는 전역 객체의 속성으로 접근할 수 있습니다. 또한 내장 url 모듈에서 가져올 수도 있습니다.

js
import { URL } from 'node:url'
console.log(URL === globalThis.URL) // 'true' 출력.
js
console.log(URL === require('node:url').URL) // 'true' 출력.

input 또는 base가 유효한 URL이 아니면 TypeError가 발생합니다. 제공된 값을 문자열로 강제 변환하려는 시도가 이루어질 것입니다. 예를 들면 다음과 같습니다.

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

input의 호스트 이름 내에 나타나는 유니코드 문자는 Punycode 알고리즘을 사용하여 자동으로 ASCII로 변환됩니다.

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

input이 절대 URL인지 미리 알 수 없고 base가 제공되는 경우 URL 객체의 origin이 예상한 것인지 확인하는 것이 좋습니다.

js
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/

url.hash ​

URL의 fragment 부분을 가져오거나 설정합니다.

js
const myURL = new URL('https://example.org/foo#bar')
console.log(myURL.hash)
// #bar 출력

myURL.hash = 'baz'
console.log(myURL.href)
// https://example.org/foo#baz 출력

hash 속성에 할당된 값에 포함된 유효하지 않은 URL 문자는 퍼센트 인코딩됩니다. 퍼센트 인코딩할 문자를 선택하는 것은 url.parse() 및 url.format() 메서드가 생성하는 것과 약간 다를 수 있습니다.

url.host ​

URL의 호스트 부분을 가져오거나 설정합니다.

js
const myURL = new URL('https://example.org:81/foo')
console.log(myURL.host)
// example.org:81 출력

myURL.host = 'example.com:82'
console.log(myURL.href)
// https://example.com:82/foo 출력

host 속성에 할당된 유효하지 않은 호스트 값은 무시됩니다.

url.hostname ​

URL의 호스트 이름 부분을 가져오거나 설정합니다. url.host와 url.hostname의 주요 차이점은 url.hostname은 포트를 포함하지 않는다는 것입니다.

js
const myURL = new URL('https://example.org:81/foo')
console.log(myURL.hostname)
// example.org 출력

// 호스트 이름 설정은 포트를 변경하지 않습니다
myURL.hostname = 'example.com'
console.log(myURL.href)
// https://example.com:81/foo 출력

// 호스트 이름과 포트를 변경하려면 myURL.host를 사용합니다
myURL.host = 'example.org:82'
console.log(myURL.href)
// https://example.org:82/foo 출력

hostname 속성에 할당된 유효하지 않은 호스트 이름 값은 무시됩니다.

url.href ​

직렬화된 URL을 가져오거나 설정합니다.

js
const myURL = new URL('https://example.org/foo')
console.log(myURL.href)
// https://example.org/foo 출력

myURL.href = 'https://example.com/bar'
console.log(myURL.href)
// https://example.com/bar 출력

href 속성 값을 가져오는 것은 url.toString()을 호출하는 것과 같습니다.

이 속성의 값을 새 값으로 설정하는 것은 new URL(value)를 사용하여 새 URL 객체를 만드는 것과 같습니다. URL 객체의 각 속성이 수정됩니다.

href 속성에 할당된 값이 유효한 URL이 아니면 TypeError가 발생합니다.

url.origin ​

[연혁]

버전변경 사항
v15.0.0"gopher" 스킴이 더 이상 특별하지 않으며 url.origin은 이제 해당 스킴에 대해 'null'을 반환합니다.

URL의 원본의 읽기 전용 직렬화를 가져옵니다.

js
const myURL = new URL('https://example.org/foo/bar?baz')
console.log(myURL.origin)
// https://example.org 인쇄
js
const idnURL = new URL('https://測試')
console.log(idnURL.origin)
// https://xn--g6w251d 인쇄

console.log(idnURL.hostname)
// xn--g6w251d 인쇄

url.password ​

URL의 비밀번호 부분을 가져오고 설정합니다.

js
const myURL = new URL('https://abc:')
console.log(myURL.password)
// xyz 인쇄

myURL.password = '123'
console.log(myURL.href)
// https://abc:/ 인쇄

password 속성에 할당된 값에 포함된 유효하지 않은 URL 문자는 퍼센트 인코딩됩니다. 퍼센트 인코딩할 문자의 선택은 url.parse() 및 url.format() 메서드에서 생성되는 것과 다소 다를 수 있습니다.

url.pathname ​

URL의 경로 부분을 가져오고 설정합니다.

js
const myURL = new URL('https://example.org/abc/xyz?123')
console.log(myURL.pathname)
// /abc/xyz 인쇄

myURL.pathname = '/abcdef'
console.log(myURL.href)
// https://example.org/abcdef?123 인쇄

pathname 속성에 할당된 값에 포함된 유효하지 않은 URL 문자는 퍼센트 인코딩됩니다. 퍼센트 인코딩할 문자의 선택은 url.parse() 및 url.format() 메서드에서 생성되는 것과 다소 다를 수 있습니다.

url.port ​

[History]

VersionChanges
v15.0.0"gopher" 스킴은 더 이상 특수하지 않습니다.

URL의 포트 부분을 가져오고 설정합니다.

포트 값은 0에서 65535(포함) 범위의 숫자 또는 숫자를 포함하는 문자열일 수 있습니다. URL 객체의 주어진 protocol의 기본 포트로 값을 설정하면 port 값이 빈 문자열('')이 됩니다.

포트 값은 빈 문자열일 수 있으며 이 경우 포트는 프로토콜/스킴에 따라 다릅니다.

프로토콜포트
"ftp"21
"file"
"http"80
"https"443
"ws"80
"wss"443

포트에 값을 할당하면 먼저 .toString()을 사용하여 값이 문자열로 변환됩니다.

해당 문자열이 유효하지 않지만 숫자로 시작하는 경우 선행 숫자가 port에 할당됩니다. 숫자가 위에 표시된 범위를 벗어나는 경우 무시됩니다.

js
const myURL = new URL('https://example.org:8888')
console.log(myURL.port)
// 8888을 출력합니다.

// 기본 포트는 자동으로 빈 문자열로 변환됩니다.
// (HTTPS 프로토콜의 기본 포트는 443입니다.)
myURL.port = '443'
console.log(myURL.port)
// 빈 문자열을 출력합니다.
console.log(myURL.href)
// https://example.org/를 출력합니다.

myURL.port = 1234
console.log(myURL.port)
// 1234를 출력합니다.
console.log(myURL.href)
// https://example.org:1234/를 출력합니다.

// 완전히 유효하지 않은 포트 문자열은 무시됩니다.
myURL.port = 'abcd'
console.log(myURL.port)
// 1234를 출력합니다.

// 선행 숫자는 포트 번호로 처리됩니다.
myURL.port = '5678abcd'
console.log(myURL.port)
// 5678을 출력합니다.

// 정수가 아닌 숫자는 잘립니다.
myURL.port = 1234.5678
console.log(myURL.port)
// 1234를 출력합니다.

// 과학적 표기법으로 표현되지 않은 범위를 벗어난 숫자는
// 무시됩니다.
myURL.port = 1e10 // 10000000000, 아래에 설명된 대로 범위가 검사됩니다.
console.log(myURL.port)
// 1234를 출력합니다.

부동 소수점 숫자 또는 과학적 표기법의 숫자와 같이 소수점을 포함하는 숫자는 이 규칙의 예외가 아닙니다. 소수점 앞까지의 선행 숫자는 유효하다고 가정하고 URL의 포트로 설정됩니다.

js
myURL.port = 4.567e21
console.log(myURL.port)
// 4를 출력합니다. ('4.567e21' 문자열의 선행 숫자이기 때문입니다.)

url.protocol ​

URL의 프로토콜 부분을 가져오거나 설정합니다.

js
const myURL = new URL('https://example.org')
console.log(myURL.protocol)
// Prints https:

myURL.protocol = 'ftp'
console.log(myURL.href)
// Prints ftp://example.org/

protocol 속성에 할당된 잘못된 URL 프로토콜 값은 무시됩니다.

특수 스킴 ​

[기록]

버전변경 사항
v15.0.0"gopher" 스킴은 더 이상 특별하지 않습니다.

WHATWG URL 표준에서는 몇 가지 URL 프로토콜 스킴을 구문 분석 및 직렬화 방식 측면에서 특수하다고 간주합니다. 이러한 특수 프로토콜 중 하나를 사용하여 URL을 구문 분석하면 url.protocol 속성을 다른 특수 프로토콜로 변경할 수 있지만 특수하지 않은 프로토콜로 변경할 수는 없으며, 그 반대도 마찬가지입니다.

예를 들어 http에서 https로 변경하는 것은 작동합니다.

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

그러나 http에서 가상의 fish 프로토콜로 변경하는 것은 새 프로토콜이 특수하지 않기 때문에 작동하지 않습니다.

js
const u = new URL('http://example.org')
u.protocol = 'fish'
console.log(u.href)
// http://example.org/

마찬가지로 특수하지 않은 프로토콜에서 특수 프로토콜로 변경하는 것도 허용되지 않습니다.

js
const u = new URL('fish://example.org')
u.protocol = 'http'
console.log(u.href)
// fish://example.org

WHATWG URL 표준에 따르면 특수 프로토콜 스킴은 ftp, file, http, https, ws, wss입니다.

url.search ​

URL의 직렬화된 쿼리 부분을 가져오거나 설정합니다.

js
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

search 속성에 할당된 값에 나타나는 잘못된 URL 문자는 퍼센트 인코딩됩니다. 퍼센트 인코딩할 문자의 선택은 url.parse() 및 url.format() 메서드에서 생성하는 것과 다소 다를 수 있습니다.

url.searchParams ​

URL의 쿼리 매개변수를 나타내는 URLSearchParams 객체를 가져옵니다. 이 속성은 읽기 전용이지만, 제공되는 URLSearchParams 객체를 사용하여 URL 인스턴스를 변경할 수 있습니다. URL의 쿼리 매개변수 전체를 대체하려면 url.search 설정자를 사용하세요. 자세한 내용은 URLSearchParams 문서를 참조하세요.

.searchParams를 사용하여 URL을 수정할 때 주의해야 합니다. WHATWG 사양에 따라 URLSearchParams 객체는 퍼센트 인코딩할 문자를 결정하는 데 다른 규칙을 사용하기 때문입니다. 예를 들어, URL 객체는 ASCII 물결표(~) 문자를 퍼센트 인코딩하지 않지만, URLSearchParams는 항상 인코딩합니다.

js
const myURL = new URL('https://example.org/abc?foo=~bar')

console.log(myURL.search) // ?foo=~bar 출력

// searchParams를 통해 URL 수정...
myURL.searchParams.sort()

console.log(myURL.search) // ?foo=%7Ebar 출력

url.username ​

URL의 사용자 이름 부분을 가져오고 설정합니다.

js
const myURL = new URL('https://abc:')
console.log(myURL.username)
// abc 출력

myURL.username = '123'
console.log(myURL.href)
// https://123:/ 출력

username 속성에 할당된 값에 잘못된 URL 문자가 나타나면 퍼센트 인코딩됩니다. 퍼센트 인코딩할 문자의 선택은 url.parse() 및 url.format() 메서드가 생성하는 것과 다소 다를 수 있습니다.

url.toString() ​

URL 객체의 toString() 메서드는 직렬화된 URL을 반환합니다. 반환된 값은 url.href 및 url.toJSON()의 값과 동일합니다.

url.toJSON() ​

추가된 버전: v7.7.0, v6.13.0

URL 객체의 toJSON() 메서드는 직렬화된 URL을 반환합니다. 반환된 값은 url.href 및 url.toString()와 같습니다.

이 메서드는 URL 객체가 JSON.stringify()로 직렬화될 때 자동으로 호출됩니다.

js
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/"]

URL.createObjectURL(blob) ​

추가된 버전: v16.7.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

주어진 <Blob> 객체를 나타내는 'blob:nodedata:...' URL 문자열을 생성하고 나중에 Blob을 검색하는 데 사용할 수 있습니다.

js
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)

등록된 <Blob>에 의해 저장된 데이터는 URL.revokeObjectURL()이 호출되어 제거될 때까지 메모리에 보관됩니다.

Blob 객체는 현재 스레드 내에 등록됩니다. 워커 스레드를 사용하는 경우, 한 워커 내에 등록된 Blob 객체는 다른 워커 또는 메인 스레드에서 사용할 수 없습니다.

URL.revokeObjectURL(id) ​

추가된 버전: v16.7.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

  • id <string> 이전의 URL.createObjectURL() 호출에서 반환된 'blob:nodedata:... URL 문자열입니다.

주어진 ID로 식별되는 저장된 <Blob>을 제거합니다. 등록되지 않은 ID를 취소하려고 하면 아무런 오류 없이 실패합니다.

URL.canParse(input[, base]) ​

Added in: v19.9.0, v18.17.0

  • input <string> 파싱할 절대 또는 상대 입력 URL입니다. input이 상대적인 경우, base가 필요합니다. input이 절대적인 경우, base는 무시됩니다. input이 문자열이 아니면 먼저 문자열로 변환됩니다.
  • base <string> input이 절대적이지 않은 경우에 대해 확인하기 위한 기준 URL입니다. base가 문자열이 아니면 먼저 문자열로 변환됩니다.
  • Returns: <boolean>

base에 대한 상대적인 input이 URL로 파싱될 수 있는지 확인합니다.

js
const isValid = URL.canParse('/foo', 'https://example.org/') // true

const isNotValid = URL.canParse('/foo') // false

URL.parse(input[, base]) ​

Added in: v22.1.0

  • input <string> 파싱할 절대 또는 상대 입력 URL입니다. input이 상대적인 경우, base가 필요합니다. input이 절대적인 경우, base는 무시됩니다. input이 문자열이 아니면 먼저 문자열로 변환됩니다.
  • base <string> input이 절대적이지 않은 경우에 대해 확인하기 위한 기준 URL입니다. base가 문자열이 아니면 먼저 문자열로 변환됩니다.
  • Returns: <URL> | <null>

문자열을 URL로 파싱합니다. base가 제공되면, 절대적이지 않은 input URL을 확인하기 위해 기준 URL로 사용됩니다. input이 유효하지 않으면 null을 반환합니다.

클래스: URLSearchParams ​

[기록]

버전변경 사항
v10.0.0이제 클래스를 전역 객체에서 사용할 수 있습니다.
v7.5.0, v6.13.0추가됨: v7.5.0, v6.13.0

URLSearchParams API는 URL의 쿼리에 대한 읽기 및 쓰기 액세스를 제공합니다. URLSearchParams 클래스는 다음 네 가지 생성자 중 하나를 사용하여 독립적으로 사용할 수도 있습니다. URLSearchParams 클래스는 전역 객체에서도 사용할 수 있습니다.

WHATWG URLSearchParams 인터페이스와 querystring 모듈은 목적이 비슷하지만, querystring 모듈은 구분 기호 문자(& 및 =)를 사용자 지정할 수 있으므로 더 일반적인 목적을 가집니다. 반면에 이 API는 URL 쿼리 문자열만을 위해 설계되었습니다.

js
const myURL = new URL('https://example.org/?abc=123')
console.log(myURL.searchParams.get('abc'))
// 123을 출력합니다.

myURL.searchParams.append('abc', 'xyz')
console.log(myURL.href)
// https://example.org/?abc=123&abc=xyz를 출력합니다.

myURL.searchParams.delete('abc')
myURL.searchParams.set('a', 'b')
console.log(myURL.href)
// https://example.org/?a=b를 출력합니다.

const newSearchParams = new URLSearchParams(myURL.searchParams)
// 위는 다음 구문과 동일합니다.
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c')
console.log(myURL.href)
// https://example.org/?a=b를 출력합니다.
console.log(newSearchParams.toString())
// a=b&a=c를 출력합니다.

// newSearchParams.toString()이 암시적으로 호출됩니다.
myURL.search = newSearchParams
console.log(myURL.href)
// https://example.org/?a=b&a=c를 출력합니다.
newSearchParams.delete('a')
console.log(myURL.href)
// https://example.org/?a=b&a=c를 출력합니다.

new URLSearchParams() ​

새로운 빈 URLSearchParams 객체를 인스턴스화합니다.

new URLSearchParams(string) ​

string을 쿼리 문자열로 구문 분석하고 새 URLSearchParams 객체를 인스턴스화하는 데 사용합니다. 선행 '?'가 있으면 무시됩니다.

js
let params

params = new URLSearchParams('user=abc&query=xyz')
console.log(params.get('user'))
// 'abc'를 출력합니다.
console.log(params.toString())
// 'user=abc&query=xyz'를 출력합니다.

params = new URLSearchParams('?user=abc&query=xyz')
console.log(params.toString())
// 'user=abc&query=xyz'를 출력합니다.

new URLSearchParams(obj) ​

Added in: v7.10.0, v6.13.0

  • obj <Object> 키-값 쌍의 컬렉션을 나타내는 객체

쿼리 해시 맵을 사용하여 새로운 URLSearchParams 객체를 인스턴스화합니다. obj의 각 속성의 키와 값은 항상 문자열로 강제 변환됩니다.

querystring 모듈과 달리, 배열 값 형태의 중복 키는 허용되지 않습니다. 배열은 array.toString()을 사용하여 문자열화되는데, 이는 단순히 모든 배열 요소를 쉼표로 결합합니다.

js
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'

new URLSearchParams(iterable) ​

Added in: v7.10.0, v6.13.0

  • iterable <Iterable> 요소가 키-값 쌍인 반복 가능한 객체

Map의 생성자와 유사한 방식으로 반복 가능한 맵을 사용하여 새로운 URLSearchParams 객체를 인스턴스화합니다. iterable은 Array 또는 임의의 반복 가능한 객체일 수 있습니다. 즉, iterable은 다른 URLSearchParams일 수도 있으며, 이 경우 생성자는 제공된 URLSearchParams의 복사본을 생성합니다. iterable의 요소는 키-값 쌍이며, 그 자체로 임의의 반복 가능한 객체일 수 있습니다.

중복 키는 허용됩니다.

js
let params

// 배열 사용
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
])
console.log(params.toString())
// Prints 'user=abc&query=first&query=second'

// Map 객체 사용
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'

// 생성기 함수 사용
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'

// 각 키-값 쌍은 정확히 두 개의 요소를 가져야 합니다.
new URLSearchParams([['user', 'abc', 'error']])
// Throws TypeError [ERR_INVALID_TUPLE]:
//        각 쿼리 쌍은 반복 가능한 [name, value] 튜플이어야 합니다.

urlSearchParams.append(name, value) ​

새로운 이름-값 쌍을 쿼리 문자열에 추가합니다.

urlSearchParams.delete(name[, value]) ​

[기록]

버전변경 사항
v20.2.0, v18.18.0선택적 value 인수에 대한 지원을 추가합니다.

value가 제공되면 이름이 name이고 값이 value인 모든 이름-값 쌍을 제거합니다.

value가 제공되지 않으면 이름이 name인 모든 이름-값 쌍을 제거합니다.

urlSearchParams.entries() ​

쿼리에서 각 이름-값 쌍에 대한 ES6 Iterator를 반환합니다. 이터레이터의 각 항목은 JavaScript Array입니다. Array의 첫 번째 항목은 name이고 Array의 두 번째 항목은 value입니다.

urlSearchParams[@@iterator]()의 별칭입니다.

urlSearchParams.forEach(fn[, thisArg]) ​

[기록]

버전변경 사항
v18.0.0fn 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE이(가) 발생합니다.
  • fn <Function> 쿼리의 각 이름-값 쌍에 대해 호출됩니다.
  • thisArg <Object> fn이(가) 호출될 때 this 값으로 사용됩니다.

쿼리의 각 이름-값 쌍을 반복하고 주어진 함수를 호출합니다.

js
const myURL = new URL('https://example.org/?a=b&c=d')
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams)
})
// 출력:
//   a b true
//   c d true

urlSearchParams.get(name) ​

  • name <string>
  • 반환 값: <string> | <null> 주어진 name과 일치하는 이름-값 쌍이 없으면 문자열 또는 null을 반환합니다.

이름이 name인 첫 번째 이름-값 쌍의 값을 반환합니다. 그러한 쌍이 없으면 null이 반환됩니다.

urlSearchParams.getAll(name) ​

이름이 name인 모든 이름-값 쌍의 값을 반환합니다. 그러한 쌍이 없으면 빈 배열이 반환됩니다.

urlSearchParams.has(name[, value]) ​

[기록]

버전변경 사항
v20.2.0, v18.18.0선택적 value 인수 지원 추가.

name과 선택적 value 인수를 기반으로 URLSearchParams 객체에 키-값 쌍이 있는지 확인합니다.

value가 제공되면 동일한 name 및 value를 가진 이름-값 쌍이 존재할 때 true를 반환합니다.

value가 제공되지 않으면 이름이 name인 이름-값 쌍이 하나 이상 있으면 true를 반환합니다.

urlSearchParams.keys() ​

각 이름-값 쌍의 이름에 대한 ES6 Iterator를 반환합니다.

js
const params = new URLSearchParams('foo=bar&foo=baz')
for (const name of params.keys()) {
  console.log(name)
}
// 출력:
//   foo
//   foo

urlSearchParams.set(name, value) ​

name과 연결된 URLSearchParams 객체의 값을 value로 설정합니다. name이 이름인 기존 이름-값 쌍이 있는 경우, 첫 번째 쌍의 값을 value로 설정하고 다른 모든 쌍을 제거합니다. 그렇지 않으면 이름-값 쌍을 쿼리 문자열에 추가합니다.

js
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

urlSearchParams.size ​

Added in: v19.8.0, v18.16.0

총 매개변수 항목 수입니다.

urlSearchParams.sort() ​

Added in: v7.7.0, v6.13.0

기존의 모든 이름-값 쌍을 이름으로 제자리에서 정렬합니다. 정렬은 안정적인 정렬 알고리즘으로 수행되므로 동일한 이름을 가진 이름-값 쌍 사이의 상대적 순서가 유지됩니다.

이 메서드는 특히 캐시 히트를 늘리는 데 사용할 수 있습니다.

js
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

urlSearchParams.toString() ​

필요한 경우 문자를 퍼센트 인코딩하여 직렬화된 검색 매개변수를 문자열로 반환합니다.

urlSearchParams.values() ​

각 이름-값 쌍의 값에 대한 ES6 Iterator를 반환합니다.

urlSearchParams[Symbol.iterator]() ​

쿼리 문자열에 있는 각 이름-값 쌍에 대한 ES6 Iterator를 반환합니다. 이터레이터의 각 항목은 JavaScript Array입니다. Array의 첫 번째 항목은 name이고, 두 번째 항목은 value입니다.

urlSearchParams.entries()의 별칭입니다.

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

url.domainToASCII(domain) ​

[기록]

버전변경 사항
v20.0.0, v18.17.0ICU 요구 사항이 제거되었습니다.
v7.4.0, v6.13.0추가됨: v7.4.0, v6.13.0

domain의 퓨니코드 ASCII 직렬화를 반환합니다. domain이 유효하지 않은 도메인인 경우 빈 문자열이 반환됩니다.

url.domainToUnicode()의 반대 작업을 수행합니다.

js
import url from 'node:url'

console.log(url.domainToASCII('español.com'))
// 출력 xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// 출력 xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// 빈 문자열을 출력합니다
js
const url = require('node:url')

console.log(url.domainToASCII('español.com'))
// 출력 xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// 출력 xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// 빈 문자열을 출력합니다

url.domainToUnicode(domain) ​

[기록]

버전변경 사항
v20.0.0, v18.17.0ICU 요구 사항이 제거되었습니다.
v7.4.0, v6.13.0추가됨: v7.4.0, v6.13.0

domain의 유니코드 직렬화를 반환합니다. domain이 유효하지 않은 도메인인 경우 빈 문자열이 반환됩니다.

url.domainToASCII()의 반대 작업을 수행합니다.

js
import url from 'node:url'

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// 출력 español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// 출력 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// 빈 문자열을 출력합니다
js
const url = require('node:url')

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// 출력 español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// 출력 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// 빈 문자열을 출력합니다

url.fileURLToPath(url[, options]) ​

[History]

버전변경 사항
v22.1.0, v20.13.0이제 options 인수를 사용하여 path 인수를 구문 분석하는 방법을 결정할 수 있습니다.
v10.12.0v10.12.0에 추가됨

  • url <URL> | <string> 경로로 변환할 파일 URL 문자열 또는 URL 객체입니다.

  • options <Object>

    • windows <boolean> | <undefined> path를 windows 파일 경로로 반환해야 하는 경우 true, posix의 경우 false, 시스템 기본값의 경우 undefined입니다. 기본값: undefined.

  • 반환값: <string> 완전히 확인된 플랫폼별 Node.js 파일 경로입니다.

이 함수는 퍼센트 인코딩된 문자의 올바른 디코딩을 보장할 뿐만 아니라 플랫폼 간 유효한 절대 경로 문자열을 보장합니다.

js
import { fileURLToPath } from 'node:url'

const __filename = fileURLToPath(import.meta.url)

new URL('file:///C:/path/').pathname // 잘못됨: /C:/path/
fileURLToPath('file:///C:/path/') // 올바름:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // 잘못됨: /foo.txt
fileURLToPath('file://nas/foo.txt') // 올바름:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // 잘못됨: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // 올바름:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // 잘못됨: /hello%20world
fileURLToPath('file:///hello world') // 올바름:   /hello world (POSIX)
js
const { fileURLToPath } = require('node:url')
new URL('file:///C:/path/').pathname // 잘못됨: /C:/path/
fileURLToPath('file:///C:/path/') // 올바름:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // 잘못됨: /foo.txt
fileURLToPath('file://nas/foo.txt') // 올바름:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // 잘못됨: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // 올바름:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // 잘못됨: /hello%20world
fileURLToPath('file:///hello world') // 올바름:   /hello world (POSIX)

url.format(URL[, options]) ​

추가된 버전: v7.6.0

  • URL <URL> WHATWG URL 객체

  • options <Object>

    • auth <boolean> 직렬화된 URL 문자열에 사용자 이름과 암호를 포함해야 하는 경우 true, 그렇지 않은 경우 false. 기본값: true.
    • fragment <boolean> 직렬화된 URL 문자열에 프래그먼트를 포함해야 하는 경우 true, 그렇지 않은 경우 false. 기본값: true.
    • search <boolean> 직렬화된 URL 문자열에 검색 쿼리를 포함해야 하는 경우 true, 그렇지 않은 경우 false. 기본값: true.
    • unicode <boolean> URL 문자열의 호스트 구성 요소에 나타나는 유니코드 문자를 Punycode로 인코딩하는 대신 직접 인코딩해야 하는 경우 true. 기본값: false.

  • 반환값: <string>

WHATWG URL 객체의 URL String 표현의 사용자 정의 가능한 직렬화를 반환합니다.

URL 객체에는 URL의 문자열 직렬화를 반환하는 toString() 메서드와 href 속성이 모두 있습니다. 그러나 이러한 속성은 어떤 방식으로든 사용자 정의할 수 없습니다. url.format(URL[, options]) 메서드를 사용하면 출력에 대한 기본 사용자 정의가 가능합니다.

js
import url from 'node:url'
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// 출력: https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString())
// 출력: https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// 출력: 'https://測試/?abc'
js
const url = require('node:url')
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// 출력: https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString())
// 출력: https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// 출력: 'https://測試/?abc'

url.pathToFileURL(path[, options]) ​

[History]

VersionChanges
v22.1.0, v20.13.0이제 options 인수를 사용하여 path 값을 반환하는 방법을 결정할 수 있습니다.
v10.12.0v10.12.0에 추가됨

  • path <string> 파일 URL로 변환할 경로입니다.

  • options <Object>

    • windows <boolean> | <undefined> path를 Windows 파일 경로로 처리해야 하는 경우 true, posix의 경우 false, 시스템 기본값의 경우 undefined입니다. 기본값: undefined.

  • 반환: <URL> 파일 URL 객체입니다.

이 함수는 path가 절대적으로 해결되고 파일 URL로 변환할 때 URL 제어 문자가 올바르게 인코딩되도록 합니다.

js
import { pathToFileURL } from 'node:url'

new URL('/foo#1', 'file:') // 잘못됨: file:///foo#1
pathToFileURL('/foo#1') // 올바름:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // 잘못됨: file:///some/path%.c
pathToFileURL('/some/path%.c') // 올바름:   file:///some/path%25.c (POSIX)
js
const { pathToFileURL } = require('node:url')
new URL(__filename) // 잘못됨: (POSIX)에서 오류 발생
new URL(__filename) // 잘못됨: C:\... (Windows)
pathToFileURL(__filename) // 올바름:   file:///... (POSIX)
pathToFileURL(__filename) // 올바름:   file:///C:/... (Windows)

new URL('/foo#1', 'file:') // 잘못됨: file:///foo#1
pathToFileURL('/foo#1') // 올바름:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // 잘못됨: file:///some/path%.c
pathToFileURL('/some/path%.c') // 올바름:   file:///some/path%25.c (POSIX)

url.urlToHttpOptions(url) ​

[History]

버전변경 사항
v19.9.0, v18.17.0반환된 객체는 url 인수의 자체 열거 가능한 모든 속성도 포함합니다.
v15.7.0, v14.18.0추가됨: v15.7.0, v14.18.0
  • url <URL> 옵션 객체로 변환할 WHATWG URL 객체입니다.
  • 반환값: <Object> 옵션 객체
    • protocol <string> 사용할 프로토콜입니다.
    • hostname <string> 요청을 보낼 서버의 도메인 이름 또는 IP 주소입니다.
    • hash <string> URL의 프래그먼트 부분입니다.
    • search <string> URL의 직렬화된 쿼리 부분입니다.
    • pathname <string> URL의 경로 부분입니다.
    • path <string> 요청 경로입니다. 쿼리 문자열이 있는 경우 포함해야 합니다. 예: '/index.html?page=12'. 요청 경로에 유효하지 않은 문자가 포함된 경우 예외가 발생합니다. 현재 공백만 거부되지만 향후 변경될 수 있습니다.
    • href <string> 직렬화된 URL입니다.
    • port <number> 원격 서버의 포트입니다.
    • auth <string> 기본 인증, 즉 Authorization 헤더를 계산하기 위한 'user:password'입니다.

이 유틸리티 함수는 URL 객체를 http.request() 및 https.request() API에서 예상하는 일반 옵션 객체로 변환합니다.

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

레거시 URL API ​

[기록]

버전변경 사항
v15.13.0, v14.17.0폐지 철회. 상태가 "레거시"로 변경되었습니다.
v11.0.0이 API는 폐지되었습니다.

[안정: 3 - 레거시]

안정: 3 안정성: 3 - 레거시: 대신 WHATWG URL API를 사용하세요.

레거시 urlObject ​

[기록]

버전변경 사항
v15.13.0, v14.17.0폐지 철회. 상태가 "레거시"로 변경되었습니다.
v11.0.0레거시 URL API가 폐지되었습니다. WHATWG URL API를 사용하세요.

[안정: 3 - 레거시]

안정: 3 안정성: 3 - 레거시: 대신 WHATWG URL API를 사용하세요.

레거시 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 속성은 지정된 경우 port를 포함하여 URL의 전체 소문자 호스트 부분입니다.

예: 'sub.example.com:8080'.

urlObject.hostname ​

hostname 속성은 port를 포함 하지 않는 host 구성 요소의 소문자 호스트 이름 부분입니다.

예: '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 속성은 앞의 ASCII 물음표(?) 문자를 포함하여 URL의 전체 "쿼리 문자열" 부분으로 구성됩니다.

예: '?query=string'.

쿼리 문자열의 디코딩은 수행되지 않습니다.

urlObject.slashes ​

slashes 속성은 protocol에서 콜론 뒤에 두 개의 ASCII 슬래시 문자(//)가 필요한 경우 true 값을 갖는 boolean입니다.

url.format(urlObject) ​

[기록]

버전변경 사항
v17.0.0호스트 이름의 Punycode 변환으로 인해 URL이 다르게 재분석될 수 있는 변경 사항이 발생하는 경우 이제 ERR_INVALID_URL 예외를 throw합니다.
v15.13.0, v14.17.0더 이상 사용되지 않는 상태가 취소되었습니다. 상태가 "레거시"로 변경되었습니다.
v11.0.0레거시 URL API는 더 이상 사용되지 않습니다. WHATWG URL API를 사용하세요.
v7.0.0file: 체계의 URL은 이제 slashes 옵션에 관계없이 항상 올바른 슬래시 수를 사용합니다. 프로토콜이 없는 거짓 slashes 옵션도 이제 항상 준수됩니다.
v0.1.25v0.1.25에 추가됨

[안정적: 3 - 레거시]

안정적: 3 안정성: 3 - 레거시: 대신 WHATWG URL API를 사용하세요.

  • urlObject <Object> | <string> URL 객체( url.parse()에서 반환되거나 다른 방법으로 구성됨). 문자열인 경우 url.parse()에 전달하여 객체로 변환됩니다.

url.format() 메서드는 urlObject에서 파생된 형식이 지정된 URL 문자열을 반환합니다.

js
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'

urlObject가 객체 또는 문자열이 아닌 경우 url.format()은 TypeError를 throw합니다.

형식 지정 프로세스는 다음과 같이 작동합니다.

  • 새 빈 문자열 result가 생성됩니다.

  • urlObject.protocol이 문자열인 경우 있는 그대로 result에 추가됩니다.

  • 그렇지 않고 urlObject.protocol이 undefined가 아니고 문자열이 아니면 Error가 throw됩니다.

  • ASCII 콜론(:) 문자로 끝나지 않는 urlObject.protocol의 모든 문자열 값의 경우 리터럴 문자열 :이 result에 추가됩니다.

  • 다음 조건 중 하나라도 참이면 리터럴 문자열 //가 result에 추가됩니다.

    • urlObject.slashes 속성이 true입니다.
    • urlObject.protocol이 http, https, ftp, gopher 또는 file로 시작합니다.

  • urlObject.auth 속성의 값이 true이고 urlObject.host 또는 urlObject.hostname이 undefined가 아닌 경우 urlObject.auth의 값이 문자열로 강제 변환되고 리터럴 문자열 @ 뒤에 result에 추가됩니다.

  • urlObject.host 속성이 undefined이면 다음이 발생합니다.

    • urlObject.hostname이 문자열이면 result에 추가됩니다.
    • 그렇지 않고 urlObject.hostname이 undefined가 아니고 문자열이 아니면 Error가 throw됩니다.
    • urlObject.port 속성 값이 true이고 urlObject.hostname이 undefined가 아니면 다음이 발생합니다.
    • 리터럴 문자열 :이 result에 추가되고,
    • urlObject.port의 값이 문자열로 강제 변환되어 result에 추가됩니다.

  • 그렇지 않고 urlObject.host 속성 값이 true이면 urlObject.host의 값이 문자열로 강제 변환되어 result에 추가됩니다.

  • urlObject.pathname 속성이 빈 문자열이 아닌 문자열이면 다음이 발생합니다.

    • urlObject.pathname이 ASCII 슬래시(/)로 시작하지 않는 경우 리터럴 문자열 '/'이 result에 추가됩니다.
    • urlObject.pathname의 값이 result에 추가됩니다.

  • 그렇지 않고 urlObject.pathname이 undefined가 아니고 문자열이 아니면 Error가 throw됩니다.

  • urlObject.search 속성이 undefined이고 urlObject.query 속성이 Object이면 리터럴 문자열 ?가 result에 추가된 다음 urlObject.query 값을 전달하는 querystring 모듈의 stringify() 메서드를 호출한 출력이 추가됩니다.

  • 그렇지 않고 urlObject.search가 문자열이면 다음이 발생합니다.

    • urlObject.search의 값이 ASCII 물음표(?) 문자로 시작하지 않는 경우 리터럴 문자열 ?가 result에 추가됩니다.
    • urlObject.search의 값이 result에 추가됩니다.

  • 그렇지 않고 urlObject.search가 undefined가 아니고 문자열이 아니면 Error가 throw됩니다.

  • urlObject.hash 속성이 문자열이면 다음이 발생합니다.

    • urlObject.hash의 값이 ASCII 해시(#) 문자로 시작하지 않는 경우 리터럴 문자열 #이 result에 추가됩니다.
    • urlObject.hash의 값이 result에 추가됩니다.

  • 그렇지 않고 urlObject.hash 속성이 undefined가 아니고 문자열이 아니면 Error가 throw됩니다.

  • result가 반환됩니다.

url.parse(urlString[, parseQueryString[, slashesDenoteHost]]) ​

[기록]

버전변경 사항
v19.0.0, v18.13.0문서 전용 사용 중단.
v15.13.0, v14.17.0사용 중단 취소. 상태가 "레거시"로 변경되었습니다.
v11.14.0반환된 URL 객체의 pathname 속성이 경로가 없고 프로토콜 스키마가 ws: 또는 wss:인 경우 이제 /입니다.
v11.0.0레거시 URL API가 사용 중단되었습니다. WHATWG URL API를 사용하세요.
v9.0.0쿼리 문자열이 없는 경우 반환된 URL 객체의 search 속성이 이제 null입니다.
v0.1.25추가됨: v0.1.25

[안정성: 0 - 사용 중단됨]

안정성: 0 안정성: 0 - 사용 중단됨: 대신 WHATWG URL API를 사용하세요.

  • urlString <string> 구문 분석할 URL 문자열입니다.
  • parseQueryString <boolean> true이면 query 속성은 항상 querystring 모듈의 parse() 메서드에서 반환된 객체로 설정됩니다. false이면 반환된 URL 객체의 query 속성은 구문 분석되지 않고 디코딩되지 않은 문자열입니다. 기본값: 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 문자열을 구문 분석하기 위해 관대한 비표준 알고리즘을 사용합니다. 호스트 이름 스푸핑 및 사용자 이름과 암호의 잘못된 처리와 같은 보안 문제에 취약합니다. 신뢰할 수 없는 입력에 사용하지 마십시오. url.parse() 취약점에 대해서는 CVE가 발급되지 않습니다. 대신 WHATWG URL API를 사용하세요.

url.resolve(from, to) ​

[기록]

버전변경 사항
v15.13.0, v14.17.0더 이상 사용되지 않음이 취소되었습니다. 상태가 "레거시"로 변경되었습니다.
v11.0.0레거시 URL API는 더 이상 사용되지 않습니다. WHATWG URL API를 사용하세요.
v6.6.0from 및 to가 동일한 호스트를 참조하는 경우 auth 필드가 이제 그대로 유지됩니다.
v6.0.0to 매개변수에 호스트 이름이 포함된 경우 auth 필드가 이제 지워집니다.
v6.5.0, v4.6.2port 필드가 이제 올바르게 복사됩니다.
v0.1.25추가됨: v0.1.25

[안정됨: 3 - 레거시]

안정됨: 3 안정성: 3 - 레거시: 대신 WHATWG URL API를 사용하세요.

  • from <string> to가 상대 URL인 경우 사용할 기본 URL입니다.
  • to <string> 확인할 대상 URL입니다.

url.resolve() 메서드는 웹 브라우저가 앵커 태그를 해결하는 방식과 유사한 방식으로 기본 URL을 기준으로 대상 URL을 확인합니다.

js
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'

WHATWG URL API를 사용하여 동일한 결과를 얻으려면 다음과 같이 합니다.

js
function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'))
  if (resolvedUrl.protocol === 'resolve:') {
    // `from`은 상대 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'

URL의 퍼센트 인코딩 ​

URL은 특정 범위의 문자만 포함하도록 허용됩니다. 해당 범위 밖의 문자는 인코딩해야 합니다. 이러한 문자를 인코딩하는 방법과 인코딩할 문자는 전적으로 URL 구조 내에서 문자가 있는 위치에 따라 다릅니다.

레거시 API ​

레거시 API 내에서 URL 객체의 속성에서 공백(' ')과 다음 문자는 자동으로 이스케이프 처리됩니다.

text
< > " ` \r \n \t { } | \ ^ '

예를 들어, ASCII 공백 문자(' ')는 %20으로 인코딩됩니다. ASCII 슬래시(/) 문자는 %3C로 인코딩됩니다.

WHATWG API ​

WHATWG URL 표준은 레거시 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 (})가 포함됩니다.
  • 사용자 정보 인코딩 세트에는 경로 퍼센트 인코딩 세트와 코드 포인트 U+002F (/), U+003A (😃, U+003B (😉, U+003D (=), U+0040 (@), U+005B ([) ~ U+005E(^), U+007C (|)가 포함됩니다.

사용자 정보 퍼센트 인코딩 세트는 URL 내에 인코딩된 사용자 이름과 비밀번호에만 독점적으로 사용됩니다. 경로 퍼센트 인코딩 세트는 대부분의 URL 경로에 사용됩니다. 조각 퍼센트 인코딩 세트는 URL 조각에 사용됩니다. C0 제어 퍼센트 인코딩 세트는 특정 조건에서 호스트 및 경로에 사용되며, 다른 모든 경우에도 사용됩니다.

호스트 이름 내에 ASCII가 아닌 문자가 나타나면 호스트 이름은 Punycode 알고리즘을 사용하여 인코딩됩니다. 그러나 호스트 이름에 Punycode 인코딩된 문자와 퍼센트 인코딩된 문자가 모두 포함될 수 있습니다.

js
const myURL = new URL('https://%CF%80.example.com/foo')
console.log(myURL.href)
// https://xn--1xa.example.com/foo를 출력합니다.
console.log(myURL.origin)
// https://xn--1xa.example.com을 출력합니다.