URL 인코딩·디코딩

URL에 직접 사용할 수 없는 문자(한글·공백·특수문자)를 %와 16진수 조합으로 바꾸는 방식입니다. 퍼센트 인코딩이라고도 합니다. 예를 들어 "한글"은 %ED%95%9C%EA%B8%80로 바뀝니다. 브라우저가 URL을 서버에 전송할 때 자동으로 처리하지만, 개발·SEO 작업에서는 직접 변환할 일이 자주 있습니다.

encodeURI는 URL 전체를 인코딩하며 : / ? # & = 같은 구조 문자는 그대로 둡니다. encodeURIComponent는 URL의 일부(컴포넌트)를 인코딩하며 구조 문자까지 모두 변환합니다. 전체 URL 변환에는 encodeURI를, 쿼리 파라미터 값처럼 URL 조각에는 encodeURIComponent를 사용하세요.

encodeURIComponent를 사용하세요. 파라미터 값에 들어간 &나 =가 구분자로 오해받지 않도록 %26, %3D로 바꿔야 합니다. encodeURI를 쓰면 &가 그대로 남아서 파라미터가 둘로 쪼개지는 버그가 생깁니다.

한글은 UTF-8에서 1글자당 3바이트를 차지하고, 각 바이트가 %XX 형태로 인코딩되기 때문입니다. "한"은 ED 95 9C 3바이트라서 %ED%95%9C이 됩니다. 정상적인 인코딩이니 걱정하지 마세요.

% 뒤에 16진수 2자리가 오지 않는 잘못된 형식(예: %ZZ, %E 단독)이거나, 이중 인코딩된 문자열(%25ED…)일 가능성이 큽니다. 입력 끝부분의 %를 먼저 확인하고, %25가 보인다면 한 번 디코딩한 뒤 다시 시도해 보세요.

이미 인코딩된 문자열을 또 인코딩해서 %가 %25로 바뀌는 현상입니다. 서버에서 한글이 %ED… 형태 그대로 보이거나 깨진다면 이중 인코딩을 의심해 보세요. 디코딩으로 원래 문자열을 복원한 뒤 필요한 만큼만 다시 인코딩하면 해결됩니다.

escape()는 구형 비표준 함수로 한글을 %uD55C 같은 형태로 바꿔서 서버가 해석하지 못합니다. 지금은 encodeURI/encodeURIComponent를 사용하는 것이 표준이며, 이 도구도 표준 방식만 제공합니다.

URL 경로에서는 %20을, form 전송 방식에서는 +를 쓰는 것이 관례입니다. 요즘은 대부분 %20으로 통일해도 문제없지만, 서버가 +를 공백으로 해석하지 않는 경우도 있으니 API 문서를 확인하는 것이 안전합니다.

한글 도메인은 실제로 퓨니코드(punycode)라는 ASCII 형태로 변환되어 동작합니다. 브라우저 주소창에는 한글로 보이지만 내부적으로는 xn--로 시작하는 형태로 바뀝니다. 링크를 공유할 때는 브라우저에 표시되는 한글 주소를 그대로 복사해도 됩니다.

메신저 앱이 긴 URL을 잘라내거나 % 문자를 변형하면서 링크가 깨지는 경우가 있습니다. 이럴 때는 URL을 먼저 디코딩해 정상 형태인지 확인하고, 그래도 안 되면 URL 단축 서비스를 이용해 짧게 줄여서 보내는 것이 좋습니다.

POST로 데이터를 보내도 URL에 포함되는 부분은 인코딩이 필요합니다. 쿼리 스트링에 한글을 붙여 POST 요청을 보내면 마찬가지로 깨질 수 있습니다. 다만 요청 본문에 담는 데이터는 Content-Type에 따라 브라우저가 알아서 처리하므로 직접 인코딩할 필요가 없습니다. 헷갈린다면 URL에 들어가는 값은 항상 인코딩한다는 원칙을 기억하세요.