如何把 WLOC 选点服务部署到 Cloudflare Workers:完整自部署教程
如何把 WLOC 选点服务部署到 Cloudflare Workers:完整自部署教程
WLOC 选点服务部署到 Cloudflare Workers 其实只需几条命令。这份 WLOC 自部署教程,带你把虚拟定位选点页和地图链接解析接口完整搬到自己的 Workers 域名下——全程不需要 KV 或数据库,也不用改动任何源码。
WLOC 是一套基于 Apple 网络定位修改的工具,配合代理客户端的 MITM 拦截使用。除了本机的客户端模块外,它还依赖一个在线选点服务:一个能在地图上选点、并支持快捷指令调用解析接口的网页应用。这个服务正是本文要部署的 Worker。
🧭 部署前:先认识 WLOC 选点服务
部署前花一分钟了解它由哪两部分组成,能帮你部署后正确验证:
| 组成 | 作用 | 源码位置 |
|---|---|---|
| 选点网页 | 在地图上选点、搜索地点、输入或粘贴经纬度,点击「储存到设备」 | worker/src/page.js |
解析接口 /api/parse |
供快捷指令把地图分享链接解析成经纬度,自动做 GCJ-02 / BD-09 转 WGS84 | worker/src/parse.js |
整个服务基于 Hono。它对解析请求显式返回 Cache-Control: no-store,避免坐标被浏览器或共享缓存留存。
💡 为什么值得自部署?官方公共实例不再作为默认选点服务,自建后域名、入口都归你掌控,也方便把快捷指令、模块里的地址统一切换到自己的站点。
📦 部署前准备清单
开始之前,请确认以下三项都就绪:
- Node.js 22 或更高版本(
wrangler已锁定在依赖中,无需手动装) - 一个 Cloudflare 账户(用于登录并创建 Worker)
- 一个可公开访问的代码仓库:客户端模块需要通过公开地址匿名下载脚本,因此
repository要指向一个公开仓库
拉取源码:
git clone https://gitcode.com/gh_mirrors/wloc/wloc
cd wloc
整个工程围绕两个配置入口展开,先记住它们:
- project.config.json:控制仓库、发布分支与选点站点地址
- worker/wrangler.jsonc:控制 Worker 的项目名与运行参数
✍️ 配置 project.config.json:填写仓库与站点
打开根目录的 project.config.json,它有三个字段:
{
"repository": "你的用户名/仓库名",
"branch": "main",
"siteUrl": ""
}
| 字段 | 怎么填 | 说明 |
|---|---|---|
repository |
owner/repo 格式 |
脚本据此生成客户端可匿名下载的公开订阅地址 |
branch |
你的发布分支 | 如 main;若从 tag 部署可填对应 tag |
siteUrl |
HTTPS 站点根地址 | 可先留空,部署后回填 |
注意:repository 必须是公开仓库,否则代理客户端无法匿名拉取脚本;siteUrl 若填写,只能是纯 HTTPS 根地址,不能带查询参数或片段(生成脚本会做严格校验,见 scripts/configure.mjs)。
⚠️ 不要直接手改
modules/下的订阅文件,它们是由templates/modules/生成的产物,应交给npm run configure统一重写。
⚙️ 一键生成模块并校验
在仓库根目录执行:
npm run configure
npm run check:release
npm run configure:依据project.config.json重新生成五种客户端模块、更新网页源码入口与 README 订阅表(逻辑见 scripts/configure.mjs)。npm run check:release:做发布前校验,确认模块、文档本地链接和上游文件完整性都没问题(见 scripts/check.mjs)。
如果 check:release 报错"与配置不一致",说明生成文件与配置不匹配,重跑 configure 即可。
🚀 登录 Cloudflare 并部署 Worker
进入 worker 目录并依次执行:
cd worker
npm ci
npm run build:check
npx wrangler login
npm run deploy
每一步都在做什么:
| 命令 | 作用 |
|---|---|
npm ci |
按锁文件安装依赖(含 wrangler 与 hono) |
npm run build:check |
dry-run,只打包到本地不上传,先确认构建无误 |
npx wrangler login |
浏览器完成 Cloudflare 授权 |
npm run deploy |
真正写入 Cloudflare 并上线 |
部署前,如果账号里已有同名 Worker,先改一下 worker/wrangler.jsonc 里的 name(默认为 wloc-spoofer),避免覆盖他人或自己的旧项目。本 Worker 没有绑定 KV、数据库或账户 ID,因此无需额外配置。
完整流程可以对照下面这张图:
flowchart LR
A[clone 仓库] --> B[填写 project.config.json]
B --> C[npm run configure]
C --> D[npm run check:release]
D --> E[cd worker && npm ci]
E --> F[npm run build:check]
F --> G[npx wrangler login]
G --> H[npm run deploy]
H --> I[回填 siteUrl 再次生成]
✅ 部署后验证:三步确认选点服务可用
从部署输出中拿到站点 URL,按 docs/DEPLOYMENT.md 的清单逐项核对:
- 首页能打开:访问站点根地址,确认选点地图正常加载,页面底部源码入口指向你的发布仓库。
- 解析接口正确:访问
/api/parse?u=31.230400,121.473700&format=json应返回对应lat/lon,且响应头带Cache-Control: no-store;只带format=json缺参数时应返回422。 - 回填并重新生成:把站点 URL 填回根目录 project.config.json 的
siteUrl,再运行一次:
npm run configure
npm run check:release
这样五种客户端模块与网页入口就都指向你自己的选点服务了。
🔁 替代方案:Cloudflare Pages
如果更习惯 Pages,也可以用同一份代码发布(详见 docs/DEPLOYMENT.md):
cd worker
npm ci
npm run pages:build
npx wrangler login
npm run pages:deploy
注意 worker/wrangler.pages.jsonc 与 wrangler.jsonc 的 compatibility_date 要保持一致,避免两边落在不同运行时语义上;改名时两个文件都要同步检查。
📌 常见问题
部署会用到数据库吗?
不会。本 Worker 只依赖标准 Web API 和 hono,无需 KV 或数据库。
网页显示保存成功,为什么地图位置没变? 网页只负责把坐标发给本机 WLOC 模块拦截写入,真正的定位修改依赖代理客户端的 MITM 与 CA 证书链路。请确认模块已启用、MITM 已开、证书已完全信任。
Workers 有费用吗? 以你自己的 Cloudflare 控制台额度为准,本项目不保证任何公共实例长期可用。
🧾 边界提醒
- WLOC 修改的是 Wi-Fi / 基站网络定位结果,不是 GPS 硬件定位;室外 GPS 信号强时可能被真实位置覆盖。
- 上游自 iOS 27 beta 6 起出现 TLS / MITM 限制,iOS 27 正式版当前按不支持处理,请勿把精力花在反复重装证书上。
- 仅在你自己拥有或已获授权的设备、网络与账号上进行定位测试,并遵守所在地法规与平台规则。
更多发布细节与维护边界,可参考 docs/MAINTENANCE.md。