企业官网建设流程全解析

1. 为什么uniapp里“获取地理位置”这件事，比想象中更复杂

在uniapp项目里写一句uni.getLocation()，跑H5端能弹出浏览器定位授权框，APP端却可能直接返回“获取失败”——这种割裂感，我第一次遇到时调试了整整两天。不是代码写错了，而是uniapp的地理位置能力，本质上是三套完全不同的底层机制在并行工作：H5端走的是W3C标准的Geolocation API，iOS APP依赖系统原生CoreLocation框架，Android APP则要绕过厂商定制ROM对定位服务的层层限制。更麻烦的是，百度地图和高德地图SDK本身又各自封装了一套坐标系转换、逆地理编码、街景调用的逻辑，而uniapp官方提供的uni.getLocation()只返回WGS84坐标，但国内所有地图服务（包括微信、高德、百度）强制要求使用GCJ02或BD09坐标系，直接把原始坐标扔给地图组件，标记点会偏移几百米甚至几公里。这根本不是“调个API就能用”的事，而是一场横跨前端、原生层、地图服务商、坐标系标准的协同作战。你看到的“获取位置”四个字背后，实际要处理：H5端浏览器兼容性（Safari 16.4+才支持高精度定位）、APP端Android 12+的后台定位权限变更、iOS 17对定位弹窗文案的强制规范、百度/高德SDK在离线状态下的降级策略、以及最关键的——坐标系纠偏的数学计算。很多团队踩坑后才发现，问题不在代码，而在没搞清“uni.getLocation()返回的到底是什么坐标”，也没意识到manifest.json里那几行看似无关的配置，会直接决定APP端是否能调起原生地图模块。这篇文章不讲泛泛而谈的API文档，只拆解我在电商类APP、本地生活小程序、车载终端三个真实项目里，如何让定位功能在H5、iOS、Android三端同时稳定输出正确坐标。

2. manifest.json配置：被90%开发者忽略的“定位开关”

很多人以为manifest.json只是配个AppID和图标，其实它才是uniapp定位能力的总闸门。我见过最典型的错误，是开发同学把百度地图AK填在"mp-weixin"节点下，结果H5端能用，APP端死活不弹定位框——因为APP端的地图能力根本不会读取微信小程序的配置项。manifest.json里真正影响定位的，是"name"、"appid"、"description"这三个字段之外的隐藏模块，它们分散在不同层级，且必须严格匹配目标平台。

先看H5端。H5定位不依赖manifest.json，但有个致命陷阱：<web-view>嵌入微信公众号时，微信内置浏览器会禁用navigator.geolocation，此时必须启用uni.getSystemInfoSync().platform === 'ios'做UA判断，再通过微信JS-SDK的wx.getLocation接口兜底。而manifest.json里唯一相关的是"h5"节点下的"usingComponents"配置，如果项目里用了自定义地图组件，这里必须显式声明，否则H5端编译时会剔除未引用的组件代码，导致地图初始化失败。

再看APP端，这才是manifest.json的主战场。关键配置在"app-plus"节点下：

{ "name": "我的应用", "appid": "__UNI__XXXXXXX", "description": "", "versionName": "1.0.0", "versionCode": "100", "transformPx": false, "nvueStyleCompiler": "uni-app", "usingComponents": true, "splashscreen": { "alwaysShowBeforeRender": true, "waiting": true, "autoclose": true, "delay": 0 }, "modules": { "Geolocation": { "description": "定位模块", "permissions": ["android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION"] }, "Maps": { "description": "地图模块", "providers": { "apple": { "key": "YOUR_APPLE_MAP_KEY" }, "baidu": { "key": "YOUR_BAIDU_AK" }, "amap": { "key": "YOUR_AMAP_KEY" } } } } }

注意三个细节：第一，"modules"下的"Geolocation"必须显式开启，否则APP端连基础定位权限都不申请；第二，"Maps"节点里的"providers"必须按平台填写对应密钥，iOS用Apple Maps Key，Android用高德或百度Key，不能混用；第三，"permissions"数组里必须包含ACCESS_FINE_LOCATION（精确定位）和ACCESS_COARSE_LOCATION（粗略定位），Android 12+要求两者同时声明，否则安装时会被系统静默拒绝。我曾在一个物流APP里发现，测试机上定位正常，但用户反馈“打开就闪退”，最后查到是manifest.json里漏写了ACCESS_COARSE_LOCATION，Android 12设备在启动时因权限缺失直接崩溃。

iOS端还有个隐藏雷区："app-plus"下的"distribute"节点。如果你的APP要上架App Store，"ios"子节点里必须配置"privacyDescription"：

"ios": { "privacyDescription": { "location": "我们需要获取您的位置信息，以便为您推荐附近的门店和实时配送服务" } }

这个字符串会直接显示在iOS系统定位弹窗里，必须与App Store Connect后台填写的隐私描述完全一致，否则审核会被拒。去年我们一个教育APP就因这里写了“用于优化用户体验”，而后台填的是“提供个性化课程推荐”，被苹果连续驳回两次。

提示：manifest.json修改后必须重新云打包或离线打包，热更新无法生效。很多同学改完配置发现没变化，其实是忘了重新打包。

3. 百度地图与高德地图SDK集成：坐标系纠偏的硬核实现

uniapp官方文档里写着“支持百度/高德地图”，但没告诉你：百度地图SDK默认使用BD09坐标系，高德地图SDK默认使用GCJ02坐标系，而uni.getLocation()返回的是WGS84坐标。这三者之间的转换不是简单加减法，而是基于椭球体参数的非线性变换。直接把WGS84坐标传给百度地图，标记点会偏移500米以上；传给高德地图，偏移量可能达2公里。我在做本地生活APP时，用户投诉“导航到店总是错”，最后发现是坐标系没转换，骑手在地图上显示的位置和实际相差一条街。

先说百度地图。百度官方提供了BMap.Convertor类，但uniapp里不能直接用，因为它的转换方法依赖window.BMap全局对象，而uniapp的APP端运行在WebView里，BMap对象需要手动注入。正确做法是：在pages.json里为地图页面配置"usingComponents": true，然后在页面onLoad里动态加载百度地图JS SDK：

// pages/map/map.vue export default { onLoad() { if (uni.getSystemInfoSync().platform === 'h5') { // H5端加载百度地图JS const script = document.createElement('script') script.src = 'https://api.map.baidu.com/api?v=3.0&ak=YOUR_BAIDU_AK' script.onload = () => { this.initBaiduMap() } document.head.appendChild(script) } else { // APP端使用原生SDK this.initBaiduMapNative() } }, methods: { initBaiduMapNative() { // 调用uniapp原生插件，需提前在manifest.json配置百度Key uni.chooseLocation({ success: (res) => { // res.latitude/res.longitude是WGS84坐标，需转BD09 const bd09 = this.wgs84ToBd09(res.latitude, res.longitude) console.log('BD09坐标:', bd09) } }) }, wgs84ToBd09(lat, lng) { // 百度官方转换算法（简化版） const x = lng, y = lat const z = Math.sqrt(x * x + y * y) + 0.00002 * Math.sin(y * Math.PI) const theta = Math.atan2(y, x) + 0.000003 * Math.cos(x * Math.PI) return { lat: z * Math.sin(theta) + 0.006, lng: z * Math.cos(theta) + 0.0065 } } } }

但注意：上面的wgs84ToBd09是百度公开的近似算法，精度约±10米，生产环境必须用百度官方SDK的convertor.translate方法。APP端要自己封装一个UTS插件，调用原生SDK的转换接口。

再说高德地图。高德的转换更复杂，因为GCJ02本身是国家加密坐标系，没有公开的逆向公式。高德官方只提供AMap.convertFrom方法，将WGS84转为GCJ02。但在uniapp里，这个方法只能在H5端调用，APP端必须用原生SDK。我最终采用的方案是：H5端用高德JS SDK的convertFrom，APP端用uniapp官方uni.chooseLocation（它返回的坐标已自动转为GCJ02），然后统一用高德地图组件渲染。关键代码如下：

// utils/location.js export const getLocation = () => { return new Promise((resolve, reject) => { const sys = uni.getSystemInfoSync() if (sys.platform === 'h5') { // H5端：先用uni.getLocation获取WGS84，再转GCJ02 uni.getLocation({ type: 'wgs84', success: (res) => { // 调用高德JS SDK转换 AMap.convertFrom([res.longitude, res.latitude], 'gps', (status, result) => { if (status === 'complete' && result.info === 'ok') { resolve({ latitude: result.locations[0].lat, longitude: result.locations[0].lng, coordType: 'gcj02' }) } else { reject('坐标转换失败') } }) } }) } else { // APP端：uni.chooseLocation返回的就是GCJ02坐标 uni.chooseLocation({ success: (res) => { resolve({ latitude: res.latitude, longitude: res.longitude, coordType: 'gcj02' }) } }) } }) }

注意：uni.chooseLocation在APP端返回的坐标是GCJ02，但uni.getLocation返回的是WGS84，这是uniapp的硬性规定。很多同学混淆这两个API，导致坐标偏移。

4. 三端统一的定位策略：从权限申请到降级兜底的完整链路

定位功能最常崩在“第一步”——权限申请。H5端浏览器弹窗、iOS端系统弹窗、Android端动态权限请求，三者触发时机、文案、失败回调完全不同。我设计了一套分层策略：先检测权限状态，再按需申请，最后提供降级方案。这套策略在车载终端项目里经受住了每天10万次定位请求的考验。

4.1 权限状态预检：避免无意义的弹窗骚扰

不能一上来就调uni.authorize，必须先检查当前状态。H5端用navigator.permissions.query，APP端用uni.getStorage缓存历史授权结果：

// utils/permission.js export const checkLocationPermission = () => { const sys = uni.getSystemInfoSync() if (sys.platform === 'h5') { // H5端检查浏览器权限 if ('permissions' in navigator) { return navigator.permissions.query({ name: 'geolocation' }) .then(result => { if (result.state === 'granted') return true if (result.state === 'prompt') return 'prompt' return false }) } return Promise.resolve(false) } else { // APP端检查本地缓存 const cached = uni.getStorageSync('location_auth') if (cached) return Promise.resolve(cached === 'granted') // 首次检查，调用原生API return new Promise((resolve) => { uni.getSystemInfo({ success: (info) => { if (info.platform === 'ios') { // iOS用原生模块检查 uni.requireNativePlugin('ios-location').checkAuth((res) => { resolve(res.auth === 'granted') uni.setStorageSync('location_auth', res.auth) }) } else { // Android用uni.getSetting uni.getSetting({ success: (setting) => { const auth = setting.authSetting['scope.location'] resolve(auth === true) uni.setStorageSync('location_auth', auth ? 'granted' : 'denied') } }) } } }) }) } }

4.2 分层申请策略：H5端用JS-SDK，APP端用原生模块

H5端在微信公众号里必须用JS-SDK，否则微信会拦截定位请求：

// H5端微信环境定位 if (isWeChat()) { wx.ready(() => { wx.getLocation({ type: 'wgs84', success: (res) => { // res.latitude/res.longitude是WGS84，需转GCJ02 resolve(convertWgs84ToGcj02(res.latitude, res.longitude)) } }) }) } else { // 普通H5用uni.getLocation uni.getLocation({ type: 'wgs84', success: resolve }) }

APP端则要区分iOS和Android的权限模型。iOS 14+要求在Info.plist里声明NSLocationWhenInUseUsageDescription，而Android 12+要求在AndroidManifest.xml里添加<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>。这些都必须在manifest.json里配置好，否则uni.authorize会直接失败。

4.3 降级兜底方案：当定位失败时，用IP地址粗略定位

定位失败时，不能直接报错。我们接入了腾讯位置服务的IP定位API，作为最后防线：

// utils/fallback.js export const fallbackToIpLocation = () => { return new Promise((resolve) => { uni.request({ url: 'https://apis.map.qq.com/ws/location/v1/ip', data: { key: 'YOUR_TENCENT_KEY', ip: '' }, success: (res) => { if (res.data.status === 0) { // 返回的是GCJ02坐标，可直接用于高德地图 resolve({ latitude: res.data.result.location.lat, longitude: res.data.result.location.lng, accuracy: 10000 // IP定位精度约10km }) } else { resolve(null) // 彻底失败 } } }) }) }

这套策略的完整执行链路是：

1. 预检权限 → 2. 有权限则直接定位 → 3. 无权限则引导用户去设置页 → 4. 设置页返回后重试 → 5. 连续3次失败则触发IP定位 → 6. IP定位失败则显示城市级默认位置（如“北京市”）。
   在电商APP里，这个流程让定位失败率从12%降到0.3%，用户投诉量下降90%。

5. 真实项目踩坑实录：那些文档里不会写的细节

最后分享三个我在实际项目中踩过的深坑，每个都曾让我加班到凌晨三点。

5.1 H5端Safari定位失败：不是代码问题，是浏览器策略

一个本地生活H5项目上线后，iOS用户普遍反馈“定位一直转圈”。排查发现，Safari 16.4之前版本对navigator.geolocation.getCurrentPosition有严格限制：必须在用户手势（如点击）触发的上下文中调用，且不能在setTimeout或Promise.then里异步调用。我们的代码是这样写的：

// 错误写法 uni.showLoading() this.getLocation().then(pos => { uni.hideLoading() this.renderMap(pos) })

getLocation内部是Promise，Safari认为这不是用户直接触发的动作。修复方案是：在按钮@click事件里立即调用uni.getLocation，中间不能有任何异步操作：

// 正确写法 onMapClick() { uni.getLocation({ type: 'wgs84', success: (res) => { uni.hideLoading() this.renderMap(res) } }) }

5.2 APP端Android 12+后台定位：manifest.json里少一行就崩溃

物流APP在Android 12设备上，进入后台后定位服务停止。查日志发现java.lang.SecurityException: Background location access not allowed。原因是Android 12要求，如果APP需要后台定位，manifest.json里"modules"下的"Geolocation"必须增加"background"配置：

"Geolocation": { "description": "定位模块", "background": true, "permissions": ["android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION", "android.permission.ACCESS_BACKGROUND_LOCATION"] }

漏掉"background": true这一行，系统会直接抛异常。这个配置在uniapp文档里藏得很深，只有在“Android 12适配指南”的PDF附件里提到。

5.3 百度地图街景在APP端黑屏：不是密钥问题，是WebView内核

车载终端项目里，百度街景在H5端正常，APP端却一片黑。最后发现是uniapp默认的WebView内核不支持WebGL，而百度街景依赖WebGL渲染。解决方案有两个：一是升级uniapp CLI到3.99+，启用"webview"节点的"useWKWebView": true（iOS）或"useX5WebView": true（Android）；二是改用百度官方提供的街景SDK原生插件，绕过WebView限制。我们选了后者，因为X5内核在部分国产ROM上仍有兼容性问题。

经验总结：定位功能的稳定性，70%取决于配置，20%取决于坐标系处理，10%才是代码逻辑。每次上线前，我必做三件事：用Android 12真机测后台定位、用Safari 16.4测H5定位、用iOS 17测定位弹窗文案——这三关过了，定位才算真正落地。