在网页中获取用户的实时位置，曾经需要借助IP库或者让用户手动输入地址，现在只需要调用浏览器原生的Geolocation接口就能拿到相当精确的经纬度数据。这个接口是W3C定义的标准Web API，主流浏览器包括移动端浏览器都已支持。本文从基础用法讲到进阶配置，再覆盖错误处理和实际落地时的注意事项，带你完整走一遍JavaScript地理位置API的使用流程。
一、Geolocation API的基础用法
地理位置API的入口挂在navigator.geolocation对象上。在使用之前，建议先做一次特性检测，避免老版本浏览器直接报错：
if ('geolocation' in navigator) {
console.log('当前浏览器支持地理位置API');
} else {
console.log('抱歉，您的浏览器不支持定位功能');
}最常用的方法是getCurrentPosition，它接收一个成功回调、一个可选的失败回调，以及一个可选的配置对象。调用这个方法时，浏览器会先弹出权限询问框，用户点击允许后才会执行回调，把位置对象传进来。
navigator.geolocation.getCurrentPosition(
function(position) {
const lat = position.coords.latitude; // 纬度
const lng = position.coords.longitude; // 经度
const accuracy = position.coords.accuracy; // 精度（米）
console.log('纬度：' + lat + '，经度：' + lng + '，精度：' + accuracy + '米');
},
function(error) {
console.log('定位失败，错误码：' + error.code);
}
);成功回调拿到的position对象包含两个关键属性：coords和timestamp。coords里除了经纬度和精度外，还可能有海拔altitude、海拔精度altitudeAccuracy、行进方向heading以及速度speed，不过这些字段只有在设备支持且权限允许时才有值，否则为null，使用前一定要做空值判断。timestamp是一个时间戳，表示位置信息获取的时间，可以用来判断数据的新鲜程度。
需要注意的是，getCurrentPosition是异步操作，不要期望调用后立刻拿到结果。在回调触发之前页面可以正常执行其他逻辑，如果业务上必须等待定位结果，可以用Promise把回调包装一层：
function getPosition() {
return new Promise(function(resolve, reject) {
navigator.geolocation.getCurrentPosition(resolve, reject);
});
}
async function showLocation() {
try {
const pos = await getPosition();
console.log(pos.coords.latitude, pos.coords.longitude);
} catch (e) {
console.log('定位失败：' + e.message);
}
}二、精确定位与持续监听的配置技巧
第三个参数是一个配置对象，包含三个常用选项。第一个是enableHighAccuracy，设置为true时浏览器会优先使用GPS、WiFi三角定位等高精度方式，代价是响应变慢且更耗电，适合步行导航类场景；默认的false则采用低功耗的粗略定位，适合天气展示、附近推荐这类对精度要求不高的业务。
第二个是timeout，单位毫秒，表示最长等待时间，超时后会触发错误码为3的错误。第三个是maximumAge，表示可以接受多久以内的缓存位置，比如设置为60000就表示一分钟内缓存的定位结果可以直接返回，不必重新发起定位请求，这在频繁获取位置的场景下能显著减少开销：
const options = {
enableHighAccuracy: true, // 追求高精度
timeout: 10000, // 最多等10秒
maximumAge: 0 // 不使用缓存，每次都重新定位
};
navigator.geolocation.getCurrentPosition(onSuccess, onError, options);如果要持续追踪位置变化，比如外卖配送、跑步记录这类需求，应该用watchPosition。它的参数和getCurrentPosition完全一致，区别在于它会注册一个监听器，只要设备位置发生显著变化就触发回调。返回值是一个监听器ID，不需要追踪时调用clearWatch传入这个ID即可取消监听：
const watchId = navigator.geolocation.watchPosition(
function(position) {
// 每次位置更新都会执行这里
console.log('新位置：', position.coords.latitude, position.coords.longitude);
},
function(error) {
console.log('监听失败：', error.message);
},
{ enableHighAccuracy: true, timeout: 15000, maximumAge: 5000 }
);
// 页面卸载或不需要时记得清除
navigator.geolocation.clearWatch(watchId);在移动端使用watchPosition时要特别注意耗电问题，长时间开启高精度监听会让手机电量快速下降。建议根据业务场景动态调整：进入前台需要精确追踪时开启，切换到后台或者用户停止操作时及时清除监听。
三、错误处理与常见踩坑点
失败回调接收一个PositionError对象，它有三个属性：code是错误码，message是错误描述，PERMISSION_DENIED等常量也可以直接在对象上访问。错误码的含义分别是：1表示用户拒绝了授权，2表示位置不可用（比如设备定位服务未开启），3表示请求超时。针对不同的错误码给出不同的提示，用户体验会好很多：
function handleError(error) {
switch (error.code) {
case error.PERMISSION_DENIED:
alert('您拒绝了定位授权，请在浏览器设置中允许后重试');
break;
case error.POSITION_UNAVAILABLE:
alert('暂时无法获取位置信息，请检查设备定位服务是否开启');
break;
case error.TIMEOUT:
alert('定位超时，请稍后重试');
break;
default:
alert('未知错误：' + error.message);
}
}有几个非常常见的坑需要提前了解。第一，Geolocation API要求安全上下文，也就是说页面必须通过HTTPS访问（localhost被视为安全环境），在HTTP页面里navigator.geolocation会直接是undefined，本地开发时如果遇到接口不存在，先检查协议。第二，部分浏览器对权限记忆有时效性，用户之前允许过不代表永远有效，代码里始终要写好失败分支。第三，定位失败不代表API有问题，手机上可能是系统级定位开关被关闭，桌面浏览器则依赖WiFi和IP，精度可能差出几公里，必要时应该在界面上展示精度值让用户知情。
拿到经纬度之后，通常还要结合第三方地图服务做可视化展示。以接入地图JS SDK为例，把坐标传给地图初始化函数即可：
// 假设页面已加载某地图SDK
navigator.geolocation.getCurrentPosition(function(position) {
const center = [
position.coords.longitude,
position.coords.latitude
];
// 将用户位置标注到地图上（示意代码，具体以所用SDK文档为准）
// map.setCenter(center);
// map.addMarker(center);
});最后提醒一点，坐标体系存在差异。浏览器返回的是WGS84坐标系（GPS原始坐标），而国内地图服务大多使用GCJ02或BD09坐标系，直接把WGS84坐标标注到国内地图上会有几百米的偏移，需要先做坐标系转换，这一点在做地图相关功能时几乎是必踩的坑，提前处理好可以省去不少排查时间。
地理位置APIGeolocationJavaScript定位修改时间：2026-09-13 08:34:29