TL;DR

이 레포지토리는 Apple의 네트워크 위치 서비스(WLOC) 응답을 프록시 수준에서 가로채어 반환 좌표를 대체함으로써 iOS에서 네트워크 기반 가상 위치를 적용하는 도구와 워커 파서를 제공한다. 핵심 동작은 온라인 선택 페이지에서 좌표를 저장하면 wloc-settings.js가 이를 $persistentStore에 기록하고 이후 wloc.js가 WLOC 호출 시 protobuf 응답을 파싱하여 좌표를 덮어쓰는 방식으로 이루어진다. 지도 공유 링크 처리는 Cloudflare Workers로 302 리다이렉트를 따라 좌표를 추출하고 GCJ-02→WGS84 변환을 적용하여 일관된 위경도를 반환하며 단축키 연동과 여러 프록시 플랫폼용 모듈을 제공하여 실제 사용 편의성을 높였다. 제약으로는 MITM 인증과 gs-loc 도메인 신뢰가 필수이며 iOS 26 이상에서는 locationd의 캐시 특성 때문에 재부팅이 필요할 수 있다.

주요 기능

• 네트워크 레이어에서 gs-loc.apple.com의 WLOC 응답을 가로채어 protobuf를 파싱하고 좌표 필드를 교체하는 기능을 제공한다. 이 과정에서 wloc.js가 저장된 좌표를 읽어 응답을 패치하므로 앱 수준 설정 없이 시스템의 네트워크 위치 결과를 바꿀 수 있다. 모듈은 투과(透传) 모드 판정 로직을 포함하여 저장된 좌표가 없을 때 원본 응답을 그대로 통과시키는 안전 동작을 유지한다.
• 온라인 선택 페이지와 Cloudflare Workers 기반 파서를 통해 Apple Maps와 高德(고덕)에서 공유된 링크를 통합 처리하며 GCJ-02 좌표를 WGS84로 변환하는 파이프라인을 구현했다. 이 파이프라인은 짧은 공유 링크의 302 리다이렉트 헤더에서 좌표를 추출하고 필요시 변환을 수행하여 바로 사용할 수 있는 위경도를 반환한다. 워커는 로그나 저장 없이 단회성 파싱만 수행하도록 설계되어 프라이버시 노출을 최소화한다.
• iCloud Shortcuts(快捷指令)와 연동되는 단축키를 제공하여 사용자가 지도 앱에서 선택한 지점을 즉시 적용하거나 저장된 좌표를 손쉽게 초기화할 수 있다. 단축키는 선택 흐름의 자동화를 담당하므로 사용자가 매번 수동으로 경도·위도를 입력할 필요가 없다. 이 연동은 Apple Maps와 일부 서드파티 지도 공유 동작을 직접 읽어오는 방식으로 동작한다.
• Surge, Quantumult X, Loon, Stash, Shadowrocket 등 다양한 프록시 플랫폼용 모듈을 사전 구성된 파일로 제공하여 사용자가 플랫폼별 변환 과정을 직접 구현할 필요를 줄였다. 각 플랫폼의 저장소 API($persistentStore, $prefs 등)에 맞춘 저장·삭제 스크립트를 포함하여 모듈 활성화·비활성화·복구 절차를 단순화했다. 또한 자체 워커 배포를 위한 Cloudflare 배포 버튼과 배포 스크립트를 제공하여 공용 인스턴스의 요청 한도나 가용성 문제를 우회할 수 있다.

어떻게 동작하는가

사용자가 선택한 지점은 선택 페이지에서 /wloc-settings/save?lon=x&lat=y 형태로 POST되며 이 요청은 wloc-settings.js가 가로채어 프록시 플랫폼의 영구 저장소($persistentStore 등)에 기록된다. 이후 기기에서 WLOC 호출이 발생하면 wloc.js가 저장소에서 좌표를 읽어 protobuf 응답의 위치 필드를 찾아 대체하고 직렬화된 응답을 반환하여 시스템이 수정된 위치를 수신하게 만든다. 지도 공유 링크 처리는 Cloudflare Workers 쪽에서 302 리다이렉트를 따라 실제 좌표를 추출하고 GCJ-02→WGS84 변환을 적용한 뒤 JSON으로 반환하는 방식으로 통일되며 이 워커는 로깅이나 영구 저장 없이 단회성으로 동작한다.

해결 문제

애플의 네트워크 기반 위치(WLOC)를 직접 수정할 방법이 없어 앱·시스템 차원에서 가상 위치를 적용하기 어려운 문제를 해결한다. 사용자는 지도에서 지점을 선택하거나 단축키를 통해 손쉽게 목표 좌표를 저장할 수 있으며 모듈이 네트워크 응답을 패치하여 시스템이 해당 좌표를 받도록 만든다. 또한 중국 지도 서비스에서 발생하는 GCJ-02 편차를 WGS84로 환산하는 파서를 포함하여 좌표 불일치로 인한 오류를 방지한다.

지금 주목받는 이유

프록시 기반 iOS 사용자 환경에서 네트워크 위치를 간편히 대체할 수 있고, 여러 플랫폼용 모듈과 단축키 연동·자체 배포 옵션을 갖추어 실무 적용 사례가 많아 주목을 받았다.

차별점

• Apple Maps와 高德(고덕) 등 서로 다른 지도 서비스의 공유 링크를 하나의 파서로 통합하여 처리한다는 점에서 차별화된다. 공유 링크에서 302 리다이렉트 헤더나 URL 파라미터로 숨겨진 좌표를 워커가 직접 추출하고 GCJ-02→WGS84 변환을 적용하므로 단축키나 클라이언트 스크립트가 복잡한 변환 로직을 구현할 필요가 없다. 이 통합 파서 구조는 링크 포맷이 다른 지도 서비스 간에도 일관된 좌표를 반환하도록 설계되어 운영 편의성을 높인다.
• 여러 프록시 플랫폼용 모듈을 미리 준비하여 플랫폼별 API 차이를 추상화한 점이 실무적 강점이다. Surge와 Loon의 $persistentStore, Quantumult X의 $prefs 등 서로 다른 저장 방식에 맞춘 스크립트를 제공하므로 사용자가 플랫폼별로 코드를 새로 작성하지 않아도 된다. 또한 모듈은 저장된 값이 없을 때 투과 모드로 동작하여 원본 응답을 그대로 전달하는 안전성을 유지한다.
• 단축키(Shortcuts)로 직접 위치를 설정·복구하는 사용자 흐름을 지원하여 UI 기반의 간편성을 확보한 점이 눈에 띈다. 사용자는 지도 앱에서 선택한 지점을 공유 메뉴를 통해 바로 저장하거나 제거할 수 있으며, 단축키는 이 과정을 자동화하여 사용성 장벽을 낮춘다. 단축키와 네트워크 패치 로직을 결합한 설계는 수동 좌표 입력 없이도 즉시 위치를 변경할 수 있게 한다.
• 공용 워커 대신 사용자가 자체적으로 Cloudflare Workers/Pages에 배포할 수 있도록 소스와 배포 스크립트를 제공하여 운영 한계를 회피할 수 있다. README에 포함된 배포 버튼과 wrangler 명령어를 통해 개인 인스턴스를 얻을 수 있으며, 워커는 비영구적 처리 설계로 개인정보 유출 위험을 줄이는 구조로 배포 가능하다. 이 점은 공용 서비스의 요청 한도나 가용성 제약을 회피하려는 사용자에게 실용적이다.

사용 사례

• 앱 개발이나 테스트 환경에서 특정 네트워크 기반 위치를 재현해야 할 때 유용하다. 개발자는 실제 GPS 핸드셋을 이동시키지 않고도 WLOC 응답을 대체하여 위치 기반 기능의 동작을 확인할 수 있다. 이 방식은 CI 환경이 아닌 로컬 디바이스에서의 반복적인 테스트 시나리오를 단순화한다.
• 지역 제한 콘텐츠나 위치 기반 권한 처리를 우회하는 용도로 내부 테스팅 및 시연 환경을 구성할 수 있다. 사용자는 지도에서 지점을 선택하여 저장하고 필요시 빠르게 원복할 수 있으므로 프라이버시 설정을 변경하지 않고도 여러 위치를 전환하며 검증 작업을 진행할 수 있다. 다만 이 사용은 해당 지역의 법적·정책적 제약을 검토한 후 수행해야 한다.
• 실내 WiFi 기반 위치가 주된 환경에서 위치 보정이나 위치 기반 동작 검증을 수행하는 데 적합하다. GPS 신호가 약한 실내 환경에서는 시스템이 네트워크 기반 위치를 우선 참조하는 경우가 있어 wloc을 통해 의도한 위치를 강제로 제공할 수 있다. 이로 인해 실내 네비게이션·위치기반 알림 등 서비스의 동작을 안정적으로 재현할 수 있다.

시작하기

모듈을 사용하려면 우선 사용 중인 프록시 툴(Surge/Quantumult X/Loon 등)에 맞는 구독 주소를 추가하고 해당 모듈을 활성화한 뒤 MITM 인증서와 gs-loc 도메인 신뢰를 설정해야 한다. 온라인 선택 페이지를 브라우저에서 열어 지점을 선택한 뒤 '储存到设备'를 실행하면 선택한 좌표가 프록시의 영구 저장소로 기록되고 이후 WLOC 호출 시 자동으로 적용된다. 자체 워커를 사용하려면 레포지토리의 worker 디렉터리를 클론한 뒤 npm install, npx wrangler login, npm run deploy 순서로 배포하면 개인 워커 주소를 받아 단축키의 기본 파서를 대체할 수 있다.

요구사항

• 프록시 플랫폼에서 MITM 기능을 활성화하고 gs-loc.apple.com 및 gs-loc-cn.apple.com에 대해 신뢰를 부여해야 한다. 해당 설정이 없으면 모듈이 WLOC 요청을 가로챌 수 없어 기능이 무력화된다.
• Cloudflare Workers를 자체 배포하려면 Node.js와 npm, Wrangler(npx wrangler)가 설치되어 있어야 하며 계정 로그인 절차가 필요하다. README에 제시된 배포 명령이 정상적으로 동작하려면 wrangler가 권한을 가진 Cloudflare 계정에 연결되어야 한다.
• iOS 측면에서는 iOS 26 이상에서 locationd의 캐시 정책으로 인해 모듈 적용 직후에도 이전 좌표가 재사용될 수 있으며 이 경우 재부팅이 필요하다. iOS 15~18의 경우 일반적으로 재부팅 없이 즉시 적용되는 반면 최신 버전은 캐시 특성 때문에 추가 조치가 요구된다.