uni-app打包H5钉钉定位失效？dd.getLocation鉴权与排查全攻略

如果你也用 HBuilderX 写 uni-app 项目，最后打包成 H5 塞进钉钉里做工作台应用，那你大概率迟早会碰上一次这种诡异组合：本地起服务调试点定位，经纬度秒回；同样的代码打包部署到服务器后，在钉钉里dd.getLocation要么一直转圈不回调，要么直接抛一个鉴权失败的错误。我前阵子刚把这个问题从头到尾走了一遍，从怀疑自己代码写错，到怀疑 HBuilderX 打包配置有问题，最后才反应过来——根子不在前端逻辑，而在钉钉 JSAPI 那一整套环境判定和鉴权流程。这篇文章把我完整的排查思路、踩过的坑、以及最终能直接落地的代码方案整理出来，给后面做 uni-app + 钉钉 H5 集成的同学省点时间。

1. 现象复盘：本地正常、线上定位失效，我经历了什么

1.1 我遇到的具体情况

项目背景很简单：用 HBuilderX 建了一个 uni-app 工程，面向移动端的 H5 页面，功能里需要拿到用户当前经纬度。因为最终要部署成钉钉内部的 H5 微应用，所以定位不能走普通网页的navigator.geolocation，而是按钉钉官方文档接入了dd.getLocation。

本地开发的时候，我用 HBuilderX 内置浏览器跑项目，定位按钮点下去，大概一两秒就拿到经纬度了，表现完全正常。于是很放心地走了一趟 HBuilderX 的“发行 -> 网站 H5 手机版”，把产物打包上传到服务器，然后在手机钉钉里打开，结果：

• 页面能加载出来，说明资源路径、nginx 都没大问题；
• 点击定位按钮，加载状态转了半天，没有 success 也没有 fail 回调；
• 控制台里能看到类似“鉴权失败”“invalid signature”之类的错误；
• 偶尔有一次是直接报dd is not defined。

这里要特别强调一个细节：我当时用的是“手机钉钉扫码打开 URL”这种方式，不是通过钉钉工作台里的微应用入口。这两种方式本身不冲突，但排查方向会有一点差别。扫码打开的页面，URL 是浏览器地址栏里完整的地址，钉钉的 JSAPI 鉴权依赖的也是这个地址；而通过工作台进入微应用时，钉钉可能会在 URL 上附加一些参数，鉴权规则一样，只是你更容易忽略真实的location.href到底是什么。

1.2 为什么“本地正常”是个陷阱

我相信很多人和我一样，第一反应不是去查钉钉鉴权，而是怀疑打包过程出了问题。毕竟“本地一切正常”这个信号太有迷惑性了。

但仔细想想，本地正常其实分两种情况：

第一种，你在浏览器里跑，window.dd这个东西压根就不存在。你写的代码如果是这样：

if (window.dd) { dd.getLocation({...}); } else { uni.getLocation({...}); }

那在本地浏览器调试时，永远走的是else分支里的uni.getLocation，而uni.getLocation在 H5 端底层会调用浏览器定位或高德 Web 定位，本地网络环境下当然秒回结果。这个“正常”其实和钉钉一点关系都没有。

第二种，你觉得自己在钉钉环境里测试了——比如用手机钉钉打开局域网地址http://192.168.1.100:8080。这种确实是在钉钉容器里，但dd.getLocation能不能用，不完全取决于你是不是在钉钉里打开，还取决于你有没有做完整的dd.config鉴权、签名 URL 是否和当前页面 URL 一致、域名是否已经在钉钉后台配置进白名单。本地局域网环境往往第一步就不满足，所以这种“测试”也测不出正确结论。

换句话说，dd.getLocation是一个强依赖环境的 API。本地“正常”不仅不能说明部署没问题，反而容易让你跳过真正该检查的环节。这也是我写这篇文章最想先讲清楚的一件事：在做钉钉 JSAPI 集成的时候，“本地正常”这句话基本没有参考价值，真正的验证环境只有一个——钉钉容器 + 线上 URL + 正确签名。

2. 拆穿“本地正常”的假象：钉钉JSAPI的鉴权前置条件

2.1 dd.config 的五个参数从哪来

在钉钉里调用dd.getLocation，和调用钉钉的其他 JSAPI 一样，第一步不是调 API 本身，而是先做一次鉴权初始化：

dd.config({ agentId: '你应用的 agentId', corpId: '你企业的 corpId', timeStamp: 1720000000000, nonceStr: '随机字符串', signature: '服务端生成的签名', jsApiList: ['getLocation'] });

这五个参数，我拆开说一下：

• corpId：企业 ID，在钉钉开放平台后台的企业信息里能看到，一个企业一个，基本不变。
• agentId：应用 ID，你创建的那个企业内部应用有自己的agentId，在应用详情页能看到。
• timeStamp：发起签名时的毫秒级时间戳。它必须和服务端生成签名时用的一致，而且不能和钉钉服务器当前时间偏差太大，否则会报时间戳错误。
• nonceStr：随机字符串，后端生成签名时用到的同一个随机串，一般用 UUID 或者随机算法生成。
• signature：通过jsapi_ticket+nonceStr+timeStamp+当前页面URL按固定规则拼接后做 SHA1 得到的一个签名值。
• jsApiList: 声明你当前页面要调用哪些钉钉 JSAPI。这里要注意大小写，钉钉文档里写的是getLocation，不要写成getlocation或者location。

很多第一次接的人会以为signature是钉钉后台固定给的，或者以为每次配置都一样。实际上它不是静态的，它和“当前页面 URL”强绑定。你部署到了服务器，URL 从http://192.168.1.100:8080变成了https://yourdomain.com/h5/index.html，签名就必须重新生成。如果代码里写死了某个环境的 URL，到线上必然会失败。

2.2 签名用的 URL 和页面实际 URL 不一致的坑

这是我在排查过程中发现的第一个真正的坑。钉钉官方文档要求：生成签名的 URL 必须是当前页面的完整 URL，但要去掉#及其后面的部分。

比如你的页面地址是：

https://yourdomain.com/h5/index.html#/pages/map/location

参与签名的 URL 必须是：

https://yourdomain.com/h5/index.html

就这么一个细节，很多人会写错。常见写法有三种：

// 正确：直接取 location.href 然后去掉 # 部分 const url = location.href.split('#')[0]; // 错误：自己拼 origin + pathname const url = location.origin + location.pathname + location.search; // 错误：取完整 href 没去 # const url = location.href;

为什么不要用location.origin拼接？因为如果部署环境经过了 nginx 的二级转发、代理或者 URL 重写，浏览器地址栏里的 URL 和服务器内部拿到的 URL 可能不一样。最保险的做法永远是直接把location.href.split('#')[0]当作当前 URL，传到后端去生成签名。

另外，如果你的 uni-app 项目用的是默认的 hash 路由模式，那location.href的变化只发生在#后面，签名 URL 不受影响，这是好事。但如果你把pages.json里的路由模式改成了 history 模式，每个页面路径都是真实的 URL 路径，那签名 URL 每个路由都会变，必须在路由跳转后重新拉取签名并重新执行dd.config。

2.3 钉钉开发者后台的 JSAPI 安全域名配置

还有一个容易漏掉的配置，藏在钉钉开发者后台里。在应用详情页找到“开发管理 -> 安全设置”，里面有一个“JSAPI 安全域名”的配置项。这里的规则我直接说重点：

• 必须填域名，不带协议、不带路径，比如yourdomain.com；
• 支持泛域名，比如*.yourdomain.com；
• 配置保存后不是瞬时生效，有时候要等一两分钟；
• 如果前端页面使用的域名和这里配置的不一致，dd.config一样会失败。

这个安全域名的校验是钉钉 JSAPI 鉴权链路里的一环，但它不是万能的——它只验证域名归属。所以哪怕你在后台配好了域名，签名里的 URL 不对，或者协议不是 HTTPS，照样会挂。

说到 HTTPS，这也是一个必须强调的前置条件。钉钉内置浏览器对非 HTTPS 的页面有很强的限制，尤其是涉及定位、录音、相机这类敏感能力的 JSAPI，HTTP 环境下大概率被拦截或者直接返回错误。我之前有一次排查了很久，最后发现测试环境的服务器只开了 80 端口，访问地址是http://，钉钉里怎么调dd.getLocation都没反应。切到 HTTPS 之后，问题消失。

3. 从服务器到浏览器：线上定位失败的完整排查链路

3.1 第一层：先判断页面到底是不是在钉钉容器里

接到“部署后定位失败”的反馈，我建议你别急着看签名、看代码，先确认一个最底层的事情：页面到底是不是真的跑在钉钉容器里。

怎么判断？看userAgent即可：

const isDingTalk = /dingtalk/i.test(navigator.userAgent);

如果你在 PC Chrome 里模拟手机 UA，然后强行引入dingtalk.open.js，window.dd可能会存在，但dd.config之后dd.ready永远不会触发，因为钉钉容器特有的桥接方法不存在。这个判断可以作为你封装定位工具的第一个过滤器。

我当时遇到的情况比较特殊：测试同事说“我是在钉钉里打开的呀”，结果一查 UA，发现他用的其实是钉钉 PC 版的某个浏览器内核，而不是移动端的钉钉 WebView。钉钉内置浏览器的 UA 里确实包含 DingTalk 标记，但同一句话在不同平台上表现可能不一样。所以不要拿别人的“感觉”当结论，自己打印一次 UA 最靠谱。

3.2 第二层：JSAPI 文件是否真正加载成功

确认页面在钉钉容器里之后，第二步要检查的是dd对象是否可用。

钉钉的 JSAPI 是一个外部脚本，通常这样引入：

<script src="https://g.alicdn.com/dingding/dingtalk-jsapi/2.9.3/dingtalk.open.js"></script>

版本号可以直接去钉钉开放平台官方文档找最新版，一般用 2.x 系列就行。注意这里有两个隐患：

第一，脚本加载顺序问题。如果你把这段<script>放在页面底部，而你的业务代码在 DOMContentLoaded 之后立刻执行dd.config，有可能脚本还没加载完，window.dd还不存在，直接报dd is not defined。我自己习惯的做法是把它放到index.html的head区域，并且用动态加载的方式包一层 Promise，确保后面调用时脚本一定就位。

第二，CDN 资源被网络拦截或缓存。钉钉内置浏览器有时候对第三方 CDN 的处理会很激进，如果之前某个版本缓存了旧的dingtalk.open.js，后面新接口可能不存在或者行为不一致。你可以通过代码判断：

if (typeof dd === 'undefined') { // 说明脚本没加载成功，或者宿主环境不是钉钉 }

这一步能帮你快速区分“环境不对”和“签名不对”。

3.3 第三层：签名流程是否完整、顺序是否正确

环境没问题、脚本也加载了，那大部分人的问题就集中在签名流程上。这层我建议按下面的顺序检查：

1. 前端有没有在执行dd.getLocation之前先执行dd.config？
2. dd.config的jsApiList里有没有包含'getLocation'？
3. 后端生成签名用的 URL，是不是前端传过去的location.href.split('#')[0]？
4. 后端用的jsapi_ticket是不是用当前应用的access_token换的？
5. signature签名串拼接顺序是否和钉钉文档一致？
6. 是否在dd.ready回调之后才调用dd.getLocation？

这六条里，我见过最多的是第三条和第六条。第三条前面讲过，URL 不一致会导致签名无效；第六条是因为dd.config本身是个异步过程，如果你在dd.config之后立刻调dd.getLocation，此时鉴权可能还没完成，钉钉会直接拒绝。

正确的调用顺序一定是这样：

dd.config({...}); dd.ready(function() { dd.getLocation({...}); }); dd.error(function(err) { console.log('鉴权失败', err); });

如果你漏了dd.ready，直接在dd.config后面同步调dd.getLocation，表现就是“偶尔能用，经常没反应”。这一点在本地调试时因为走了降级分支，根本不会触发，所以很容易被忽略。

3.4 第四层：初始化成功后的调起时机与参数

最后再检查dd.getLocation本身的参数。

钉钉的dd.getLocation支持几个配置项，常用的有：

• targetAccuracy：目标精度，单位米。我一般设 30 或者 50，实际精度取决于设备；
• coordinateType：坐标系类型，可选gcj02或wgs84。国内地图服务基本都是 GCJ-02 坐标系（高德、腾讯、钉钉都给这套），如果你后续要把经纬度传给高德地图，直接传gcj02，别用wgs84之后再转换；
• success：成功回调，返回longitude、latitude、accuracy；
• fail：失败回调，返回错误码和错误信息。

这里有个容易想当然的点：钉钉定位返回的是 GCJ-02 坐标系，不是 WGS-84。有些图表库或者 GIS 服务默认用 WGS-84，如果直接拿经纬度去标记，位置偏移几十米到几百米都有可能。当时我发现线上拿到的点在地图上飘到隔壁街区，一度以为是定位精度问题，后来才意识到坐标系不统一。

结合上面几层排查，我整理了一个常见错误码和对应原因的对照表，方便你快速定位：

这个是经验值，钉钉不同版本的错误码文案可能略有差异，但排查方向基本一致。

4. 可以复用的代码：定位封装、签名接口和路由恢复策略

4.1 前端封装：环境判断 + 签名 + ready + 定位四件套

为了让后面不再重复踩坑，我直接在 uni-app 的公共方法里封装了一个getDingTalkLocation。核心思路很简单：先判断是不是钉钉环境，是的话走完整鉴权链路，不是的话降级到uni.getLocation。完整代码如下：

// utils/dingtalk.js function isDingTalkEnv() { return /dingtalk/i.test(navigator.userAgent); } function loadDingTalkJsApi() { return new Promise((resolve, reject) => { if (typeof dd !== 'undefined') { resolve(); return; } const script = document.createElement('script'); script.src = 'https://g.alicdn.com/dingding/dingtalk-jsapi/2.9.3/dingtalk.open.js'; script.onload = () => resolve(); script.onerror = () => reject(new Error('dingtalk jsapi 加载失败')); document.head.appendChild(script); }); } async function getSignature() { // 从自己的后端接口拿签名配置 const response = await fetch('/api/dingtalk/sign?url=' + encodeURIComponent(location.href.split('#')[0])); const data = await response.json(); return data.data; // { agentId, corpId, timeStamp, nonceStr, signature } } export function getDingTalkLocation() { return new Promise((resolve, reject) => { if (!isDingTalkEnv()) { // 非钉钉环境：降级到 uni.getLocation uni.getLocation({ type: 'gcj02', success: (res) => resolve({ longitude: res.longitude, latitude: res.latitude }), fail: (err) => reject(err) }); return; } loadDingTalkJsApi() .then(() => getSignature()) .then((config) => { dd.config({ agentId: config.agentId, corpId: config.corpId, timeStamp: config.timeStamp, nonceStr: config.nonceStr, signature: config.signature, jsApiList: ['getLocation'] }); let isErrorHandled = false; dd.error((err) => { if (!isErrorHandled) { isErrorHandled = true; reject(new Error('dd.config 鉴权失败: ' + JSON.stringify(err))); } }); dd.ready(() => { dd.getLocation({ targetAccuracy: 30, coordinateType: 'gcj02', success: (res) => { if (!isErrorHandled) { isErrorHandled = true; resolve({ longitude: res.longitude, latitude: res.latitude }); } }, fail: (err) => { if (!isErrorHandled) { isErrorHandled = true; reject(new Error('dd.getLocation 调用失败: ' + JSON.stringify(err))); } } }); }); // 兜底：10秒后如果还没回调，判定超时 setTimeout(() => { if (!isErrorHandled) { isErrorHandled = true; reject(new Error('钉钉定位超时')); } }, 10000); }) .catch(reject); }); }

几个要注意的细节：

• dd.error一定要在dd.config之后、dd.ready之前注册，不然有些版本里鉴权失败的回调不会被触发；
• 回调要用一个flag防止重复 resolve 或 reject。Promise 状态一旦变化，后续回调就是无效的，但钉钉的fail和dd.error在某些异常情况下会同时触发，不加保护会抛 unhandled rejection；
• 超时兜底非常重要，线上环境遇到过十秒都没回调的极端情况，如果不设置超时，用户会一直在转圈。

4.2 服务端签名接口：access_token、jsapi_ticket 和签名生成

前端拿签名，后端得先有一系列流程。我这边用的是 Node.js，核心逻辑如下：

// server/dingtalk.js const crypto = require('crypto'); const axios = require('axios'); const APP_KEY = '你的appKey'; const APP_SECRET = '你的appSecret'; let cachedToken = { value: '', expireAt: 0 }; let cachedTicket = { value: '', expireAt: 0 }; async function getAccessToken() { if (cachedToken.expireAt > Date.now()) { return cachedToken.value; } const { data } = await axios.get('https://oapi.dingtalk.com/gettoken', { params: { appkey: APP_KEY, appsecret: APP_SECRET } }); cachedToken = { value: data.access_token, expireAt: Date.now() + 6000 * 1000 }; return data.access_token; } async function getJsapiTicket() { if (cachedTicket.expireAt > Date.now()) { return cachedTicket.value; } const accessToken = await getAccessToken(); const { data } = await axios.get('https://oapi.dingtalk.com/get_jsapi_ticket', { params: { access_token: accessToken } }); cachedTicket = { value: data.ticket, expireAt: Date.now() + 6000 * 1000 }; return data.ticket; } function createSignature(ticket, nonceStr, timeStamp, url) { const plain = `jsticket=${ticket}&noncestr=${nonceStr}&timestamp=${timeStamp}&url=${url}`; return crypto.createHash('sha1').update(plain).digest('hex'); } async function getSignatureConfig(url) { const ticket = await getJsapiTicket(); const nonceStr = uuid.v4().replace(/-/g, ''); const timeStamp = Date.now(); const signature = createSignature(ticket, nonceStr, timeStamp, url); return { agentId: AGENT_ID, corpId: CORP_ID, timeStamp, nonceStr, signature }; }

这里我要重点提醒两件事：

第一，jsapi_ticket必须缓存。钉钉的get_jsapi_ticket接口调用次数是有限制的，你不可能每个用户每次请求都去换一次 ticket。我在代码里做了 100 分钟的缓存，实际 ticket 有效期是 7200 秒，留点余量，避免边界情况下刚好过期。

第二，签名串拼接顺序是jsticket、noncestr、timestamp、url，顺序不能错，参数名必须和钉钉文档完全一致。我看到过有人把jsticket写成jsapi_ticket，也有人把noncestr写成nonceStr，这样 SHA1 之后的签名值完全对不上，前端dd.config就会报签名错误。

另外，如果后端部署在局域网或者 Redis 缓存里没有做互斥锁，高并发场景下多个请求同时去换 ticket，可能会触发钉钉的限流。这个问题我是在压测时才暴露出来的，简单做法是给 ticket 缓存加一个“获取中”的 Promise 锁，避免并发穿透。代码类似这样：

let ticketPending = null; async function getJsapiTicket() { if (cachedTicket.expireAt > Date.now()) return cachedTicket.value; if (ticketPending) return ticketPending; ticketPending = (async () => { try { const accessToken = await getAccessToken(); const { data } = await axios.get('...'); cachedTicket = { value: data.ticket, expireAt: Date.now() + 6000 * 1000 }; return data.ticket; } finally { ticketPending = null; } })(); return ticketPending; }

4.3 路由变化后是否需要重新鉴权

前面提过，uni-app 的 H5 默认是 hash 路由。在这种模式下，路由跳转不会改变location.href.split('#')[0]，所以理论上签名不会失效。但实际业务里我遇到过一个场景：用户在钉钉里把页面切到后台，过几分钟再回来，再点定位，有概率直接失败。这可能不是鉴权失效，而是钉钉 WebView 在页面进入后台时挂起了 JS 执行，回来之后事件队列错乱。

我的处理方式有两个：

做法一：在页面的onShow生命周期里重新执行一次dd.config，但不重新拉签名。因为 URL 没变，ticket 也在有效期内，签名可以复用，重新 config 的目的是让钉钉重新建立一次鉴权会话。

做法二：如果项目换成了 history 路由模式，那必须在uni.addInterceptor或者路由的beforeEach里重新拉签名。因为每次路由切换，URL 都变了，旧签名对当前页面无效。这个逻辑没法省，一旦用 history 模式，就得把getDingTalkLocation里的签名获取拆出来，做成一个独立函数，在每次路由变化时调用。

5. 三个隐蔽的小坑：缓存、HTTPS 和不生效的降级策略

5.1 钉钉内置浏览器的缓存策略很激进

部署到服务器后，钉钉内置 WebView 对静态资源的缓存策略比我预想的要激进。我遇到过一种情况：后端dingtalk.open.js的 CDN 地址被缓存成一个旧版本，虽然我没改过引入地址，但钉钉容器里执行的却是几天前的脚本，新接口方法不存在，导致dd.getLocation提示不支持。

处理办法分两层。第一层，给index.html设置不缓存的响应头；第二层，给带 hash 的静态资源设置长缓存。nginx 配置大致这样：

location = /h5/index.html { add_header Cache-Control "no-cache, no-store, must-revalidate"; add_header Pragma "no-cache"; } location /h5/static/ { add_header Cache-Control "public, max-age=31536000, immutable"; }

如果你用的是 HBuilderX 默认打包，静态资源文件名通常会带 hash，所以静态资源可以放心长缓存。关键是index.html必须实时更新，否则页面入口本身都是旧的。

另外，钉钉里的“刷新”和你习惯的浏览器刷新不太一样。用户点右上角刷新按钮，未必能拉最新资源。最稳的验证方式是杀掉钉钉进程重新打开，或者发布后用无痕思路的测试机验证。

5.2 HTTP 部署在钉钉里的 mixed content 问题

很多人测试环境用 HTTP 部署，觉得“能打开页面就行”。但钉钉容器对 HTTPS 的要求比普通浏览器严格，尤其是涉及定位、拍照这类 JSAPI，在非 HTTPS 环境下经常出现“service unavailable”或者干脆无响应。

我当时排查到最后，发现服务器只暴露了 80 端口，页面加载没问题，但定位接口一直被拒。后来在 nginx 里配了 HTTPS 证书，同时把页面里所有请求统一改成 HTTPS，问题才消失。

这里也提醒一点：如果前端页面是 HTTPS，但你的定位签名接口或者地图资源还是 HTTP，浏览器会拦截 mixed content，表现同样是定位或地图组件异常。所以不只是首页协议要对，页面引用的所有资源也要保持一致。

5.3 降级策略：钉钉环境外该给用户什么体验

最后说一下降级策略。实际开发中不可能每个人都在钉钉环境里打开这个页面，H5 本身也应该能在普通浏览器里正常显示。所以我的建议是：定位逻辑必须做环境判断，钉钉环境走dd.getLocation，非钉钉环境降级到uni.getLocation。

降级代码在最前面的封装里已经写了，但有一点要注意：uni.getLocation在普通浏览器里调用时，会触发浏览器的定位授权弹窗，用户一旦拒绝，fail回调会返回权限错误。这时候不要只是提示“定位失败”，最好能引导用户去浏览器设置里打开定位权限，或者手动选择地址。

我当时做一个小小的优化：失败时把错误文案格式化，如果是权限类型错误，提示用户“请在设置中允许使用位置信息”；如果是网络超时，提示“当前网络不稳定，请重试”。这个小细节在用户反馈上提升非常明显，实测下来比单纯弹一个“定位失败”要友好得多。

结合上面的所有检查项，最终的部署前确认清单可以压缩成一句话：页面必须是 HTTPS，域名必须在钉钉后台配 JSAPI 安全域名，后端签名 URL 必须取自location.href.split('#')[0]，dd.getLocation必须放在dd.ready里调用，而且非钉钉环境必须有降级方案。这套流程走完，我在本项目和后续几个 H5 微应用集成里再没被定位问题卡住过。

最后再分享一个我自己的习惯：写完定位封装之后，我会在首页环境判断的地方打印一条明显的调试日志，包含 UA 和 dd 对象是否存在。这样线上出了问题，远程让同事打开控制台截图给我，十秒内就能判断是环境问题还是签名问题，不用再像第一次那样盲人摸象。定位属于敏感能力，发布前也记得确认业务场景确实拿到了必要的授权和用户同意，合规使用，别给自己埋雷。