定位失败不再卡壳Geolocator.js的GeoError错误码与处理策略完整清单【免费下载链接】geolocatorA utility for getting geo-location information via HTML5 and IP look-ups, geocoding, address look-ups, distance and durations, timezone information and more...项目地址: https://gitcode.com/gh_mirrors/ge/geolocator在使用 Geolocator 获取用户定位时定位失败是新手最常遇到的场景权限被拒绝、网络超时、API 密钥失效……而 Geolocator.js 提供的GeoError 错误码体系正是把五花八门的失败原因统一成一套通用语言。本文带来一份完整的 GeoError 错误码清单与处理策略帮你快速看懂每一个错误、写出稳健的定位功能。为什么需要 GeoErrorGeolocator 内部整合了 HTML5 Geolocation、IP 定位、Google 地理编码等多种定位源不同来源返回的错误格式各不相同。GeoError 类 将所有回调和抛出的异常统一为同一个错误对象你只需要检查一个code属性就能知道到底哪里出了问题。它对外通过geolocator.Error暴露核心成员有code错误码如TIMEOUT、PERMISSION_DENIEDmessage错误描述create(err)把任意错误对象/字符串转换为 GeoErrorfromResponse(response)把 Google API 的响应体解析成 GeoErrorisGeoError(err)判断一个值是否为 GeoError 实例相关测试用例可参考 test/geoerror.spec.js它验证了GeoError同时是Error的子类instanceof判断始终可靠。19 个 GeoError 错误码完整清单全部错误码定义在 src/core/geo.error.js 中按来源可以分为四大类。定位源相关定位拿不到错误码含义常见原因GEOLOCATION_NOT_SUPPORTED浏览器不支持 HTML5 定位 API老版本浏览器或非 HTTPS 环境PERMISSION_DENIED用户拒绝了定位权限浏览器弹窗点了拒绝POSITION_UNAVAILABLE无法获取位置GPS 信号弱、模拟器无定位TIMEOUT超过timeout配置仍未定位成功室内、高楼密集区INVALID_GEO_IP_SOURCEIP 定位源未设置或无效自定义 Geo-IP 源地址错误请求与参数相关请求本身有问题错误码含义常见原因INVALID_PARAMETERS请求参数无效缺经纬度、地址为空INVALID_REQUEST查询内容缺失地理编码时没传地址INVALID_RESPONSE服务返回了无法解析的响应接口变更、代理截断REQUEST_FAILED请求发出后失败XHR 网络错误NOT_FOUND找不到资源也涵盖ZERO_RESULTSPARSE_ERROR请求体不是合法 JSON序列化出错配额与密钥相关Google API 特有错误码含义常见原因REQUEST_DENIED请求被服务拒绝缺 API key、用了 HTTPGOOGLE_KEY_INVALIDAPI 密钥无效key 复制不完整、未开通计费OVER_QUERY_LIMIT超出配额调用量太大DAILY_LIMIT_EXCEEDED超出日限额当天请求过多USER_RATE_LIMIT_EXCEEDED超出单用户每秒限流高频轮询定位GOOGLE_API_FAILEDGoogle API 加载失败网络屏蔽、CDN 故障距离矩阵与兜底错误码含义MAX_ELEMENTS_EXCEEDED起点×终点总数超过单次上限MAX_DIMENSIONS_EXCEEDED起点或终点超过 25 个MAX_WAYPOINTS_EXCEEDED途经点过多INTERNAL_ERROR内部错误如跨域 XHR 失败UNKNOWN_ERROR未知错误默认兜底值 小技巧不确定某个字符串是否为合法错误码时可以用GeoError.isValidErrorCode(code)校验避免手滑写错码值。如何快速定位错误来源HTML5 定位错误数字码自动映射浏览器原生定位失败的err.code是数字1/2/3GeoError 会自动帮你翻译成标准错误码映射逻辑见 GeoError.create1→PERMISSION_DENIED2→POSITION_UNAVAILABLE3→TIMEOUT所以你在回调里永远拿到的都是上面清单里的字符串错误码不用再关心浏览器原生数字。Google API 错误状态与 reason 双通道解析Google 各接口报错结构不统一——有的返回status字符串有的返回error.errors[].reason。GeoError.fromResponse 会按顺序解析两种结构其中 reason 的映射关系定义在 errorCodeFromReasonGoogle reason对应 GeoError 错误码invalidINVALID_REQUESTkeyInvalidGOOGLE_KEY_INVALIDdailyLimitExceededDAILY_LIMIT_EXCEEDEDuserRateLimitExceededUSER_RATE_LIMIT_EXCEEDEDnotFoundNOT_FOUNDparseErrorPARSE_ERROR推荐的 3 步错误处理策略在实际代码里可参考 example/js/example.js 的写法建议按判断 → 分流 → 兜底三步处理判断回调第一个参数非空即代表失败先用geolocator.Error.isGeoError(err)确认类型分流用err.code做switch分支权限类错误提示用户开权限配额类错误做降级其余记录日志兜底对无法识别的错误统一展示err.message保证界面永不卡壳。geolocator.locate(function (err, location) { if (err) { if (err.code PERMISSION_DENIED) { /* 引导用户开启定位权限 */ } else if (err.code TIMEOUT) { /* 延长超时或改用 IP 定位 */ } else { console.error(err); } return; } // 使用 location ... });其中locate的完整行为与错误抛出时机可查阅 src/core/geolocator.jsError属性的暴露位置见 geolocator.js。避坑指南新手最容易踩的 3 个坑HTTPS 坑HTML5 定位和 Google API 都要求安全环境HTTP 页面会直接报REQUEST_DENIED或GEOLOCATION_NOT_SUPPORTED。配额坑OVER_QUERY_LIMIT和DAILY_LIMIT_EXCEEDED不是代码 bug是用超了。生产环境务必加上前端限流 后端配额监控。兜底坑不要把UNKNOWN_ERROR当普通失败展示。它是所有无法识别错误的归口出现频率高时说明有未覆盖的异常源应回溯err.message补充分支。 掌握这份清单后任何定位失败都能在一分钟内定位到原因。完整的枚举定义、API 端点常量还可继续参考 src/core/enums.js帮助你排查定位源层面的问题。【免费下载链接】geolocatorA utility for getting geo-location information via HTML5 and IP look-ups, geocoding, address look-ups, distance and durations, timezone information and more...项目地址: https://gitcode.com/gh_mirrors/ge/geolocator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考