mac-location-sdk

macOS CoreLocation 定位 SDK — 获取本机经纬度，支持 WGS84 / GCJ02 坐标系输出。

特性

• 🖥️ Universal Binary（arm64 + x86_64），同时支持 Apple Silicon 和 Intel Mac
• 🔒 预编译 LocHelper.app，无需用户机器上有 Swift 编译器
• 🌏 WGS84 → GCJ02 坐标转换，国内打车/地图平台直接可用
• 🔄 智能重试机制，locationUnknown（error 0）自动退避重试，提高定位成功率
• 🎯 多次采样模式，持续收集坐标取精度最高的，提升定位准确性
• 🛡️ 三级查找策略：预编译 → 用户缓存 → 现场编译（自动 fallback）
• 📦 零配置，npm install 即用

安装

npm install mac-location-sdk

使用

基础用法

import { getLocation, wgs84ToGcj02 } from "mac-location-sdk";

// 获取 GCJ02 坐标（默认，适合国内打车平台）
const loc = getLocation({ gcj02: true });
if (loc) {
  console.log(
    `${loc.coordSystem}  lng=${loc.longitude}  lat=${loc.latitude}  ±${loc.accuracy}m`,
  );
}

// 获取原始 WGS84 坐标
const wgs = getLocation({ gcj02: false });

// 手动坐标转换
const gcj = wgs84ToGcj02(116.397428, 39.90923);
console.log(gcj); // { lng: 116.403..., lat: 39.916... }

// 出错时抛异常（而非静默返回 null）
const strict = getLocation({ throwOnError: true });

高精度采样模式

Mac 主要通过 Wi-Fi 扫描定位，首次返回的坐标可能不够精准。开启多次采样后，SDK 会在指定时间窗口内持续收集坐标更新，取精度最高的返回：

import { getLocation } from "mac-location-sdk";

// 快速定位（默认，拿到第一个有效坐标即返回）
const fast = getLocation({ gcj02: true });

// 高精度定位（8 秒窗口内收集多个坐标，取精度最高的）
const precise = getLocation({
  gcj02: true,
  sampleCount: 5,       // 期望采样次数
  sampleTimeout: 8,     // 采样窗口（秒）
});

// 更高精度（适合室内定位）
const indoor = getLocation({
  gcj02: true,
  sampleCount: 10,
  sampleTimeout: 15,
});

💡 采样模式原理：CoreLocation 在持续定位过程中会不断修正位置，sampleCount > 1 时 SDK 不会拿到第一个坐标就停止，而是在 sampleTimeout 秒内持续收集，最终返回精度最高（accuracy 最小）的坐标。

API

getLocation(options?)

获取本机经纬度。

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | gcj02 | boolean | true | 返回 GCJ02（国内打车平台用）。false 则返回原始 WGS84 | | timeoutMs | number | 90000 | helper .app 输出超时（毫秒） | | throwOnError | boolean | false | 失败时是否抛错。false 时失败返回 null | | sampleCount | number | 1 | 采样次数。1 快速返回，>1 取精度最高的（更准但更慢） | | sampleTimeout | number | 8 | 采样窗口（秒），仅 sampleCount > 1 时生效 |

返回 Location | null：

interface Location {
  latitude: number;
  longitude: number;
  accuracy: number;            // 水平精度（米）
  coordSystem: "wgs84" | "gcj02";
}

wgs84ToGcj02(lng, lat)

WGS84 → GCJ02 坐标转换。若坐标不在中国范围内，原样返回。

formatLocation(loc)

格式化定位结果为可读字符串。

CLI

安装后可直接运行：

npx mac-location-sdk

输出：

====== 定位结果 ======
GCJ02  经度 116.403XXXXX  纬度 39.916XXXXX  精度 ±15 米
======================

定位授权

首次运行时 macOS 会弹出定位授权弹窗，点击「允许」即可。之后不再弹窗。

权限管理：系统设置 → 隐私与安全性 → 定位服务 → LocHelper

常见问题

定位不够精准怎么办？

1. 开启多次采样：getLocation({ sampleCount: 5, sampleTimeout: 8 })
2. 确保 Wi-Fi 已开启且联网 — Mac 主要靠 Wi-Fi 扫描定位
3. 靠近窗户 — 减少 Wi-Fi 信号反射干扰
4. Mac 没有 GPS 芯片，Wi-Fi 定位精度通常在 10~100 米，这是硬件限制

kCLErrorDomain error 0（locationUnknown）

定位权限已授权但定位数据暂不可用，常见原因：

1. Wi-Fi 未开启 — Mac 主要靠 Wi-Fi 扫描定位，请确认 Wi-Fi 已打开
2. 网络不通 — Wi-Fi 定位需要联网查询 Apple 位置数据库
3. 定位服务总开关未开 — 系统设置 → 隐私与安全性 → 定位服务
4. locationd 异常 — 终端执行 sudo killall locationd 重启定位服务

v1.1.0+ 会自动对 error 0 进行退避重试（1s → 2s → 4s，最多 3 次），多数情况下重试后可成功定位。

定位权限被拒绝（error 1）

前往：系统设置 → 隐私与安全性 → 定位服务 → LocHelper 勾选允许。

开发

构建

npm run build

重新预编译 LocHelper（需要 Xcode）

npm run prebuild-helper

类型检查

npm run typecheck

更新日志

v1.3.0

• 🎯 新增多次采样模式（sampleCount + sampleTimeout），持续收集坐标取精度最高的返回
• 📐 新增 formatLocation() 格式化输出函数
• 🛡️ accuracy 字段改为必填，parseFloat 返回 NaN 时兜底为 0
• ⚠️ 非 macOS 平台改为 console.warn 提示（而非静默返回 null）
• 🐛 修复内联 Swift 模板字符串插值失效的 bug
• 🐛 修复 URL.pathname 含空格/中文路径时路径解析失败
• 📦 补充 TypeScript 源码（src/）和 tsconfig.json

v1.2.0

• 🖥️ LocHelper 编译为 Universal Binary（arm64 + x86_64），支持 Intel Mac

v1.1.0

• 🔄 requestLocation() 改为 startUpdatingLocation() + 获取后自动停止，更稳定
• 🔁 locationUnknown（error 0）自动退避重试（1s → 2s → 4s，最多 3 次）
• 🛡️ 权限 denied/restricted 快速退出，不再等待超时
• 📝 JS 侧新增 error 0 识别和详细排查指引

v1.0.0

• 🎉 初始版本

License

MIT