免越狱接管 Apple /clls/wloc 定位流:iOS-Location-Spoofer-Web 的流式 Protobuf 引擎、边缘网关与兼容边界实测
免越狱环境下修改 iOS 设备全局定位,传统路线往往依赖 Mac / Windows 桌面端连接 Xcode DeveloperDiskImage 或 libimobiledevice 调试通道,一旦拔掉数据线或重启设备就会失效。最近我把开源项目 akudamatata/iOS-Location-Spoofer-Web(CC BY-NC-SA 4.0 协议)拉到本地做了一轮完整源码审计与协议实测,发现它用一套极轻量的组合把整条链路搬到了移动端与边缘节点:以 Cloudflare Pages + KV 作为全栈控制台,通过 Shadowrocket 的 HTTPS MITM 拦截 Apple /clls/wloc 二进制定位响应,再用零 BigInt 依赖的纯 JS 流式 Protobuf 引擎执行“最小改写”。
更有意思的是,顺着它的 50 条提交历史与核心代码往下挖,我不仅看到了从“令牌硬注入漏洞”到 HTMLRewriter 脱敏的重构现场,还实测出 iOS 12+ JavaScriptCore 兼容、4+1 封包探测与滑窗兜底的底层细节,以及几处尚未被文档提及的代码层边界与小 Bug。这篇文章把它的全栈架构、二进制改写机理与实战避坑一次拆清。
[!NOTE] 源码审计基线与本机实测说明
本文所有文件路径、协议字段号、阈值常量与安全审计结论,均对照自开源仓库 akudamatata/iOS-Location-Spoofer-Web(审计至 commit13e59f5,2026-09-02)。核心客户端引擎location-spoofer.js共922行,边缘服务端由functions/下7个 Cloudflare Pages Functions 构成,前端面板public/index.html为单文件1,905行实现。我在本地 Node.js 环境对
location-spoofer.js导出模块的实测结果:
- 对南半球坐标
-33.86882(放大10^8倍为-3386882000)执行Varint64.encodeSigned()与Varint64.decode()往返测试,输出10字节补码序列b09081b1f3ffffffff01,无损还原为-3386882000;- 构造包含
1条 Wi-Fi(Tag2)、1条蜂窝基站(Tag22)及未知根字段 Tag33的110字节标准 ARPC 封包输入spoofAppleResponse(),成功识别为kind: 'arpc',改写wifiCount: 1、cellCount: 1,并完整透传根字段[2, 22, 33]。
一、五层全栈拓扑:零服务器运维的边缘控制面 + 本地 MITM 数据面
在传统自建定位方案里,开发者常需要自己维护一台跑 Docker 的 VPS,既要管域名证书、又要担心后端进程挂掉。iOS-Location-Spoofer-Web 在 2026-07-10 彻底删掉了 docker-compose 与环境变量模板,把控制面完全切到了 Cloudflare Pages + KV 的免费边缘额度上,形成了极简的五层栈式结构。
把这五层按职责拆开看,每一层的代码密度都非常克制:
| 层级 | 核心文件与组件 | 关键职责与技术选型 |
|---|---|---|
| L5 · 客户端面板 | public/index.html、public/manifest.json |
单文件无构建工程(无 React/Webpack),直接引用 Leaflet 1.9.4,实现 Liquid Glass(液态玻璃)UI、PWA 全屏沉浸适配与双坐标系纠偏。 |
| L4 · 边缘接口层 | functions/*.js(7 个边缘函数) |
借助 Cloudflare HTMLRewriter 注入运行时开关,通过 KV 命名空间 SPOOFER_DATA 读写 loc 与 favorites(上限 100 条)。 |
| L3 · 代理隧道层 | public/ios-location-spoofer.sgmodule、functions/ios-location-spoofer.sgmodule.js |
动态生成带当前域名与 Token 的 Shadowrocket 模块,利用 %APPEND% 注入 MITM 主机名,开启 binary-body-mode=1 接管二进制响应体。 |
| L2 · 二进制改写核 | location-spoofer.js(与 public/location-spoofer.js 完全一致) |
零依赖实现 64 位 Varint 编解码、Apple ArpcCodec、4+1 封包探测与 WLOC 最小改写。 |
| L1 · 系统边界层 | iOS locationd 与 /clls/wloc 服务 |
覆盖 iOS 12.0 ~ iOS 26.x 与 iOS 27 beta 1 ~ 5;但 iOS 27 beta 6+ 因苹果开启强 TLS 证书固定(Certificate Pinning),所有 MITM 路线均已失效。 |
这里有一个很容易被忽略的工程细节:打开 public/ios-location-spoofer.sgmodule,能看到它劫持的域名并不只有苹果官方的 gs-loc.apple.com、gs-loc-cn.apple.com 与 gsp-ssl.ls.apple.com,还同时覆盖了高德定位辅助域 bluedot.is.autonavi.com 及其阿里 DNS 别名 bluedot.is.autonavi.com.gds.alibabadns.com,匹配路径统一锁定为 /clls/wloc(?:\?.*)?$。在国行 iOS 设备开启定位服务时,系统会向国内分发节点发起混合请求,漏掉高德边缘域名就会出现“微信改成功了、系统地图却飘回真实位置”的割裂现象。
二、核心二进制引擎深潜:location-spoofer.js 如何改写 Apple WLOC
整个项目技术含量最高的部分都在 location-spoofer.js(922 行)。在 2026-09-02 的重构(commit 0094ea5)中,作者把早期外部依赖脚本彻底重写为纯原生模块化架构,集中解决了两个底层难题:老旧 JavaScriptCore 的 64 位整型溢出,以及新版本 iOS 对未知 Protobuf 字段的严格校验。
1. 为什么放弃 BigInt,手写双 32 位 Varint64?
Apple WLOC 协议里的经纬度并不是 IEEE-754 浮点数,而是将角度乘以 100,000,000(10^8)后编码为有符号 64 位整数(Varint)。以北京默认坐标 39.90872 为例,乘以 10^8 后为 3,990,872,000——已经超过了 JavaScript 常规位运算(<<、>>、|)的 32 位有符号上限 2,147,483,647。如果直接用普通 JS 位运算编码经纬度,高位比特会被无情截断,结果直接变成错误坐标。
那为什么不直接用 ES2020 的 BigInt?因为 Shadowrocket 的脚本运行在 NEPacketTunnelProvider 网络扩展沙盒内的 JavaScriptCore 中,在 iOS 12 ~ iOS 13 老设备或低版本系统内核下并不支持 BigInt。为此,作者在 Varint64 模块(第 162–255 行)用双 32 位无符号字({ low, high })和二进制补码算术手搓了一套完整的 64 位 Varint 编解码器:
- 高位拆分:用
Math.floor(num / 4294967296) >>> 0提取高 32 位,用num >>> 0提取低 32 位,安全范围覆盖到Number.MAX_SAFE_INTEGER(9007199254740991),远超全球经纬度±180 × 10^8的量级; - 负数补码:遇到南半球或西半球负坐标(如我实测的
-33.86882)时,fromSigned()先对绝对值按位取反再加 1,并在low === 0时手动向high进位(carry),编码出标准的 10 字节 64 位负数 Varint; - 跨边界右移:在
encodeWords()循环中,每次吐出 7 个 payload 比特后,通过((low >>> 7) | (high << 25)) >>> 0把高字最低 7 位无缝拼接到低字顶部,彻底绕开BigInt依赖。
2. “4+1” 封包探测与 WLOC 最小改写决策流
Apple /clls/wloc 的 HTTP 响应体并不是裸露的 Protobuf,不同 iOS 版本与请求类型会在外层套上不同格式的二进制信封(Envelope)。我在 extractEnvelope() 与 spoofAppleResponse()(第 594–722 行)梳理出了它的五级递进探测链:
这五级探测按优先级依次匹配:
- Synthetic 封包:校验
responseBytes前缀是否符合0x00 0x01 ... 0x00 0x00特征,并读取第8–9字节大端无符号 16 位长度提取负载; - 结构化 ARPC 封包:调用
ArpcCodec.parse()按大端字节序依次解析version (u16)、locale/appIdentifier/osVersion(2 字节长度前缀 Pascal 字符串)、functionId (u32)与payloadLength (u32); - Marker 签名封包:通过
ByteUtils.findSequence()全局检索 6 字节特征码00 00 00 01 00 00,紧随其后读取u16BE长度切出负载; - Bare 裸 Protobuf:直接校验首字节
wireType(0 或 2)与fieldNumber > 0; - 滑窗特征扫描兜底(
scanPatchRawBuffer):当苹果微调外层包头导致前 4 路全部失配时,引擎会先以步长2扫描前96字节偏移,再以步长1补扫0–256字节区间,尝试把每个偏移切片喂给patchWlocPayload(),一旦成功改写出至少 1 条 Wi-Fi 或基站记录,立刻用标准APPLE_SYNTHETIC_PREFIX重新封包回传。
最核心的工程智慧体现在 patchWlocPayload()(第 516–541 行)的 WLOC 最小改写(Minimal Rewrite) 策略上:
// patchWlocPayload 核心透传逻辑(location-spoofer.js L522-534)
for (var i = 0; i < fields.length; i += 1) {
var f = fields[i];
if (f.fieldNumber === 2 && f.wireType === 2) {
parts.push(ProtobufEngine.makeLengthDelimitedField(2, patchWifiEntity(f.valueBytes, config)));
wifiCount += 1;
} else if (CELL_RESPONSE_TAGS[f.fieldNumber] && f.wireType === 2) {
parts.push(ProtobufEngine.makeLengthDelimitedField(f.fieldNumber, patchCellEntity(f.valueBytes, config)));
cellCount += 1;
} else {
// 关键:其余根级字段(包括 3, 4, 33 等)全量原样透传,不丢弃!
parts.push(f.raw);
}
}
早期的很多定位脚本喜欢把响应解码成 JSON 后只挑几个字段重新拼装,结果一旦遇上 iOS 18 ~ 27 新增的根级元数据字段(如源码注释点名的 Tag 3、4、33)就会因为结构残缺被 locationd 直接拒收。这里的 ProtobufEngine.readFields() 在解析每个字段时都保留了原始字节切片 f.raw:
- 对 Wi-Fi 实体(根 Tag
2-> 子字段 Tag2)和蜂窝基站实体(根 Tag22/24-> 子字段 Tag5)中的Location子消息,仅当确认同时存在字段1(纬度)与2(经度)时,才原地替换字段1、2与字段3(水平精度horizontalAccuracy); - 其余 BSSID、信号强度、时间戳以及所有未定义 Protobuf 字段,全部通过
f.raw一字节不差地原样回写。同时failOpen默认开启,哪怕解析抛出异常也会执行$done({})放行原始响应,避免断网或导致定位服务假死。
[!WARNING] 我在源码审计中发现的两处逻辑反差
- 海拔与垂直精度其实“存而未改”:前端底部抽屉、
functions/set.js的 KV 存储,乃至location-spoofer.js顶部的CONFIG_DEFAULTS与runShadowrocket()(第873–874行),都完整同步了altitude与verticalAccuracy。但实际执行二进制改写的patchLocationRecord()(第455–486行)其实 只处理了fieldNumber1(纬度)、2(经度)和3(水平精度),并没有把海拔和垂直精度写入 WLOC Protobuf 报文。换句话说,目前面板上调整这两个高级参数只会存入 KV,并不会实际影响系统返回的模拟海拔。- 静态与透传分支的冗余写法:在
ProtobufEngine.makeVarintField()(第345–347行)中,判断signedOrUnsignedVal < 0的三元表达式两个分支调用的都是Varint64.encodeSigned(signedOrUnsignedVal);另外在spoofAppleResponse()组装回包时,如果命中bare(裸 Protobuf),脚本会强制给它套上一层APPLE_SYNTHETIC_PREFIX(0001000000010000+ 2 字节长度),而不是保持裸 Protobuf 返回,这一点在排查特定系统版本的原始响应回放时需要注意。
三、四域协同生命周期:鉴权修复、坐标纠偏与动态同步
搞定了底层二进制改写,Web 面板如何安全地把坐标传递给手机端的小火箭脚本?项目用 Cloudflare Pages Functions + HTMLRewriter 搭出了一套四域协同链路。
1. 从“HTML 明文泄密”到 HTMLRewriter 脱敏
翻看 Git 提交历史时,我注意到 2026-09-02 的一次关键安全修复(commit f0af3da):在此之前的版本里,functions/index.js 直接把环境变量 env.TOKEN 原封不动地拼接进 <script>window.__CFG__={ token, amapKey }</script> 塞回给前端页面!这意味着只要有人对站点首页执行一次简单的 curl,就能直接拿到管理员的明文 TOKEN,所谓的“30 天液态玻璃密码锁屏”形同虚设。
修复后的 functions/index.js 改成了严格的布尔标志位注入:
const hasToken = Boolean(env.TOKEN);
const amapKey = env.AMAP_KEY || '';
const configScript = `<script>window.__CFG__=${JSON.stringify({ hasToken, amapKey })};</script>`;
浏览器收到页面后,先检查 HAS_TOKEN。如果服务端开启了鉴权,则校验 localStorage 中有效期 30 天的 gps_session,并通过 GET /verify?token=... 向边缘节点验真,验证通过才把密钥写入本地缓存并开始拉取 /loc.json 与 /favorites。
2. 中国区火星坐标系(GCJ-02)与 WGS-84 的往返闭环
Apple 底层 /clls/wloc 必须接收全球标准的 WGS-84 坐标,但国内用户最习惯使用的高德地图底图和地名检索(restapi.amap.com/v3/assistant/inputtips)全部运行在加密偏转后的 GCJ-02 坐标系下。
public/index.html 内置了一套无外部依赖的 GCJ 转换器(第 1131–1159 行):
- 当切换到高德地图(
amap)或高德卫星(sat)时,内部存储与提交的WGS状态始终保持 WGS-84,仅在渲染地图中心点、蓝色已锁定图钉(updateLockedPin)或处理高德搜索结果时实时转换; - 当切换到 CartoDB 国际地图(
osm)或 Esri 卫星(esri)时,直接透传原始 WGS-84 坐标; - 消除浮点往返误差的细节:由于
GCJ.w2g()与近似反解GCJ.g2w()存在微米级往返浮点误差,早期用 6 位小数精确比对会导致“刚收藏的位置再点过去,星标却不亮”。作者在coordMatch()(第1551–1554行)专门设定了0.000015°(约1.7米)的容差窗口,彻底稳住了星标状态高亮与防重复收藏。
3. 一键模块导入与 configUrl 热同步
用户不需要在手机端手动改写任何脚本。点击设置面板的“一键导入模块”时,前端会动态拼装当前域名与 Token,触发 shadowrocket://install/module?url=... 协议唤醒小火箭,请求边缘函数 functions/ios-location-spoofer.sgmodule.js。该边缘函数在响应瞬间把静态模板里的占位符 你的域名 和 你的Token 实时替换为真实 Host 与 Token。
导入后,每次 Apple locationd 发起 /clls/wloc 请求并被 Shadowrocket 拦截时,runShadowrocket() 会带着 5 秒超时向 configUrl(即 https://你的域名/loc.json?token=...)发起 $httpClient.get(),拉取最新锁定的坐标并即时改写返回包。配合 iOS 端“关闭定位服务等待 10 秒再重新开启”清掉系统基站缓存,几秒内就能把新坐标刷进微信、高德或系统地图。
四、部署前必读:代码审计暴露的 4 项细节瑕疵与安全边界
虽然这套架构在个人单用户场景下非常优雅,但把全量代码一行行审计下来,我还是抓出了几个尚未修复的工程瑕疵,如果你打算 Fork 自建,建议顺手补齐:
[!CAUTION] 源码级细节瑕疵与安全建议
- 收藏夹跳转到 Esri 国际卫星图层时的 500 米偏移 Bug:在
public/index.html第1588行的收藏夹条目点击事件中,代码写的是var disp=currentLayer==='osm'?[f.latitude,f.longitude]:GCJ.w2g(f.latitude,f.longitude);——唯独漏掉了同属 WGS-84 坐标系的'esri'!对照全文件其余四处(onMapMove、switchLayer、doSearch、updateLockedPin)均正确判断了currentLayer==='osm'||currentLayer==='esri'。结果就是如果你正在用“国际卫星”图层,点开收藏夹跳回中国境内地点时,地图中心会意外偏移几百米。修复只需补全||currentLayer==='esri'即可。- 未配置高德 Key 时的 XSS 风险点:高德搜索分支(第
1397行)和收藏夹渲染(第1578行)都对名称调用了escHtml()转义;但当未配置AMAP_KEY回退到 OpenStreetMap Nominatim 搜索时,第1425行直接把第三方接口返回的parts[0]拼进了row.innerHTML。同样,搜索历史(第1336行)把用户输入仅做单引号转义后直接塞进了内联onclick属性。建议统一改用textContent与addEventListener。- 高德 Key 仍暴露于未鉴权首页 & Token 经 URL 传递:虽然
env.TOKEN已经脱敏,但functions/index.js依然会把明文AMAP_KEY注入未登录也能访问的首页 HTML 中(建议在高德控制台务必为该 Key 配置 HTTP Referer 白名单,限制仅允许自己的.pages.dev或自定义域名调用)。此外,全站 API 与.sgmodule均采用?token=查询参数鉴权且authOk()使用普通===比对,Token 会留在浏览器历史与代理配置 URL 中,绝不能复用常用个人密码作为TOKEN。- iOS 27 beta 6+ 的系统级终局限制:正如仓库兼容性矩阵所标注,一旦设备升级到启用了强制 TLS Certificate Pinning 的系统版本,无论脚本怎么优化 Protobuf 探测,系统定位进程都会直接拒绝 Shadowrocket 签发的本地 CA 证书。对于测试机而言,保留在
iOS 12 ~ iOS 26.x(或iOS 27 beta 5及以下)是目前 MITM 路线的硬前提。
综合来看,akudamatata/iOS-Location-Spoofer-Web 把一个原本高度依赖桌面端硬件连线的工具,压缩成了一套零运维成本的 Serverless Web 应用:前端用单文件原生 JS 撑起了流畅的 Liquid Glass PWA 体验与双坐标系纠偏,底层用零 BigInt 的手写 64 位 Varint 与最小改写策略扛住了多年来的协议演进。对于需要频繁做 LBS 跨区联调、测试定位回调边界或研究 Apple 私有定位协议的开发者而言,它既是一套拿来即用的利器,也是一份极佳的轻量级二进制代理工程参考样本。
原文链接与参考资料
- 官方开源仓库:akudamatata/iOS-Location-Spoofer-Web - GitHub
- 核心代理改写脚本:location-spoofer.js 源码
- Shadowrocket 模块模板:ios-location-spoofer.sgmodule
- Cloudflare Pages 边缘函数:Cloudflare Pages Functions 官方文档
- Open-Meteo 地形海拔接口:Open-Meteo Elevation API