URL 인코딩: 쿼리 파라미터와 경로를 퍼센트 인코드하기

퍼센트 인코딩은 안전하지 않은 문자를 %XX로 바꿔 임의의 텍스트가 URL 안에서 안전하도록 만듭니다. 어떤 문자를 이스케이프하고 어떻게 되돌리는지 알아두세요.

퍼센트 인코딩이란

URL에 허용되지 않는 문자는 퍼센트 기호와 두 자리 16진수로 치환됩니다. 공백은 %20, 앰퍼샌드는 %26이 됩니다.

encodeURIComponent와 encodeURI

단일 쿼리 값이나 경로 세그먼트에는 encodeURIComponent를 사용하세요 — /, ?, &, =를 이스케이프합니다. 전체 URL에 대해서는 encodeURI만 사용하세요. 그 문자들은 거기서는 구조적이며 그대로 살아남아야 합니다.

+와 %20의 함정

쿼리 문자열에서 공백은 +(폼 인코딩) 또는 %20으로 나타날 수 있습니다. decodeURIComponent는 +를 공백으로 바꾸지 않으니, 폼 인코딩 데이터를 디코딩하기 전에 +를 먼저 치환하세요.

이중 인코딩

이미 인코딩된 문자열을 다시 인코딩하면 %20이 %2520이 됩니다. 출력에 %25 시퀀스가 보인다면 그 값은 두 번 인코딩된 것이니, 더 이상 바뀌지 않을 때까지 반복적으로 디코딩하세요.

예약 문자와 비예약 문자

RFC 3986은 URL 문자를 예약(gen-delims: 와 같은 :, /, ?, #, sub-delims: 와 같은 &, =)과 비예약(글자, 숫자, -, ., _, ~)으로 나눕니다. 비예약 문자는 절대로 인코딩이 필요하지 않습니다. 예약 문자는 URL 구조가 아니라 값 안에 등장할 때만 인코딩이 필요합니다.

전체 URL 인코딩과 단일 값 인코딩

encodeURI는 전체 URL용입니다: :, /, ?, #, &, =를 그대로 두어 URL 형태를 유지합니다. encodeURIComponent는 경로 세그먼트나 쿼리 파라미터에 들어갈 단일 값용입니다 — 그 구조 문자들을 이스케이프해서 값이 자기 자리를 벗어나지 못하게 합니다.

코드로 안전한 쿼리 문자열 만들기

문자열 연결보다 URLSearchParams(브라우저) 또는 url.URLSearchParams(Node)를 우선 사용하세요. 두 API 모두 키와 값을 올바르게 인코딩하고, 다중 값 파라미터를 다루며, 가장 흔한 실수 — &나 =를 포함한 파라미터를 인코딩하지 않는 것 — 를 피하게 해 줍니다.

Open JSON Fix Compare JSON changes