desktop-location-sdk

跨平台桌面端精准定位 SDK — macOS / Windows / Linux，WGS84/GCJ02 坐标，GPS 级精度。

特性

• 🖥️ 跨平台：macOS (CoreLocation) + Windows (WinRT) + Linux (Geoclue2)
• 🛰️ GPS 级精度：调用系统原生定位 API（GPS/WiFi/蜂窝混合定位）
• 🌏 WGS84 → GCJ02 坐标转换，国内打车/地图平台直接可用
• 📦 零原生编译：不用 node-gyp / N-API，用系统脚本桥接
• 🔒 预编译 Helper：macOS (LocHelper.app) + Windows (LocHelper.exe)，无需用户机器上有编译器
• 🔄 智能重试：macOS locationUnknown 自动退避重试
• 🛡️ Windows 三策略：预编译 exe（优先）→ PowerShell + WinRT → C# 现场编译（兜底）
• 🐧 Linux D-Bus：通过 Geoclue2 标准定位服务获取

安装

npm install desktop-location-sdk

使用

同步接口（macOS / Windows）

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

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

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

// 出错时抛异常
const strict = getLocation({ throwOnError: true });

异步接口（所有平台，Linux 必须使用）

import { getLocationAsync } from "desktop-location-sdk";

const loc = await getLocationAsync({ gcj02: true });
if (loc) {
  console.log(`${loc.coordSystem}  lng=${loc.longitude}  lat=${loc.latitude}`);
}

坐标转换

import { wgs84ToGcj02 } from "desktop-location-sdk";

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

平台检测

import { isPlatformSupported, getPlatformSource } from "desktop-location-sdk";

if (isPlatformSupported()) {
  console.log(getPlatformSource()); // "CoreLocation (macOS)" / "WinRT Geolocation (Windows)" / "Geoclue2 (Linux)"
}

CLI

安装后可直接运行：

npx desktop-location-sdk           # 获取 GCJ02 定位
npx desktop-location-sdk --wgs84   # 获取 WGS84 定位
npx desktop-location-sdk --json    # JSON 格式输出
npx desktop-location-sdk --async   # 异步模式（Linux 必须）

输出：

定位引擎: CoreLocation (macOS)
正在获取定位...

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

API

getLocation(options?)

同步获取本机经纬度（macOS / Windows）。

| 参数 | 类型 | 默认 | 说明 | | ----------------- | ----------------- | -------- | -------------------------------------------------- | | gcj02 | boolean | true | 返回 GCJ02（国内平台用）。false 则返回原始 WGS84 | | timeoutMs | number | 90000 | 定位超时（毫秒） | | throwOnError | boolean | false | 失败时是否抛错。false 时失败返回 null | | desiredAccuracy | "best" \| "low" | "best" | 精度偏好：best = GPS/WiFi 最高精度 |

getLocationAsync(options?)

异步获取本机经纬度（所有平台）。Linux 必须使用此接口。

参数同 getLocation。

返回值 Location

interface Location {
  latitude: number; // 纬度
  longitude: number; // 经度
  accuracy?: number; // 水平精度（米）
  altitude?: number; // 海拔（米）— Windows/Linux 可提供
  speed?: number; // 速度（m/s）— Windows/Linux 可提供
  heading?: number; // 方向（度）— Windows 可提供
  coordSystem: "wgs84" | "gcj02";
  source: "corelocation" | "winrt" | "geoclue2" | "fallback";
}

各平台定位授权

macOS

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

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

Windows

首次运行时 Windows 弹出定位授权弹窗，点击「允许」即可。

权限管理：设置 → 隐私和安全性 → 位置 → 允许应用访问你的位置

前提：Windows 10 1607+ (版本 14393+)

Linux

由桌面环境管理定位授权。

• GNOME：设置 → 隐私 → 位置服务 → 开启
• KDE：系统设置 → 位置 → 开启

前提：Geoclue2 服务已安装并运行。

各平台实现原理

macOS — CoreLocation

通过预编译 LocHelper.app 调用 CoreLocation API。三级查找策略：

1. 预编译版本（prebuilt/LocHelper.app）— 随 npm 包分发，无需编译器
2. 用户缓存（~/.lochelper/）— 之前已编译过
3. 现场编译 — 需要 Xcode Command Line Tools

CoreLocation 混合定位：

• Wi-Fi：扫描周围 AP 的 BSSID，对照 Apple 位置数据库（室内主力，精度 ~50m）
• GPS/GNSS：有定位芯片的设备
• 蓝牙信标（iBeacon 等）

Windows — WinRT Geolocation

通过 LocHelper.exe 调用 WinRT Windows.Devices.Geolocation API。三级策略：

1. 预编译 exe（prebuilt/LocHelper.exe）— 随 npm 包分发，最可靠，不依赖 PowerShell/csc.exe
2. PowerShell + WinRT — 通用性最广，直接调用 WinRT API
3. 现场编译 C# LocHelper.exe — 需要 csc.exe，作为兜底方案

定位来源：

• GPS：USB/蓝牙 GPS 接收器（精度 ~5m）
• Wi-Fi：对照 Microsoft 位置数据库（精度 ~50m）
• 蜂窝：基站定位（精度 ~300m）

Linux — Geoclue2

通过 D-Bus 调用 Geoclue2（freedesktop.org 标准定位服务）：

• GPS：通过 gpsd 或 ModemManager（精度 ~5m）
• Wi-Fi：对照 Mozilla Location Service（精度 ~50m）
• 蜂窝：ModemManager 基站定位

常见问题

macOS: kCLErrorDomain error 0（locationUnknown）

定位权限已授权但定位数据暂不可用：

1. Wi-Fi 未开启 — Mac 主要靠 Wi-Fi 扫描定位
2. 网络不通 — Wi-Fi 定位需要联网查询 Apple 位置数据库
3. 定位服务总开关未开 — 系统设置 → 隐私与安全性 → 定位服务

v1.0.0+ 自动对 error 0 进行退避重试（1s → 2s → 4s，最多 3 次）。

Windows: WinRT 不可用

需要 Windows 10 1607+。SDK 会依次尝试预编译 exe → PowerShell + WinRT → C# 现场编译，自动选择可用方案。

Windows: LocHelper.exe 缓存过期

SDK 会在 %LOCALAPPDATA%\lochelper\version.txt 记录版本号。版本不匹配时自动清除旧缓存并重新编译。

Linux: Geoclue2 未安装

# Debian/Ubuntu
sudo apt install geoclue-2.0

# Fedora
sudo dnf install geoclue2

# Arch
sudo pacman install geoclue

Linux: gdbus 不可用

# Debian/Ubuntu
sudo apt install libglib2.0-dev-bin

# Fedora
sudo dnf install glib2

# Arch
sudo pacman install glib2

与 npm上 mac-location-sdk包 的关系

本包是 mac-location-sdk 的跨平台升级版：

• macOS 行为与 mac-location-sdk 完全一致
• 新增 Windows (WinRT) 和 Linux (Geoclue2) 支持
• API 兼容，可直接替换 import

开发

# 构建
npm run build

# 重新预编译 macOS LocHelper（需要 Xcode，macOS only）
npm run prebuild-helper

# 重新预编译 Windows LocHelper.exe（需要 .NET SDK，Windows only）
npm run prebuild-windows-helper

# 类型检查
npm run typecheck

预编译产物说明

| 平台 | 产物 | 位置 | 构建命令 | 构建环境要求 | |------|------|------|----------|------------| | macOS | LocHelper.app | prebuilt/LocHelper.app/ | npm run prebuild-helper | Xcode Command Line Tools | | Windows | LocHelper.exe | prebuilt/LocHelper.exe | npm run prebuild-windows-helper | .NET Framework 4+ 或 .NET SDK | | Linux | 无（纯 CLI 调用 gdbus） | — | — | — |

跨平台构建提示：Windows 的 LocHelper.exe 只能在 Windows 上编译（依赖 Windows SDK）。macOS/Linux 开发者可使用 GitHub Actions CI 在 Windows runner 上构建。用户端即使没有预编译 exe，SDK 也会自动 fallback 到 PowerShell 或运行时编译。

License

MIT