·2분 읽기
URL 인코딩 한글 파라미터 깨짐 해결 — 실전 디버깅 5가지 패턴
URL에 한글 파라미터를 넣었더니 물음표나 %ED%9C 같은 문자로 깨지나요? 인코딩/디코딩 규칙부터 자주 만나는 5가지 깨짐 패턴과 해결법을 정리했어요.
🔗
URL 인코더/디코더 바로 사용하기
URL을 인코딩하거나 디코딩하세요
→
왜 한글 URL은 깨질까
URL 표준은 원래 ASCII만 허용해요. 한글 같은 비ASCII 문자는 **퍼센트 인코딩(UTF-8 바이트를 `%XX` 형태)**으로 변환해야 합니다.
예시: `안녕`은 UTF-8로 `0xEC 0x95 0x88 0xEB 0x85 0x95` → URL 인코딩 `%EC%95%88%EB%85%95`.
이 변환이 어딘가 빠지거나 두 번 걸리면 한글이 깨져요. 흔한 5가지 패턴을 정리했어요.
패턴 1 — 인코딩을 안 하고 붙여 넣음
가장 흔한 실수예요. `/search?q=안녕`을 그대로 fetch에 넣으면 브라우저마다 처리가 달라요. Firefox는 자동 인코딩해주지만, 백엔드가 `Content-Length`를 바이트로 파싱하면 길이 불일치로 끊깁니다.
해결: JavaScript는 `encodeURIComponent('안녕')`으로 감싸세요. Python은 `urllib.parse.quote('안녕')`.
패턴 2 — encodeURI와 encodeURIComponent 혼동
`encodeURI`는 URL 구조 문자(`/`, `?`, `=`, `&`)를 안 건드려요. 파라미터 값 안에 이런 문자가 있으면 깨집니다.
파라미터 값은 반드시 **`encodeURIComponent`**를 써요.
```js
const url = `/search?q=${encodeURIComponent(query)}`;
```
패턴 3 — 이중 인코딩
서버가 자동 디코딩하는데 프론트에서 `encodeURIComponent`를 두 번 돌린 경우예요. `%` 기호 자체가 `%25`로 한 번 더 인코딩되면서 `%2595%2588` 같은 쓰레기가 나옵니다.
해결: 인코딩은 한 번만. URL 작성 시점에 1회만 걸고 그 후엔 안 건드리세요.
패턴 4 — EUC-KR과 UTF-8 혼합
옛날 사이트(네이버 일부 페이지, 공공기관 사이트)가 EUC-KR을 쓰면 같은 `안녕`이 `%BE%C8%B3%E7`으로 인코딩돼요. UTF-8로 디코드하면 깨집니다.
해결: 상대 사이트 charset을 확인하고 맞는 인코딩 사용. Python은 `urllib.parse.quote(text.encode('euc-kr'))` 같이 명시적으로 지정하세요.
패턴 5 — 웹서버 자동 디코딩 차이
Nginx와 Node.js가 URL 디코딩 방식이 다른 경우가 있어요. Nginx는 한 번 자동 디코딩해서 넘기는데, Node.js(Express)는 또 디코딩을 시도할 수 있죠.
해결: 프록시 구성에서 `proxy_pass` 옵션 확인. `proxy_set_header Host $http_host` 같은 설정으로 원본 URL 보존하는 게 안전합니다.
디버깅 체크리스트
URL이 깨지면 이 순서로 확인해요.
1. 원본 문자열이 어떤 인코딩인가 (UTF-8? EUC-KR?)
2. 인코딩 몇 번 걸렸나 (`%` 두 개 이상 연속?)
3. 브라우저 주소창에서 복사하면 정상인가
4. 서버 로그에 찍힌 원본 쿼리는 어떻게 보이나
5. 프록시 설정이 URL 변환하고 있나
실전 코드 예시
JavaScript
```js
const keyword = '홍길동';
const url = `https://api.example.com/search?q=${encodeURIComponent(keyword)}`;
// https://api.example.com/search?q=%ED%99%8D%EA%B8%B8%EB%8F%99
```
Python
```python
from urllib.parse import quote
keyword = '홍길동'
url = f'https://api.example.com/search?q={quote(keyword)}'
```
Ruby
```ruby
require 'uri'
URI.encode_www_form_component('홍길동')
# => '%ED%99%8D%EA%B8%B8%EB%8F%99'
```
Toolkio URL Encoder 활용
Toolkio URL Encoder는 인코딩/디코딩을 양방향으로 즉시 보여줘요. 이중 인코딩 여부를 체크할 때 이게 가장 빠릅니다. 브라우저 내 처리라 민감 파라미터도 안심하고 테스트할 수 있어요.