연결 문제 해결 · Clash 기술 블로그

Clash 구독 가져오기 실패 해결 방법: Invalid YAML, 만료된 링크 및 형식 수정

가져오기에 실패하면 구독이 다운로드되었는지 먼저 확인하고 받은 내용을 YAML과 Mihomo에서 파싱할 수 있는지 살펴보세요. 401, HTML 페이지, Invalid YAML 및 unsupported field는 각각 다른 해결 방법이 필요합니다.

본문 읽기블로그로 돌아가기
  • 구독
  • YAML
  • 가져오기 실패
이 글의 목차
게시일
업데이트 날짜
예상 읽기 시간
약 6분

Clash 구독 가져오기가 실패하면 링크 만료와 형식 해석 실패부터 구분하세요

클라이언트는 흔히 '업데이트 실패'라는 하나의 알림으로 표시하지만 링크 만료, Invalid YAML, unsupported field는 전혀 다른 방식으로 처리해야 합니다. 오류 원문, HTTP 상태, 줄 번호를 보존하고 실패 단계를 먼저 판단해야 실제로는 로그인 페이지인 파일을 YAML 편집기로 고치는 일을 피할 수 있습니다.

두 실패 유형의 근거

동작설명먼저 할 일
HTTP 401, 403, 404, 시간 초과원격 요청에서 아직 사용할 수 있는 설정을 받지 못함token, 주소, 네트워크, 서버 상태를 확인하세요
HTML, 로그인 페이지 또는 요금제 안내가 반환됨URL에는 접속되지만 내용이 YAML이 아님웹페이지 주소가 아니라 구독 인터페이스를 복사했는지 확인하세요
mapping values are not allowedYAML 구조 또는 들여쓰기 오류오류가 표시된 줄과 상위 계층의 들여쓰기를 기준으로 찾으세요
unknown field、cannot unmarshal구문은 맞더라도 현재 코어가 필드 또는 데이터 형식을 지원하지 않을 수 있음코어 버전과 공식 필드를 확인하세요

응답 헤더와 시작 부분을 확인하되 전체 구독 주소는 공개하지 마세요

자신이 제어하는 터미널 또는 브라우저 개발자 도구에서 구독 응답을 확인하세요. 상태는 성공이어야 하고 본문 시작 부분은 YAML 설정이나 provider 데이터처럼 보여야 합니다. <!DOCTYPE html>, 로그인 양식, JSON 오류 또는 '트래픽 소진' 안내가 나오면 안 됩니다.

구독 URL에는 설정을 직접 가져올 수 있는 token이 포함되는 경우가 많습니다. 스크린샷에서는 쿼리 매개변수를 가리고 curl 명령을 공개 문의에 붙이지 마세요. 링크가 이미 노출됐다면 서비스 패널에서 먼저 재설정한 뒤 이전 응답 점검을 계속합니다.

로컬 기기에서만 응답 확인
# URL 中含私密 token，不要复制输出到公开位置
curl -I "https://example.invalid/subscription?token=REDACTED"
curl -sS "https://example.invalid/subscription?token=REDACTED" | head

YAML 오류가 표시된 줄은 이전 계층 구조가 이미 깨진 결과일 때가 많습니다

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가 해당 필드를 받아들이는 것은 아닙니다

일반 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 또는 서비스 제공자가 다시 생성한 깨끗한 구독으로 먼저 전환해 네트워크를 복구하세요. 유일한 운영 설정을 연속으로 직접 수정하지 말고, 구문 분석에 실패한 파일을 시작 시 자동 로드하도록 설정하지도 마세요.

수정 기록에는 최소한 실패 단계, 원본 오류, 클라이언트 및 코어 버전, 해결 조치를 남기세요. 같은 구독을 다음에 업데이트했을 때 문제가 재발하면 이 정보로 서버 생성 방식의 변경, 클라이언트 업그레이드, 로컬 덮어쓰기의 오류 재유입을 구분할 수 있습니다.

참고 자료