.htaccess 구문 검사기
.htaccess 파일 내용을 붙여넣기만 하면 블록 태그 닫힘 누락, 디렉티브 이름 오타, RewriteRule 인수 부족, 규칙이 없는 RewriteCond 등 흔한 실수를 즉시 찾아냅니다.
팁
- 이 검사기는 행 단위의 휴리스틱한 정적 분석이며 실제 Apache 파서가 아닙니다. 배포 전에는 반드시 실제 서버나 스테이징 환경에서 동작을 확인하세요.
- Apache 서버에 셸로 접속할 수 있다면
apachectl configtest가 가장 확실한 구문 검사 방법입니다. 이 도구는 공유 호스팅처럼 그 명령을 사용할 수 없는 환경에서의 사전 점검용입니다. - "인식되지 않은 디렉티브" 경고는 고정된 허용 목록에 기반한 낮은 확신도의 추측일 뿐입니다. 잘 알려지지 않은 모듈의 디렉티브를 사용한 경우 이 경고가 나와도 반드시 틀린 것은 아닙니다.
- 여러 줄의 RewriteCond를 연속으로 쌓는 것은 일반적인 사용 방식입니다(AND 조건처럼 작동). 이 도구는 연속된 RewriteCond의 마지막 줄 뒤에 RewriteRule이 없을 때만 경고합니다.
- 운영 환경에 반영하기 전에는 파일 전체를 한 번에 교체하기보다 변경 사항을 조금씩 적용하며 단계별로 확인하는 것을 권장합니다.
자주 묻는 질문
AllowOverride None이 설정되어 .htaccess 자체가 완전히 무시되고 있는 경우입니다. 서버 관리자에게 AllowOverride All(또는 최소한 AuthConfig, FileInfo 등 필요한 항목)이 활성화되어 있는지 확인을 요청하세요. 브라우저나 CDN 캐시가 이전 응답을 그대로 보여주고 있는지도 함께 확인해 보세요.RewriteRule 패턴 치환대상 [플래그]입니다. 패턴은 요청된 URL 경로(맨 앞의 슬래시 제외)와 매칭되는 정규표현식이며, 치환 대상에서는 $1, $2 등으로 패턴 안의 괄호 그룹을 참조할 수 있습니다. 플래그는 대괄호 안에 쉼표로 구분해 지정하며, [L](이후 규칙 처리 중단)이나 [R=301](영구 리다이렉트) 등이 있습니다.%{REQUEST_FILENAME} !-f(파일로 존재하지 않을 때만 적용)와 같은 RewriteCond를 앞에 붙이는 것이 일반적인 해결책입니다.
여담 ― 왜 ".htaccess"라는 이름이 붙었을까
".htaccess"라는 이름은 "hypertext access"의 줄임말로, 그 역사는 1995년 무렵 NCSA httpd와 초기 Apache 버전까지 거슬러 올라갑니다. 원래는 서버 관리자만 수정할 수 있는 전역 설정 파일(httpd.conf)을 건드리지 않고도, 디렉터리 소유자가 자신이 관리하는 영역에 비밀번호 보호(Basic 인증)를 설정할 수 있도록 도입되었습니다.
.htaccess가 강력한 이유는 Apache 관리자가 AllowOverride 디렉티브를 통해 허용하기만 했다면, FTP나 파일 관리자로 파일을 업로드하는 순간 서버 재시작 없이 설정이 즉시 반영된다는 점입니다. 이 덕분에 메인 설정 파일에 접근할 권한이 없는 공유 호스팅 사용자도 디렉터리 단위로 리다이렉트, 캐시 제어, 접근 제한을 세밀하게 다룰 수 있습니다.
하지만 이런 편리함에는 대가가 따릅니다. Apache 공식 문서는 서버 설정 파일에 접근할 수 있다면 .htaccess 대신 그곳에 디렉티브를 작성할 것을 명확히 권장합니다. 이유는 단순합니다. Apache는 요청이 올 때마다 상위 디렉터리를 거슬러 올라가며 .htaccess 파일을 매번 다시 찾아 읽어야 하므로, 메인 설정 파일에 작성하는 경우에 비해 무시할 수 없는 성능 오버헤드가 발생하기 때문입니다.
또한 구문 오류가 섞이면 많은 공유 호스팅 환경에서 해당 디렉터리 전체가 빈 화면의 "500 Internal Server Error"가 되어버리며, 정확한 원인을 찾는 데 시간이 걸리기 쉽습니다. 꼼꼼한 육안 확인뿐 아니라 이런 정적 검사기를 함께 활용하면 배포 후 사고로 이어지기 전에 실수를 미리 잡아낼 수 있습니다.