잘못된 퍼센트 인코딩 UTF-8을 해결하는 방법
URL 값이 앱에 도착했는데 decodeURIComponent()가 URIError를 냅니다. 기호를 바꾸기 전에 두 문제를 구분하세요. 퍼센트 이스케이프 자체가 불완전한 경우와, 바이트 표기는 완전하지만 유효한 UTF-8이 아닌 경우입니다.
값이 바뀌는 경계를 찾으세요
검색창에서 50% off를 입력할 수 있지만 생성된 링크를 열면 페이지가 멈춘다고 해 보겠습니다. 검색창의 퍼센트 기호는 일반 텍스트입니다. 코드가 이미 인코딩된 URL 구성요소로 다룰 때 특별한 의미가 생깁니다. 사용자 텍스트, 직렬화된 URL, 받는 페이지에서 읽은 값이 각각 무엇이어야 하는지 적어 보세요. 지울 기호를 찾는 것이 아니라 인코딩 계약의 불일치를 찾는 작업입니다.
실제 비밀번호 재설정 링크나 고객 검색어를 콘솔·공개 이슈에 복사하지 말고 무해한 예시를 사용하세요. 먼저 decodeURIComponent("%25")를 시험하면 퍼센트 기호 하나가 나와야 합니다. 다음으로 아래의 오류 처리 함수를 사용해 실패 예시를 시험하세요. 정상 대조군은 되고 예시만 실패한다면 디코더 전체가 고장 난 것이 아니라 입력 자료를 조사해야 합니다.
잘못된 이스케이프와 잘못된 UTF-8은 다릅니다
%만 있으면 뒤에 두 자리 바이트 값이 없습니다. 반면 %92는 바이트 표기로는 맞지만 그 바이트 하나로 UTF-8 문자가 되지는 않습니다. 공개 사례에는 오래된 인코딩의 따옴표 바이트나 단독 %AF를 포함해 두 종류의 실수가 모두 나옵니다.
decodeURIComponent("%"); // URIError
decodeURIComponent("%92"); // URIError
decodeURIComponent("%25"); // %
decodeURIComponent("%C2%AF"); // ¯
decodeURIComponent("%E2%80%99"); // ’
보존된 Node v24.19.0 시험은 이 결과를 재현했고 %91, %AF, UTF-8 왼쪽 따옴표도 시험했습니다. 브라우저 오류 문구는 다를 수 있습니다. 정확한 입력이 성공했는지 거부됐는지가 유용한 증거입니다.
퍼센트 기호를 직접 이어 붙이지 말고 URL API를 쓰세요
새 링크를 만들 때는 원래 텍스트를 URL API에 전달해 매개변수 직렬화를 맡기세요. 받는 쪽도 같은 API로 값을 읽습니다. 반환된 값을 바로 한 번 더 디코딩하면 안 됩니다.
const link = new URL("https://example.com/search");
link.searchParams.set("q", "50% off & café");
const received = new URL(link.href).searchParams.get("q");
console.log(received); // 50% off & café
예시 URL이며 FrAIFlow의 실제 엔드포인트는 아닙니다. 핵심은 인코딩된 구성요소와 이미 파싱된 값을 구분하는 것입니다. 두 번째 디코딩은 50% off 같은 정상 텍스트도 오류로 만들 수 있습니다. 폼 방식 쿼리 매개변수의 더하기 기호는 decodeURIComponent()에 직접 전달한 더하기 기호와 처리 방식이 다릅니다. 형식에 맞는 파서를 사용하세요.
문자를 추측하지 말고 생성하는 쪽을 고치세요
실패한 예시는 비공개로 정확히 보관하고 만든 쪽에 어떤 문자 인코딩을 사용했는지 물어보세요. 단독 %92가 오래된 바이트 규칙을 암시할 수는 있지만 바이트 하나로 출처를 확정할 수는 없습니다. 계정 ID·서명·파일 이름에서 작은따옴표로 조용히 치환하지 마세요. 도움이 되는 오류를 반환하고 사용자의 원래 입력을 보존하며 가능하면 원천 인코딩을 수정합니다.
변경 후에는 실제 퍼센트 기호, 악센트 단어, 곡선 따옴표, 더하기, 앰퍼샌드를 시험하세요. 링크 생성→열기→값 읽기를 모두 거쳐도 각 값이 같아야 합니다. 잘못된 입력은 페이지 전체를 중단하지 않고 통제된 오류로 처리돼야 합니다. 이는 형식 계약을 검증하는 것이지 읽을 만해질 때까지 반복 디코딩해도 된다는 뜻이 아닙니다.
잘못된 입력도 페이지 전체를 멈추지 않게 처리하세요
function decodeComponent(value) {
try { return { ok: true, value: decodeURIComponent(value) }; }
catch (error) {
if (!(error instanceof URIError)) throw error;
return { ok: false, error: "Invalid encoded component" };
}
}
이 경계 처리는 식별자를 몰래 바꾸지 않고 실패를 알립니다. 알 수 없는 원본 인코딩까지 찾아 주지는 않습니다. 형식 계약이 요구하는 횟수만 디코딩하세요. 성공한 뒤 퍼센트 기호가 남았다는 이유로 한 번 더 읽지 마세요. 폐기된 unescape()를 UTF-8 해결책으로 쓰지 말고 토큰과 비공개 검색값을 공개 로그에서 제외하세요.
