浏览器Geolocation API是Web开发中用于获取用户设备地理位置的原生接口，它基于设备的定位能力（如GPS、WiFi、基站等）返回位置相关数据，开发者可以通过简单的JavaScript调用实现位置获取功能，无需依赖额外的第三方定位服务。
Geolocation API基础调用方法
Geolocation API挂载在浏览器全局对象navigator的geolocation属性下，最核心的两个方法是getCurrentPosition和watchPosition，前者用于获取一次位置，后者用于持续监听位置变化。
获取单次位置
getCurrentPosition方法接收三个参数：成功回调函数、失败回调函数、可选的配置参数对象，基本使用示例如下：
// 检查浏览器是否支持Geolocation API
if ('geolocation' in navigator) {
// 调用获取位置方法
navigator.geolocation.getCurrentPosition(
// 成功回调，接收位置对象
function(position) {
const latitude = position.coords.latitude; // 纬度
const longitude = position.coords.longitude; // 经度
const accuracy = position.coords.accuracy; // 位置精度，单位米
console.log('获取位置成功：');
console.log('纬度：' + latitude);
console.log('经度：' + longitude);
console.log('精度：' + accuracy + '米');
},
// 失败回调，接收错误对象
function(error) {
console.log('获取位置失败，错误码：' + error.code);
console.log('错误信息：' + error.message);
},
// 可选配置参数
{
enableHighAccuracy: true, // 是否启用高精度定位，默认false
timeout: 10000, // 定位超时时间，单位毫秒，默认Infinity
maximumAge: 0 // 缓存位置的最大时长，单位毫秒，默认0
}
);
} else {
console.log('当前浏览器不支持Geolocation API');
}
持续监听位置变化
如果需要实时获取用户的位置变化，比如运动轨迹记录场景，可以使用watchPosition方法，它的参数和getCurrentPosition一致，会返回一个监听ID，后续可以通过clearWatch方法停止监听：
let watchId = null;
if ('geolocation' in navigator) {
// 开始监听位置变化
watchId = navigator.geolocation.watchPosition(
function(position) {
console.log('位置更新：');
console.log('纬度：' + position.coords.latitude);
console.log('经度：' + position.coords.longitude);
console.log('速度：' + position.coords.speed + '米/秒');
},
function(error) {
console.log('监听位置失败：' + error.message);
},
{
enableHighAccuracy: true,
timeout: 5000
}
);
// 10秒后停止监听
setTimeout(function() {
if (watchId !== null) {
navigator.geolocation.clearWatch(watchId);
console.log('已停止位置监听');
}
}, 10000);
}
位置对象属性说明
成功回调接收到的position对象包含两个核心属性：coords和timestamp，其中coords是位置坐标相关的详细信息，具体属性如下：
| 属性名 | 说明 | 单位 |
|---|---|---|
| latitude | 纬度值 | 度 |
| longitude | 经度值 | 度 |
| accuracy | 经纬度的精度 | 米 |
| altitude | 海拔高度，不支持时返回null | 米 |
| altitudeAccuracy | 海拔高度的精度，不支持时返回null | 米 |
| heading | 移动方向，正北方向顺时针角度，不支持时返回null | 度 |
| speed | 移动速度，不支持时返回null | 米/秒 |
常见错误处理
调用Geolocation API时可能因为权限问题、设备不支持、定位超时等原因失败，失败回调的error对象包含code和message两个属性，code的取值对应的错误类型如下：
- 1（PERMISSION_DENIED）：用户拒绝了位置权限申请
- 2（POSITION_UNAVAILABLE）：无法获取位置信息，比如设备没有定位能力
- 3（TIMEOUT）：定位请求超时
针对不同的错误类型，可以给出对应的用户提示，优化用户体验：
function handleGeolocationError(error) {
switch(error.code) {
case error.PERMISSION_DENIED:
alert('您拒绝了位置权限申请，无法获取您的位置信息');
break;
case error.POSITION_UNAVAILABLE:
alert('无法获取位置信息，请检查设备定位功能是否开启');
break;
case error.TIMEOUT:
alert('定位请求超时，请稍后重试');
break;
default:
alert('获取位置时发生未知错误');
}
}
if ('geolocation' in navigator) {
navigator.geolocation.getCurrentPosition(
function(position) {
console.log('位置获取成功');
},
handleGeolocationError
);
}
使用注意事项
在实际使用Geolocation API时，需要注意以下几点：
Geolocation API仅在HTTPS协议或者本地localhost环境下可用，HTTP协议的线上环境无法调用该API，这是浏览器出于安全性的强制要求。
- 首次调用API时浏览器会自动弹出权限申请弹窗，用户允许后才会返回位置数据，不要频繁触发权限申请，避免引起用户反感
- 高精度定位会消耗更多设备电量，非必要场景不要开启
enableHighAccuracy: true配置 - 获取到的位置是设备上报的位置，可能存在一定误差，对精度要求高的场景需要结合业务逻辑做校验
Geolocation_APIJavaScript地理位置获取浏览器_API修改时间：2026-06-09 09:39:32