GitHub Pages에서 한글 URL 문제 해결하기

블로그에서 한글로 된 태그가 걸린 글들을 보려고 태그를 클릭했는데, URL이 http://example.com/한글-태그로 이동해야 할 링크에서 404 페이지가 표시되는 상황이 발생했다.
아마 처음부터 동작하지 않았던 문제였겠지만, 지금까지 확인하지 못했던 것 같다.

문제 분석

URL의 한글을 제대로 인코딩하지 못해서 발생한 게 아닐까라는 생각에, JS의 encodeURIComponent와 decodeURIComponent를 사용해 한글 URL을 테스트했다.
테스트 결과, 개발 환경에서는 정상적으로 작동했기 때문에 프로덕션 환경에서도 괜찮을 것이라고 판단했으나, 프로덕션 환경에서는 여전히 문제가 발생했다.

혹시나 해서 다른 GitHub Pages 블로그들은 어떤지 확인해 보니 한글 URL이 잘 동작하는 것을 확인할 수 있었다.
이를 통해 한글 URL 자체의 문제가 아닌, 본인 블로그의 URL 처리 방식에 문제가 있었음을 알게 되었다.
그래서 태그와 URL을 생성하는 기존의 slugify 함수를 GitHub의 URL 생성 방식에 맞게 수정해야겠다고 생각이 들었다.

문제 해결

검색 과정 끝에 github-slugger라는 라이브러리를 발견했다.
기존의 slugify 함수는 한글 문자열을 URL-safe 포맷으로 변환하지 못했지만, github-slugger는 유니코드 문자열도 처리 가능한 GitHub 스타일의 슬러그를 생성한다.
이를 기존 코드에 적용한 후 문제를 해결할 수 있었다.

import { slug } from 'github-slugger';

export function slugify(input?: string) {
  if (!input) return '';

  return slug(input.trim());
}

결론

이번 경험을 통해 URL 경로에 비 ASCII 문자(특히 한글)가 포함될 경우, 적절한 슬러그 생성 방식의 선택이 중요하다는 점을 배웠다.
앞으로는 개발 단계에서 이런 문제를 미리 테스트하며, 배포 전에 다국어 지원과 관련된 검증을 철저히 해야겠다고 다짐했다.