이 글의 목차
구독을 가져올 때 긴 오류 메시지가 나와도 바로 파일을 편집할 필요는 없습니다. 요청이 설정을 가져오지 못했을 수도 있고, 내용을 가져왔지만 불러오지 못했을 수도 있습니다. 두 경우는 다음 조치가 완전히 다릅니다. 전체 오류 메시지와 정상 작동하는 사본을 보관한 뒤 반환된 내용이 현재 코어에 맞는지 판단하면 원래 상태로 되돌리기도 쉽습니다.
구독이 다운로드 단계에서 실패했을까, 구성 해석 단계에서 실패했을까?
오류 원문, HTTP 상태, 구체적인 줄 번호를 저장하고 아래 표로 다운로드 문제와 설정 구문 분석 문제를 구분하세요. 링크가 유효하지 않거나 로그인 페이지가 반환되면 구독 출처를 확인합니다. 들여쓰기 오류가 있거나 코어가 필드를 지원하지 않을 때 다운로드한 내용을 점검하세요.
두 실패 유형의 근거
| 동작 | 설명 | 먼저 할 일 |
|---|---|---|
| HTTP 401, 403, 404, 시간 초과 | 원격 요청에서 아직 사용할 수 있는 설정을 받지 못함 | token, 주소, 네트워크, 서버 상태를 확인하세요 |
| HTML, 로그인 페이지 또는 요금제 안내가 반환됨 | URL에는 접속되지만 내용이 YAML이 아님 | 웹페이지 주소가 아니라 구독 인터페이스를 복사했는지 확인하세요 |
| mapping values are not allowed | YAML 구조 또는 들여쓰기 오류 | 오류가 표시된 줄과 상위 계층의 들여쓰기를 기준으로 찾으세요 |
| unknown field、cannot unmarshal | 구문은 맞더라도 현재 코어가 필드 또는 데이터 형식을 지원하지 않을 수 있음 | 코어 버전과 공식 필드를 확인하세요 |
응답 헤더와 시작 부분을 확인하되 전체 구독 주소는 공개하지 마세요
자신이 제어하는 터미널 또는 브라우저 개발자 도구에서 구독 응답을 확인하세요. 상태는 성공이어야 하고 본문 시작 부분은 YAML 설정이나 provider 데이터처럼 보여야 합니다. <!DOCTYPE html>, 로그인 양식, JSON 오류 또는 '트래픽 소진' 안내가 나오면 안 됩니다.
구독 URL에는 경로나 쿼리 매개변수에 token이 포함될 수 있습니다. 스크린샷과 로그의 인증 정보를 가리고, 구분할 수 없다면 URL 전체를 가리세요. curl 명령을 공개 이슈에 붙여 넣지 마세요. 링크가 노출됐다면 제공업체 관리 페이지에서 초기화한 뒤 조사를 계속하세요.
# URL 中含私密 token，不要复制输出到公开位置
curl -I "https://example.invalid/subscription?token=REDACTED"
curl -sS "https://example.invalid/subscription?token=REDACTED" | head서비스는 요청의 User-Agent에 따라 다른 내용을 반환할 수 있습니다. 클라이언트에서 실제로 업데이트할 때 받은 응답을 기준으로 삼으세요. curl 결과는 비교용이며 그 결과만으로 구독 링크가 무효라고 판단할 수는 없습니다.
들여쓰기 오류와 코어 필드 호환성 문제 처리
YAML은 들여쓰기로 계층을 표현합니다. Tab, 빠진 콜론, 닫히지 않은 따옴표, 잘못된 목록 하이픈 때문에 구문 분석기가 다음 줄에서야 오류를 표시할 수 있습니다. line 48 column 7이 보이면 제48줄만 보지 말고 그 줄이 어느 키에 속하는지, 이전 항목이 끝났는지 위쪽까지 확인하세요.
프록시 이름에 콜론, 해시 또는 특수 문자가 있으면 따옴표로 감싸야 합니다. 같은 계층에서 서로 다른 수의 공백을 섞지 마세요. 원본 파일을 보존한 채 복사본을 편집하고, 오류 하나만 수정한 뒤 다시 테스트해 다음 오류를 확인합니다.
# 正确：proxies 是列表
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
# 错误：proxies 被写成普通字符串
proxy-groups:
- name: PROXY
type: select
proxies: DIRECT일반 YAML 검사기는 텍스트 구조만 검증하며 Mihomo의 필드, 형식, 참조 관계는 알지 못합니다. unknown field, proxy not found, group not found 또는 지원하지 않는 프로토콜이 표시되면 들여쓰기를 계속 조정할 것이 아니라 현재 코어의 문서와 버전을 확인해야 합니다.
클라이언트에 포함된 코어 버전이 구독 생성기보다 오래됐거나 병합 덮어쓰기로 필드가 잘못된 위치로 이동했을 수 있습니다. 먼저 '정보' 화면이나 시작 로그에서 실제 코어를 확인한 뒤 현재 Mihomo 문서와 대조하세요. 업그레이드 전에 정상 설정을 보존해 프로토콜 호환성 문제를 새 마이그레이션 문제로 키우지 마세요.
전체 설정, 노드 Provider, 규칙 세트는 서로 대체할 수 없습니다
전체 설정에는 보통 포트, 프록시 그룹, rules가 포함됩니다. proxy-provider 파일은 주로 노드를 제공하고 rule-provider 파일은 domain, ipcidr, classical 같은 behavior에 따라 규칙 내용을 제공합니다.
provider URL을 전체 구독으로 가져와도 올바른 YAML이라는 사실만으로 필요한 프록시 그룹과 규칙이 포함됐다고 볼 수는 없습니다. 클라이언트에서 필드 누락 오류가 나거나 불러오더라도 원하는 라우팅 설정이 없을 수 있습니다. 주 설정에서 참조하는 방식으로 사용하세요.
반대로 전체 설정을 proxy-providers에 넣으면 목록 구문 분석 단계에서 실패할 수 있습니다. 반환된 최상위 키와 서비스 제공자의 가져오기 방식을 먼저 확인한 뒤 Profile, proxy-providers, rule-providers 중 어디에 둘지 결정하세요.
- 전체 Profile
- 보통 단독으로 로드할 수 있으며 proxy-groups와 rules 같은 실행 설정을 포함합니다.
- Proxy Provider
- 주 설정의 proxy-providers가 참조하며 주로 노드 목록을 담습니다.
- Rule Provider
- RULE-SET에서 사용하며 behavior와 payload 구조가 서로 맞아야 합니다.
복사본에서 테스트하고 클라이언트가 병합한 최종 파일도 확인하세요
원본 응답을 직접 관리하는 로컬 위치에 저장한 뒤 복사본에서 편집하고 테스트하세요. 외부에 공유할 때는 별도 사본에서 token과 노드 인증 정보를 가리고, 가린 자리표시자 값을 실제 실행 설정에 다시 쓰지 마세요. Mihomo 명령줄은 지정 디렉터리의 설정을 테스트할 수 있고 그래픽 클라이언트도 보통 불러오기 전에 검증합니다. 실제 사용 중인 코어가 출력한 첫 번째 오류부터 확인하세요.
원본 파일은 통과하는데 클라이언트에서 실패한다면 Merge, Mixin, 덮어쓰기 스크립트 또는 전역 설정이 생성한 최종 설정을 확인하세요. 구독 자체가 잘못된 것이 아니라 덮어쓰기가 삭제된 정책 그룹을 참조하거나 동일한 최상위 키에 호환되지 않는 내용을 두 번 생성한 경우가 흔합니다.
원본 구독은 읽히지만 최종 설정에서 group not found 발생
흔한 원인:덮어쓰기 또는 이전 규칙이 더는 존재하지 않는 정책 그룹을 참조함
해결 방법:최종 설정에서 그룹 이름을 검색하고 관련 덮어쓰기를 잠시 비활성화하세요.
구독 내용이 HTML임
흔한 원인:웹사이트 페이지를 복사했거나 로그인이 만료됐거나 token이 무효함
해결 방법:전용 구독 주소를 다시 받아야 하며 HTML을 편집하지 마세요.
Provider만 업데이트되지 않음
흔한 원인:URL, path, behavior 또는 쓰기 권한 문제
해결 방법:provider 유형에 맞춰 확인하고 전체 Profile을 다시 만들지 마세요.
불러올 수 있는 구성 복구와 문제 해결 기록 보관
사용 중인 설정이 손상되면 마지막으로 작동했던 Profile이나 제공자가 다시 만든 정상 구독으로 돌아가 연결을 복원하세요. 평소 쓰는 유일한 설정을 계속 수동으로 고치거나 파싱에 실패한 파일을 시작 시 자동 로드하도록 설정하지 마세요.
수정 기록에는 최소한 실패 단계, 원본 오류, 클라이언트 및 코어 버전, 해결 조치를 남기세요. 같은 구독을 다음에 업데이트했을 때 문제가 재발하면 이 정보로 서버 생성 방식의 변경, 클라이언트 업그레이드, 로컬 덮어쓰기의 오류 재유입을 구분할 수 있습니다.