카카오톡으로 보낸 링크가 한글 부분만 %EA%B2%80%EC%83%89 같은 문자열로 바뀌어 있다. 깨진 게 아니라 URL 인코딩이 된 것인데, 브라우저에서는 정상 작동한다. 다만 사람이 읽을 수 없어서 불편하고, API 연동 시에는 직접 인코딩/디코딩을 해야 할 때가 있다.
URL 인코딩이 필요한 이유
URL(웹 주소)에는 영문, 숫자, 일부 특수문자만 허용된다. 한글, 공백, &, = 같은 문자는 그대로 쓸 수 없어서 %XX 형태(퍼센트 인코딩)로 바꿔야 한다.
| 원래 문자 | 인코딩 결과 | 설명 |
|---|---|---|
| 공백 | %20 | 가장 흔한 변환 |
| 한 | %ED%95%9C | UTF-8 기준 3바이트 |
| & | %26 | 파라미터 구분자와 혼동 방지 |
| = | %3D | 값 할당 기호와 혼동 방지 |
| # | %23 | 앵커 태그와 혼동 방지 |
encodeURI와 encodeURIComponent의 차이
웹 개발에서 두 함수를 혼동하면 버그가 생긴다. 차이를 알아두면 어떤 상황에서 어떤 걸 쓸지 바로 판단할 수 있다.
- encodeURI
- URL 전체를 인코딩할 때 쓴다.
:, /, ?, &, =같은 URL 구조 문자는 변환하지 않는다. 완성된 URL에 한글만 인코딩하고 싶을 때 적합하다. - encodeURIComponent
- URL의 일부(쿼리 파라미터 값)를 인코딩할 때 쓴다.
&, =까지 전부 변환한다. 검색어나 사용자 입력값을 파라미터로 넘길 때 필수다.
예시
encodeURI:https://example.com/검색?q=테스트→https://example.com/%EA%B2%80%EC%83%89?q=%ED%85%8C%EC%8A%A4%ED%8A%B8
encodeURIComponent:테스트&값→%ED%85%8C%EC%8A%A4%ED%8A%B8%26%EA%B0%92(&도 변환됨)
URL 인코딩/디코딩하는 법
URL 인코딩 변환기에 텍스트를 붙여넣으면 인코딩과 디코딩을 바로 처리할 수 있다. encodeURIComponent 옵션 체크박스가 있어서 용도에 맞게 전환할 수 있고, 입력과 동시에 결과가 나온다.
- 인코딩: 한글이 포함된 URL을 API에 넘기기 전에 변환
- 디코딩: 로그 파일이나 서버 응답에서 %XX로 된 URL을 읽을 수 있는 형태로 복원
자주 겪는 문제와 해결법
- 이중 인코딩: 이미 인코딩된 URL을 한 번 더 인코딩하면 %25EC 같은 형태가 된다. %가 %25로 다시 변환되는 것이다. 인코딩 전에 이미 변환됐는지 확인하자.
- 한글 깨짐: 서버와 클라이언트의 문자 인코딩이 다를 때 발생한다. UTF-8로 통일하면 대부분 해결된다.
- + vs %20: 일부 시스템에서 공백을 +로 표기한다(application/x-www-form-urlencoded). 표준 URL 인코딩은 %20이다.
URL에 특수문자나 한글이 들어가는 순간 인코딩은 피할 수 없다. 원리를 알면 디버깅 시간이 줄어든다.