.htaccess 구문 검사기

.htaccess 파일 내용을 붙여넣기만 하면 블록 태그 닫힘 누락, 디렉티브 이름 오타, RewriteRule 인수 부족, 규칙이 없는 RewriteCond 등 흔한 실수를 즉시 찾아냅니다.

마지막 업데이트: 2026-09-20

.htaccess의 잘못을 찾아내기

`.htaccess`는 한 글자만 틀려도 사이트 전체가 500 오류를 낼 수 있는 파일입니다. 내용을 붙여 넣으면 이 도구가 그 자리에서 전형적인 잘못—닫지 않은 블록 태그, 철자가 틀린 지시어 이름, 인자가 모자란 `RewriteRule`, 홀로 남겨진 `RewriteCond`—을 찾아냅니다.

**여기서 살피는 것은 문법이지, 뜻대로 도는지가 아닙니다.** 다시쓰기 규칙이 아무리 흠 없이 적혀 있어도 조건의 차례가 어긋나면 마음에 둔 URL로는 보내지지 않습니다. 그 밖에 알아 둘 만한 규격이 둘 있습니다. 하나는 **`RewriteCond`가 바로 뒤에 오는 `RewriteRule` 하나에만 걸린다**는 것으로, 조건만 여럿 늘어놓고 끝에 규칙 하나를 두는 표기는 아예 성립하지 않습니다. 다른 하나는 **서버 설정에서 `AllowOverride`가 꺼져 있으면 `.htaccess`가 처음부터 읽히지 않는다**는 점입니다. 적어 두었는데 아무 일도 일어나지 않는다면 파일이 아니라 서버 설정을 의심하십시오.

사용하는 방법

.htaccess의 내용을 붙여 넣습니다 파일 전체를 그대로 넣어 주십시오.
먼저 예시로 확인합니다 온전한 예와 잘못이 든 예가 함께 마련되어 있습니다.
짚인 줄을 읽습니다 **닫지 않은 태그와 모자란 인자가 줄 번호와 함께 보고됩니다.**
아무 일도 없다면 서버 설정도 봅니다 **`AllowOverride`가 꺼져 있으면 파일은 읽히지 않습니다.**

더 잘 활용하기 위한 팁

이 검사기는 행 단위의 휴리스틱한 정적 분석이며 실제 Apache 파서가 아닙니다. 배포 전에는 반드시 실제 서버나 스테이징 환경에서 동작을 확인하세요.
Apache 서버에 셸로 접속할 수 있다면 apachectl configtest가 가장 확실한 구문 검사 방법입니다. 이 도구는 공유 호스팅처럼 그 명령을 사용할 수 없는 환경에서의 사전 점검용입니다.
"인식되지 않은 디렉티브" 경고는 고정된 허용 목록에 기반한 낮은 확신도의 추측일 뿐입니다. 잘 알려지지 않은 모듈의 디렉티브를 사용한 경우 이 경고가 나와도 반드시 틀린 것은 아닙니다.
여러 줄의 RewriteCond를 연속으로 쌓는 것은 일반적인 사용 방식입니다(AND 조건처럼 작동). 이 도구는 연속된 RewriteCond의 마지막 줄 뒤에 RewriteRule이 없을 때만 경고합니다.
운영 환경에 반영하기 전에는 파일 전체를 한 번에 교체하기보다 변경 사항을 조금씩 적용하며 단계별로 확인하는 것을 권장합니다.

이럴 때 쓸 수 있습니다

운영에 올리기 전에 확인할 때

**`.htaccess`의 잘못은 사이트 전체를 넘어뜨리므로 미리 살피는 값어치가 큽니다.**

다시쓰기 규칙을 덧붙일 때

기존 규칙에 조건을 더한 뒤 꼴이 무너지지 않았는지 볼 수 있습니다.

넘겨받은 설정을 읽어 낼 때

오래 덧대어 온 파일 안에 이미 듣지 않는 대목이 없는지 확인할 수 있습니다.

500 오류의 범위를 좁힐 때

**서버가 뜨지 않는 까닭이 문법에 있는지를 먼저 가려낼 수 있습니다.**

.htaccess 용어

RewriteEngine: 다시쓰기 기능을 켜는 지시어입니다. **이를 `On`으로 두지 않으면 뒤따르는 규칙은 하나도 듣지 않습니다.**
RewriteCond: 다시쓰기의 조건입니다. **바로 뒤에 오는 `RewriteRule` 하나에만 걸린다**는 점을 새겨 두어야 합니다.
RewriteRule: 다시쓰기 규칙 자체로, 패턴과 바꿀 곳, 그리고 `[L,QSA]` 같은 깃발을 받습니다.
깃발: 규칙 뒤 대괄호 안의 설정입니다. `L`은 여기서 멈추라는, `QSA`는 질의 문자열을 이어받으라는 뜻입니다.
블록 태그: ``이나 `` 같은 감쌈입니다. **닫는 것을 빠뜨리면 500 오류가 납니다.**
AllowOverride: `.htaccess`에 어떤 지시어를 허용할지 정하는 서버 쪽 설정입니다. **꺼져 있으면 그 파일은 아예 읽히지 않습니다.**

자주 묻는 질문

가장 흔한 원인은 Apache 메인 설정에서 해당 디렉터리에 AllowOverride None이 설정되어 .htaccess 자체가 완전히 무시되고 있는 경우입니다. 서버 관리자에게 AllowOverride All(또는 최소한 AuthConfig, FileInfo 등 필요한 항목)이 활성화되어 있는지 확인을 요청하세요. 브라우저나 CDN 캐시가 이전 응답을 그대로 보여주고 있는지도 함께 확인해 보세요.

기본 형태는 RewriteRule 패턴 치환대상 [플래그]입니다. 패턴은 요청된 URL 경로(맨 앞의 슬래시 제외)와 매칭되는 정규표현식이며, 치환 대상에서는 $1, $2 등으로 패턴 안의 괄호 그룹을 참조할 수 있습니다. 플래그는 대괄호 안에 쉼표로 구분해 지정하며, [L](이후 규칙 처리 중단)이나 [R=301](영구 리다이렉트) 등이 있습니다.

변환된 URL이 같은 RewriteRule의 패턴에 다시 매칭되어 Apache가 계속 같은 변환을 반복하는 것이 전형적인 원인입니다. 변환 대상 경로가 실제로 존재하는 파일이라면 처리가 멈추도록, %{REQUEST_FILENAME} !-f(파일로 존재하지 않을 때만 적용)와 같은 RewriteCond를 앞에 붙이는 것이 일반적인 해결책입니다.

대부분의 공유 호스팅 환경에서는 해당 디렉터리 아래의 모든 페이지가 "500 Internal Server Error"를 반환하게 됩니다. 서버의 오류 로그에 접근할 수 있다면, 그것이 정확한 줄 번호와 원인을 가장 빠르게 찾는 방법입니다.

아니요, 그것을 보장할 수는 없습니다. 이 도구는 행 단위 정규표현식에 기반한 휴리스틱한 정적 검사이며, 실제 Apache 파서의 동작을 완전히 재현하지는 않습니다. 필요한 모듈(mod_rewrite 등)이 로드되어 있는지, 특정 디렉티브가 해당 컨텍스트에서 허용되는지는 서버 환경에 따라 다르므로, 결과를 신뢰하기 전에 반드시 스테이징 환경이나 실제 서버에서 확인하세요.

여담 ― 왜 ".htaccess"라는 이름이 붙었을까

".htaccess"라는 이름은 "hypertext access"의 줄임말로, 그 역사는 1995년 무렵 NCSA httpd와 초기 Apache 버전까지 거슬러 올라갑니다. 원래는 서버 관리자만 수정할 수 있는 전역 설정 파일(httpd.conf)을 건드리지 않고도, 디렉터리 소유자가 자신이 관리하는 영역에 비밀번호 보호(Basic 인증)를 설정할 수 있도록 도입되었습니다.

.htaccess가 강력한 이유는 Apache 관리자가 AllowOverride 디렉티브를 통해 허용하기만 했다면, FTP나 파일 관리자로 파일을 업로드하는 순간 서버 재시작 없이 설정이 즉시 반영된다는 점입니다. 이 덕분에 메인 설정 파일에 접근할 권한이 없는 공유 호스팅 사용자도 디렉터리 단위로 리다이렉트, 캐시 제어, 접근 제한을 세밀하게 다룰 수 있습니다.

하지만 이런 편리함에는 대가가 따릅니다. Apache 공식 문서는 서버 설정 파일에 접근할 수 있다면 .htaccess 대신 그곳에 디렉티브를 작성할 것을 명확히 권장합니다. 이유는 단순합니다. Apache는 요청이 올 때마다 상위 디렉터리를 거슬러 올라가며 .htaccess 파일을 매번 다시 찾아 읽어야 하므로, 메인 설정 파일에 작성하는 경우에 비해 무시할 수 없는 성능 오버헤드가 발생하기 때문입니다.

또한 구문 오류가 섞이면 많은 공유 호스팅 환경에서 해당 디렉터리 전체가 빈 화면의 "500 Internal Server Error"가 되어버리며, 정확한 원인을 찾는 데 시간이 걸리기 쉽습니다. 꼼꼼한 육안 확인뿐 아니라 이런 정적 검사기를 함께 활용하면 배포 후 사고로 이어지기 전에 실수를 미리 잡아낼 수 있습니다.

모든 여담 보기