카카오톡으로 링크를 보냈는데 상대방이 열어보니 404 에러가 뜬다. 주소를 자세히 보면 한글이 포함된 부분이 %EC%9D%B4... 같은 코드로 바뀌어 있고, 어딘가에서 잘려 있다. URL 인코딩 문제다.
왜 한글이 퍼센트 코드로 바뀌나
URL 표준(RFC 3986)은 영문 알파벳, 숫자, 일부 특수문자만 허용한다. 한글, 일본어, 공백 같은 문자는 URL에 직접 쓸 수 없어서 UTF-8 바이트 값을 %XX 형태로 변환해야 한다. 이 과정이 퍼센트 인코딩(URL 인코딩)이다.
- 인코딩 예시
- "한글" → %ED%95%9C%EA%B8%80 (한 글자가 3바이트씩 6바이트)
- 디코딩 예시
- %ED%95%9C%EA%B8%80 → "한글" (원래 문자로 복원)
인코딩 때문에 생기는 문제
- 링크 잘림: 메신저나 이메일에서 인코딩된 긴 URL이 중간에 끊어져 404가 발생한다
- 파라미터 깨짐: API 호출 시 쿼리스트링에 특수문자(&, =, ?)를 인코딩하지 않으면 파라미터가 제대로 전달되지 않는다
- 이중 인코딩: 이미 인코딩된 값을 다시 인코딩하면 %25ED 같은 이상한 코드가 나온다
encodeURI와 encodeURIComponent의 차이
| 함수 | 인코딩 대상 | 적합한 상황 |
|---|---|---|
| encodeURI | 한글, 공백 등 (:/? 등 URL 구조는 유지) | 전체 URL을 인코딩할 때 |
| encodeURIComponent | 모든 특수문자 포함 | 쿼리 파라미터 값을 인코딩할 때 |
API 호출에서 파라미터 값에 &나 =가 포함될 수 있다면 반드시 encodeURIComponent를 써야 한다. encodeURI는 이런 문자를 건드리지 않아서 파라미터 구분이 꼬일 수 있다.
빠르게 변환하는 법
코드를 쓸 수 없는 상황이거나, 인코딩된 URL을 사람이 읽을 수 있게 디코딩해야 할 때는 URL 인코딩 변환 도구가 편하다. 텍스트를 붙여넣으면 실시간으로 인코딩 또는 디코딩 결과가 나오고, encodeURI/encodeURIComponent 옵션도 선택할 수 있다. 입출력 크기 비교까지 표시되니 인코딩 후 URL 길이가 얼마나 늘어나는지도 바로 확인된다.
TIP 한글 URL을 메신저로 공유할 때 잘림 문제가 반복된다면, URL 단축 서비스를 먼저 거치는 게 가장 간단한 해결책이다.