如何把 WLOC 选点服务部署到 Cloudflare Workers:完整自部署教程

原创2026-11-05 12:22:282,595 阅读

如何把 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:填写仓库与站点

打开根目录的 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 的清单逐项核对:

  1. 首页能打开:访问站点根地址,确认选点地图正常加载,页面底部源码入口指向你的发布仓库。
  2. 解析接口正确:访问 /api/parse?u=31.230400,121.473700&format=json 应返回对应 lat/lon,且响应头带 Cache-Control: no-store;只带 format=json 缺参数时应返回 422。
  3. 回填并重新生成:把站点 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。

登录后查看全文
wloc