Shadowrocket 설정 파일(.conf) 구조와 사용법: General·Rule·Host·URL Rewrite

이 글의 핵심

Shadowrocket의 .conf는 설정 텍스트 파일이며, 연결 서비스 이용권이 아닙니다. 사용 가능한 연결을 이미 보유하고 있고 설정을 읽거나 수정하려는 사용자를 위해 네 섹션의 역할을 구분한 뒤 설정 사본에서 항목별로 변경하고, 마지막으로 Global Routing의 Config 모드에서 규칙을 확인하는 방법을 안내합니다. 예제는 문법 설명용이며 도메인과 주소는 문서용 예시 값이므로 실제 서비스에 사용할 수 없습니다.

1. 섹션 제목을 확인한 다음 각 줄의 형식을 살펴보세요

대괄호는 섹션의 시작을 나타냅니다. [General] 아래 설정은 다음 섹션 제목이 나올 때까지 General에 속합니다. 빈 줄은 가독성을 위한 구분일 뿐 섹션 제목을 대신할 수 없습니다. 편집할 때는 영문 키워드, 반각 쉼표, 등호, 대괄호를 그대로 유지하고 입력기가 문장부호를 전각 문자로 바꾸지 않도록 주의하세요.

네 섹션은 서로 다른 네 가지 프록시 프로토콜도 아니고, 파일 순서대로 실행되는 네 단계의 네트워크 관문도 아닙니다. General은 전역 설정을 제공하고, Rule은 요청 처리 방식을 선택하며, Host는 지정한 도메인을 주소에 매핑하고, URL Rewrite는 조건에 맞는 URL을 표현식으로 처리합니다. ‘위에서 아래로’ 적용되는 순서는 Rule 내부의 규칙에 해당하며, 이를 파일 전체에 그대로 적용하면 안 됩니다.

4개 섹션

이 글의 범위: General / Rule / Host / URL Rewrite

구분 기호 2종류

General과 Host에서는 등호를, Rule에서는 쉼표를 주로 사용합니다

기본 처리 규칙 1개

최소 예제에서는 FINAL을 Rule의 마지막에 둡니다

[General]
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

[Host]
test.example.com = 192.0.2.10

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

2. General: 전역 설정은 트래픽 분기 규칙이 아닙니다

General에서는 보통 매개변수 이름 = 매개변수 값 형식으로 작성합니다. 예를 들어 dns-server = system은 시스템 DNS를 사용한다는 뜻입니다. 이 설정은 DNS 조회 동작을 정할 뿐, ‘모든 요청을 직접 연결’하거나 ‘모든 요청을 프록시로 연결’한다는 의미가 아닙니다. 요청 처리 방식은 현재 Global Routing 모드와 적용되는 규칙에 따라 달라집니다.

[General]
dns-server = system

DNS를 변경하기 전에 문제가 어느 단계에서 발생하는지 확인하세요. 도메인 조회에 실패했는지, 대상 주소를 얻은 후 연결에 실패했는지 구분해야 합니다. DNS, 규칙, 원격 연결 설정을 한꺼번에 바꾸면 결과가 달라져도 어떤 항목이 영향을 줬는지 알 수 없습니다. 기존 설정에 다른 General 매개변수가 포함될 수 있으므로, 이 글의 한 줄 예제를 섹션 전체를 대체하는 근거로 삼지 마세요.

기존 설정에서 유효한 매개변수는 유지하고, 이번에 확인할 항목만 수정하세요.
매개변수 값에는 반각 문자를 사용하고, 값 뒤에 한국어 설명을 바로 덧붙이지 마세요.
General에 DOMAIN-SUFFIX나 FINAL을 넣지 마세요. 이 키워드들은 Rule에 속합니다.
시스템 DNS와 지정한 리졸버의 결과가 다르면, 먼저 조회 결과를 기록한 다음 조정이 필요한지 판단하세요.

3. Rule: 매칭 범위·정책·순서를 함께 확인하세요

Rule은 보통 유형,매칭 내용,정책 형식으로 작성합니다. DOMAIN-SUFFIX,example.com,PROXY는 example.com과 그 하위 도메인을 매칭한 다음 PROXY를 적용합니다. 매칭 내용에는 https://나 경로를 넣지 않으며, 전체 URL을 쓰는 것도 아닙니다. 호스트 이름 하나만 매칭하려면 DOMAIN을 사용하는 편이 더 명확합니다.

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

이 예시에서는 api.example.com이 먼저 DOMAIN에 매칭되므로 뒤에 있는 DOMAIN-SUFFIX 규칙까지 내려가지 않습니다. 그 밖의 example.com 하위 도메인은 접미사 규칙에 매칭될 수 있습니다. 두 줄의 순서를 바꾸면 범위가 더 넓은 접미사 규칙이 먼저 매칭되어 단일 도메인 예외가 의도대로 적용되지 않습니다. 앞선 규칙에 매칭되지 않은 요청은 FINAL이 처리하므로 보통 마지막에 둡니다.

도메인으로 매칭

DOMAIN: api.example.com처럼 전체 도메인 이름을 매칭합니다.
DOMAIN-SUFFIX: example.com과 그 하위 도메인을 매칭합니다. 임의의 문자열 포함 여부를 확인하는 규칙은 아닙니다.
DOMAIN-KEYWORD: 도메인에 포함된 키워드로 매칭하므로 예상보다 넓은 범위에 적용될 수 있습니다.

구체적인 예외를 넓은 범위의 규칙보다 앞에 두세요. 도메인 규칙에는 URL 경로를 넣지 않습니다.

주소 및 기본 처리 규칙으로 매칭

IP-CIDR: IP 주소 대역을 매칭합니다. 192.0.2.0/24는 이 글에서 사용하는 문서용 예시 대역입니다.
GEOIP: 대상 IP의 지리 정보 데이터베이스를 기준으로 매칭하며, 결과는 데이터베이스의 기록에 따라 달라집니다.
FINAL: 매칭 내용을 쓰지 않고 FINAL,PROXY와 같은 기본 처리 정책을 바로 지정합니다.

no-resolve는 해당 IP 규칙을 위해 추가 도메인 조회를 하지 않도록 하는 옵션이며, 모든 DNS를 끈다는 뜻은 아닙니다.

DIRECT는 직접 연결, PROXY는 프록시 정책에 따라 처리한다는 의미입니다. 정책 이름은 서버 주소가 아닙니다. GEOIP 결과는 IP 주소와 데이터베이스 정보에 따라 달라지므로, 특정 중국어 웹사이트가 반드시 CN에 매칭된다고 보장할 수 없습니다. 특정 도메인에 예외를 적용하려는 경우 웹페이지 언어를 근거로 GEOIP를 추측하기보다 명확한 도메인 규칙을 우선 고려하세요.

4. Host: 주소를 고정 매핑하며 정책을 선택하지 않습니다

Host는 지정한 도메인을 주소에 매핑하는 기능으로, 일반적인 형식은 도메인 = IP 주소입니다. 이는 ‘매칭된 요청에 어떤 정책을 적용할지’를 정하는 Rule과 별개의 기능입니다. 도메인을 특정 주소에 매핑해도 요청이 자동으로 DIRECT 처리되는 것은 아닙니다. 현재 라우팅 모드와 규칙을 함께 확인해 실제 처리 결과를 판단하세요.

[Host]
test.example.com = 192.0.2.10

이 줄은 test.example.com의 매핑만 지정하며 example.com의 모든 하위 도메인에 자동으로 적용되지 않습니다. 사이트가 동적 주소나 분산된 진입점을 사용한다면, 고정 주소는 서비스 변경 후 작동하지 않을 수 있습니다. 추가한 이유를 기록하고 매핑을 삭제한 뒤에도 다시 확인하세요. 출처가 불분명한 Host 항목을 오래된 설정에서 그대로 유지하지 마세요.

Host와 Rule은 수정 목적이 다릅니다

주소를 지정하려는 경우

Host에 전체 도메인과 확정된 대상 주소를 입력하세요.
주소가 접속하려는 서비스에 실제로 속하는지 확인하세요.
실제 접속을 시도하기 전에 이 글의 문서용 예시 주소를 삭제하세요.

요청 처리 정책을 바꾸려는 경우

Rule에 DOMAIN 또는 DOMAIN-SUFFIX를 추가하세요.
DIRECT, PROXY 또는 정의된 유효한 정책을 선택하세요.
구체적인 예외를 넓은 범위의 규칙과 FINAL보다 앞에 두세요.

주소 조회 대상과 라우팅 정책을 각각 확인하세요. 트래픽 분기 규칙 대신 Host를 사용하지 마세요.

5. URL Rewrite: URL을 기준으로 매칭하며 도메인별 트래픽을 분기하지 않습니다

URL Rewrite는 매칭할 주소를 표현식으로 지정한 다음 대체 결과나 해당 동작을 설정합니다. 아래는 HTTP에서 HTTPS로 302 리디렉션하는 예시입니다. 정규식에서 \.는 문자 그대로의 마침표를 나타내고, (.*)는 경로 내용을 캡처하며, 대체 주소의 $1은 첫 번째 캡처 그룹을 참조합니다.

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

입력 예시: http://example.com/help.
대체 대상: https://example.com/help.
^와 $는 매칭 범위의 시작과 끝을 지정해 주소 중간의 일부만 매칭되는 것을 방지합니다.
302는 리디렉션 응답 상태를 나타내며, 프록시 포트나 Rule 정책 이름이 아닙니다.

이 예시는 HTTP로 시작하는 URL을 매칭합니다. 모든 HTTPS 경로를 바로 읽을 수 있다는 뜻은 아닙니다. HTTPS 경로는 암호화된 콘텐츠 안에 있으므로 경로를 처리하려면 추가 전제 조건이 필요합니다. URL Rewrite 섹션을 추가하는 것만으로 이러한 조건이 자동으로 충족되지는 않습니다. 이 글에서는 인증서 관련 설정을 변경할 필요가 없으며, 이 HTTP 예제를 확인하기 위해 수정 범위를 넓히는 것도 권장하지 않습니다.

6. 저장한 뒤 Config를 선택하고 변경 항목을 하나씩 확인하세요

파일을 편집하는 것과 변경한 파일을 적용하는 것은 별개의 단계입니다. Config에서 수정 사항을 저장한 후 현재 선택된 파일이 해당 설정인지 확인하세요. Rule을 검증하려면 Home → Global Routing으로 돌아가 Config를 선택합니다. Proxy나 Direct 모드에 그대로 있으면 접속 결과만으로 방금 수정한 트래픽 분기 규칙이 올바른지 판단할 수 없습니다.

원본 보관

Config에서 현재 사용 중인 로컬 설정을 찾아 사본을 만들거나 원본을 백업하세요. 현재 파일 이름을 기록하고, 유일하게 사용할 수 있는 설정 파일을 바로 덮어쓰지 마세요.
항목 하나만 수정

대상 설정의 편집 화면을 열고 한 섹션에서 수정할 항목 하나만 변경하세요. 예를 들어 먼저 DOMAIN,api.example.com,DIRECT를 추가하고, Host와 DNS는 동시에 수정하지 마세요.
저장 후 선택

저장한 뒤 Config로 돌아가 대상 설정이 선택되어 있는지 확인하세요. 이어서 Home → Global Routing → Config로 이동해 이번 테스트에서 규칙 기반 분기가 실제로 사용되는지 확인합니다.
새 요청 보내기

이미 연결된 장시간 연결만 확인하지 않도록 대상 요청을 새로 보내세요. 요청 도메인, 예상 정책, 실제 결과를 기록하고 필요하면 다시 연결한 뒤 테스트하세요.
변경 전후 비교

방금 추가한 줄을 삭제하고 같은 대상을 다시 확인하세요. 결과가 예상과 다르면 수정을 더 추가하지 말고 매칭 순서와 현재 선택된 설정부터 다시 살펴보세요.

Config

권장

선택한 설정의 규칙에 따라 요청을 처리합니다. DIRECT와 PROXY 중 무엇이 적용될지는 규칙의 내용과 순서에 달려 있으며, 나머지 요청이 항상 직접 연결되는 것은 아닙니다.

적합한 용도: 이 글의 Rule 수정 검증 및 일상적인 규칙 기반 트래픽 분기.

Proxy

요청을 프록시 모드로 처리하며 Rule에 따라 항목별로 트래픽 분기 정책을 선택하지 않습니다. 프록시 연결의 작동 여부를 확인하는 비교 기준으로는 쓸 수 있지만, 규칙이 매칭됐다는 근거로 사용할 수는 없습니다.

적합한 용도: 사용 가능한 서비스가 이미 있는 상태에서 연결 문제와 규칙 문제를 구분해 확인할 때.

Direct

요청을 직접 연결 모드로 처리합니다. 이 모드의 결과로 PROXY 규칙이 올바른지 판단할 수 없습니다.

적합한 용도: 같은 대상이 직접 연결 환경에서 어떻게 동작하는지 확인할 때.

Global Routing의 Scene은 시나리오 설정과 관련된 기능이므로 Config 규칙 검증과 혼동하지 마세요. Settings → On Demand는 필요 시 연결 조건을 관리하는 메뉴이며 Rule 편집 화면이 아닙니다. 네트워크 조건에 따라 연결이 자동으로 바뀔 수 있다면 테스트 전에 이 별도 설정들을 확인해 연결 상태 변화를 .conf 문법 오류로 오해하지 않도록 하세요.

7. 설정이 적용되지 않으면 증상에 따라 원인을 좁혀 보세요

‘파일을 저장할 수 있다’는 것은 편집이 완료됐다는 의미일 뿐, 모든 규칙이 의도대로 작성됐다는 뜻은 아닙니다. 점검할 때는 먼저 파일과 모드를 확인한 다음 대상, 순서, 문법을 살펴보세요. 다음 항목은 서비스를 바꾸지 않고 확인할 수 있으며, 현재 이용 가능한 연결이 있는 상태에서 하나씩 점검하기에 적합합니다.

증상	먼저 확인할 항목	확인 방법
Rule을 추가해도 변화가 없음	현재 파일과 Global Routing	Config에서 올바른 파일이 선택됐는지 확인하고 Home → Global Routing에서 Config를 선택하세요.
특정 도메인 예외가 적용되지 않음	규칙의 순서	DOMAIN 예외를 더 넓은 DOMAIN-SUFFIX 규칙보다 앞에 두고 FINAL은 마지막에 유지하세요.
특정 도메인 하나만 접속할 수 없음	Host의 고정 매핑	해당 도메인의 기존 매핑을 삭제한 뒤 다시 테스트하세요. 이때 DNS를 동시에 바꾸지 마세요.
URL Rewrite가 적용되지 않음	프로토콜, 호스트 이름, 표현식	요청이 HTTP인지 HTTPS인지 확인하고, 마침표 이스케이프와 경로가 매칭되는지 살펴보세요.
파일 저장 후 파싱 문제가 발생함	섹션 제목과 반각 문장부호	대괄호, 쉼표, 등호를 확인하세요. 최근 변경을 되돌린 다음 설정을 다시 여세요.

사용자가 이미 보유한 구독은 보통 연결 정보를 관리하는 데 사용되며, ‘구독 업데이트’를 ‘현재 로컬 .conf 파일이 업데이트됐다’는 뜻으로 볼 수 없습니다. 설정이 원격 소스에서 제공된 경우 원격 원본과 로컬 사본도 구분해야 합니다. 이후 업데이트 과정에서 기존 내용이 바뀔 수 있습니다. 같은 파일을 반복해서 가져오기보다 로컬 수정 내역을 기록해 두면 문제의 원인을 추적하기 쉽습니다.

최소 검증에는 필요한 General, 대상 Rule, FINAL만 남기세요. 필요하지 않은 예제 섹션은 추가하지 않아도 됩니다.
매번 수정 항목 하나, 테스트 대상 하나, 결과 하나를 기록해 여러 변수를 동시에 바꾸지 않도록 하세요.
전체 문법과 더 많은 섹션 설명은 설정 종합 가이드에서 확인하세요. 용어는 개념 빠른 참조에서 찾아볼 수 있습니다.