문자열을 URL 인코딩하는 방법 (그리고 왜 중요한가)

URL에는 제한된 문자 집합만 담을 수 있습니다. 그래서 데이터에 공백, 앰퍼샌드, 물음표가 들어 있으면 링크에 그냥 넣을 수 없고 먼저 인코딩해야 합니다. URL 인코딩(퍼센트 인코딩이라고도 합니다)은 안전하지 않은 문자를 % 뒤에 16진수 코드를 붙인 형태로 바꿉니다. 공백은 %20, 앰퍼샌드는 %26이 되는 식입니다.

왜 중요한가

검색어 salt & pepper를 쿼리 문자열에 넣는다고 상상해 보세요: ?q=salt & pepper. 브라우저는 &를 새 매개변수의 시작으로, 공백을 URL의 끝으로 인식하므로 값이 산산조각 납니다. 이를 ?q=salt%20%26%20pepper로 퍼센트 인코딩하면 전체 구절이 하나의 값으로 온전히 유지됩니다. URL 인코더/디코더로 어떤 문자열이든 즉시 인코딩하거나 디코딩할 수 있습니다.

인코딩이 필요한 문자

문제를 일으키는 것은 URL에서 특별한 의미를 갖는 예약 문자들입니다:

• 공백 → %20 (쿼리 문자열에서는 때때로 +)
• & → %26 (매개변수를 구분)
• = → %3D (키에 값을 할당)
• ? → %3F (쿼리 문자열을 시작)
• # → %23 (프래그먼트를 시작)
• /, :, +, 그리고 악센트 문자나 이모지 같은 비 ASCII 문자도 값 안에서는 인코딩이 필요합니다.

encodeURIComponent vs encodeURI

JavaScript는 두 가지 함수를 제공하는데, 잘못 고르는 것이 가장 흔한 버그의 원인입니다:

• encodeURIComponent는 &, =, ?, /를 포함해 거의 모든 것을 인코딩합니다. URL의 한 조각 — 쿼리 매개변수 값 하나, 경로 세그먼트 하나 — 에 사용하세요.
• encodeURI는 이미 구조가 잡힌 전체 URL을 넘겨받는다고 가정하므로, &, =, ?, /, :는 일부러 건드리지 않습니다. 개별 값을 인코딩할 때가 아니라 오직 전체 URL을 정리할 때만 쓰세요.

경험칙: ?key=VALUE를 만들고 있다면 VALUE를 encodeURIComponent에 통과시키세요.

흔한 실수

• 매개변수 하나만 인코딩하려던 걸 전체 URL에 적용하기. https://site.com/?q=a b를 encodeURIComponent에 넣으면 https://의 ?가 %3A%2F%2F와 %3F로 뭉개져 작동하지 않는 링크가 됩니다. 값만 인코딩한 뒤 그 주위로 URL을 조립하세요.
• 이중 인코딩. 이미 인코딩된 문자열을 다시 인코딩하면 %20이 %2520이 됩니다 (% 자체가 인코딩됩니다). 공백이 리터럴 %2520으로 보인다면 두 번 인코딩한 것입니다 — URL 인코더/디코더로 한 번 디코딩해 복원하세요.
• base64나 HTML 엔티티와 혼동하기. 바이너리를 텍스트로 바꾸려면 Base64 인코더/디코더를, HTML에서 문자를 안전하게 표시하려면 HTML 엔티티 인코더를 쓰세요. URL 인코딩은 다른 문제 — 링크 안에서 데이터를 안전하게 만드는 것 — 를 풉니다.