mac-location-sdk

English | 中文

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

English | 中文

macOS CoreLocation SDK — Get latitude & longitude on your Mac, with WGS84 / GCJ02 coordinate system output.

Features

• 🖥️ Universal Binary (arm64 + x86_64) — supports both Apple Silicon and Intel Macs
• 🔒 Pre-compiled LocHelper.app — no Swift compiler required on the user's machine
• 🌏 WGS84 → GCJ02 coordinate conversion — ready for domestic ride-hailing / map platforms
• 🔄 Smart retry — automatic backoff retry on locationUnknown (error 0) for higher success rate
• 🎯 Multi-sample mode — continuously collects coordinates and returns the most accurate one
• 🛡️ Three-tier lookup strategy — precompiled → user cache → on-the-fly compile (auto fallback)
• 📦 Zero config — just npm install and go

Installation

npm install mac-location-sdk

Usage

Basic

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

// Get GCJ02 coordinates (default, suitable for domestic ride-hailing platforms)
const loc = getLocation({ gcj02: true });
if (loc) {
  console.log(
    `${loc.coordSystem}  lng=${loc.longitude}  lat=${loc.latitude}  ±${loc.accuracy}m`,
  );
}

// Get raw WGS84 coordinates
const wgs = getLocation({ gcj02: false });

// Manual coordinate conversion
const gcj = wgs84ToGcj02(116.397428, 39.90923);
console.log(gcj); // { lng: 116.403..., lat: 39.916... }

// Throw on error (instead of silently returning null)
const strict = getLocation({ throwOnError: true });

High-Precision Sampling Mode

Macs locate primarily via Wi-Fi scanning, so the first coordinate returned may not be very accurate. When multi-sample mode is enabled, the SDK continuously collects coordinate updates within a specified time window and returns the most precise one:

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

// Fast location (default — returns the first valid coordinate)
const fast = getLocation({ gcj02: true });

// High-precision location (8-second window, returns the most accurate coordinate)
const precise = getLocation({
  gcj02: true,
  sampleCount: 5,       // expected number of samples
  sampleTimeout: 8,     // sampling window (seconds)
});

// Even higher precision (suitable for indoor positioning)
const indoor = getLocation({
  gcj02: true,
  sampleCount: 10,
  sampleTimeout: 15,
});

💡 How sampling works: CoreLocation continuously refines position during ongoing location updates. When sampleCount > 1, the SDK doesn't stop at the first coordinate — it keeps collecting within the sampleTimeout window and returns the coordinate with the best accuracy (smallest accuracy value).

API

getLocation(options?)

Get the current device's latitude and longitude.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | gcj02 | boolean | true | Return GCJ02 coordinates (for domestic ride-hailing platforms). false returns raw WGS84 | | timeoutMs | number | 90000 | Timeout for helper .app output (milliseconds) | | throwOnError | boolean | false | Whether to throw on failure. false returns null on failure | | sampleCount | number | 1 | Number of samples. 1 returns immediately, >1 returns the most accurate (more accurate but slower) | | sampleTimeout | number | 8 | Sampling window (seconds), only effective when sampleCount > 1 |

Returns Location | null:

interface Location {
  latitude: number;
  longitude: number;
  accuracy: number;            // horizontal accuracy (meters)
  coordSystem: "wgs84" | "gcj02";
}

wgs84ToGcj02(lng, lat)

WGS84 → GCJ02 coordinate conversion. If the coordinates are outside China, returns them unchanged.

formatLocation(loc)

Format a location result as a human-readable string.

CLI

After installation, you can run it directly:

npx mac-location-sdk

Output:

====== Location Result ======
GCJ02  Longitude 116.403XXXXX  Latitude 39.916XXXXX  Accuracy ±15m
==============================

Location Authorization

On first run, macOS will show a location authorization dialog — click "Allow". It won't appear again afterwards.

Permission management: System Settings → Privacy & Security → Location Services → LocHelper

FAQ

Location not accurate enough?

1. Enable multi-sample mode: getLocation({ sampleCount: 5, sampleTimeout: 8 })
2. Make sure Wi-Fi is on and connected — Macs locate primarily via Wi-Fi scanning
3. Move closer to a window — reduces Wi-Fi signal reflection interference
4. Macs don't have GPS chips; Wi-Fi positioning accuracy is typically 10–100 meters — this is a hardware limitation

kCLErrorDomain error 0 (locationUnknown)

Location permission is granted but location data is temporarily unavailable. Common causes:

1. Wi-Fi not enabled — Macs locate primarily via Wi-Fi scanning; make sure Wi-Fi is turned on
2. No network connectivity — Wi-Fi positioning requires internet access to query Apple's location database
3. Location Services toggle is off — System Settings → Privacy & Security → Location Services
4. locationd malfunction — Run sudo killall locationd in Terminal to restart the location service

v1.1.0+ automatically retries error 0 with backoff (1s → 2s → 4s, up to 3 times). In most cases, location succeeds after retrying.

Location permission denied (error 1)

Go to: System Settings → Privacy & Security → Location Services → LocHelper and check Allow.

Development

Build

npm run build

Rebuild pre-compiled LocHelper (requires Xcode)

npm run prebuild-helper

Type check

npm run typecheck

Changelog

v1.3.0

• 🎯 Added multi-sample mode (sampleCount + sampleTimeout) — continuously collects coordinates and returns the most precise one
• 📐 Added formatLocation() formatting output function
• 🛡️ accuracy field is now required; parseFloat returning NaN falls back to 0
• ⚠️ Non-macOS platforms now show a console.warn message (instead of silently returning null)
• 🐛 Fixed inline Swift template string interpolation bug
• 🐛 Fixed path resolution failure when URL.pathname contains spaces / Chinese characters
• 📦 Added TypeScript source code (src/) and tsconfig.json

v1.2.0

• 🖥️ LocHelper compiled as Universal Binary (arm64 + x86_64), supporting Intel Macs

v1.1.0

• 🔄 Changed requestLocation() to startUpdatingLocation() + auto-stop after obtaining location, more stable
• 🔁 locationUnknown (error 0) automatic backoff retry (1s → 2s → 4s, up to 3 times)
• 🛡️ Permission denied/restricted fast exit, no longer waiting for timeout
• 📝 JS side added error 0 identification and detailed troubleshooting guide

v1.0.0

• 🎉 Initial release

License

MIT