개발
2026.09.22 · 2분
태그를 정리하면서 없어진 주소 36개에 308 리다이렉트를 깔았다. 배포 전에 로컬 프로덕션 빌드로 확인했는데, 절반만 동작했다.
/tags/nextjs → 308 /tags/Next.js
/tags/XSS → 308 /tags/%EB%B3%B4%EC%95%88
/tags/Node.js → 308 /tags/%EB%B3%B4%EC%95%88
/tags/텐트 → 200 ← 이게 문제
/tags/검색유입 → 200 ← 이것도
ASCII 로 된 태그는 전부 잡히고 한글만 빠졌다.
이 함정은 아무것도 실패하지 않아서 고약하다. 빌드가 통과한다. 타입 검사도 통과한다. 서버 로그에 아무것도 안 남는다. /tags/텐트 를 열면 페이지가 멀쩡하게 뜬다.
규칙이 36개인데 그중 14개만 안 먹으니, 규칙 자체가 틀렸다고 의심하기도 어렵다. ASCII 를 먼저 눌러 보면 "아 잘 되네" 하고 넘어간다. 실제로 나는 한글 태그를 확인 목록에 넣어 둔 덕에 잡았지, 안 넣었으면 그대로 배포했을 것이다.
공식 문서가 source 를 설명하는 문장은 한 줄이다.
sourceis the incoming request path pattern.
"들어오는 요청 경로" 라고만 하고 그게 인코딩된 형태인지 디코딩된 형태인지는 말하지 않는다. 문서 전체를 훑어도 encoding, percent-encoding, non-ASCII 를 언급하는 곳이 없다. 경로 매칭 규칙은 path-to-regexp 로 넘겨 버린다.
그래서 코드를 쓸 때 자연스럽게 이렇게 된다.
{ source: '/tags/텐트', destination: '/tags/캠핑', permanent: true }
읽기 좋고 표에 적힌 태그 이름을 그대로 옮긴 것이고 틀렸다.
들어오는 요청은 /tags/%ED%85%90%ED%8A%B8 다. 브라우저가 그렇게 보낸다. source 는 그 문자열과 맞으므로 여기에 한글 원문을 적으면 영원히 안 맞는다.
{
source: `/tags/${encodeURIComponent(from)}`,
destination: `/tags/${to}`,
permanent: true,
}
destination 은 인코딩하지 않는다. Next 가 Location 헤더를 만들 때 알아서 인코딩한다. 여기서 한 번 더 하면 %25ED%2585%2590... 이 되어 엉뚱한 주소로 간다.
한 함수 안에서 두 값을 다르게 다뤄야 한다는 것이 이 함정의 핵심이다. 대칭으로 보이는 자리라 같이 처리하고 싶어진다.
배포하고 나서 확인하면 늦다. 308 은 permanent: true 일 때 브라우저가 영구 캐시하므로, 잘못 깔면 되돌려도 이미 받은 사람은 계속 그리로 간다.
로컬 프로덕션 빌드에서 확인하는 게 싸다.
npm run build
npx next start -p 3100
for t in 텐트 검색유입 nextjs XSS; do
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" \
"http://127.0.0.1:3100/tags/$(python3 -c "
import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1]))" "$t")"
done
curl 에 인코딩된 주소를 주는 것이 중요하다. 셸에 한글을 그대로 넣으면 curl 이 알아서 인코딩해 주긴 하지만 브라우저가 보내는 것과 같은지 확신할 수 없다.
살아 있어야 하는 주소도 같이 눌러 본다. 리다이렉트만 확인하면 목적지가 같이 사라진 경우를 놓친다.
같은 실수를 다시 하지 않으려고 순수 함수로 빼고 테스트를 걸었다.
it('source 는 인코딩하고 destination 은 하지 않는다', () => {
expect(tagMergeRedirects({ 텐트: '캠핑' })).toEqual([
{ source: '/tags/%ED%85%90%ED%8A%B8',
destination: '/tags/캠핑', permanent: true },
])
})
퍼센트 인코딩된 문자열을 테스트에 박아 두는 게 처음엔 어색했는데, 이 경우엔 그게 맞다. 값이 아니라 형태가 계약이기 때문이다. encodeURIComponent 로 기대값을 만들면 구현과 같은 함수를 쓰게 되어 둘이 같이 틀려도 통과한다.
이 글은 AI 가 조사·초안을 작성하고 사람이 검수한 뒤 발행했습니다. 사실관계는 아래 출처에서 확인할 수 있습니다.