先交代一下背景我用HbuilderX寫uni-appH5端最終要嵌進(jìn)釘釘?shù)墓ぷ髋_(tái)里頁(yè)面里的定位功能走的是釘釘JSAPI也就是dd.getLocation。本地開發(fā)一切正常點(diǎn)按鈕、拿經(jīng)緯度、傳給后端流程跑得特別舒服。結(jié)果打包成H5部署到服務(wù)器之后同事在釘釘里打開定位直接拿不到了控制臺(tái)干干凈凈連報(bào)錯(cuò)都沒有。這種“本地正常、上線就掛”的問題做釘釘內(nèi)嵌H5的朋友一定不陌生。這篇文章把我這次踩坑的全過程、排查套路和最終配置方案完整寫出來(lái)。不管你是剛接觸uni-app還是已經(jīng)和釘釘JSAPI打過幾次交道照著這套思路基本能把環(huán)境差異類問題掃干凈。我會(huì)把重點(diǎn)放在部署前后的環(huán)境差異、釘釘JSAPI的鑒權(quán)鏈路、uni-app打包配置這三個(gè)關(guān)鍵環(huán)節(jié)上最后還給了一份可以直接抄的Nginx和manifest配置。1. 先摸清楚 dd.getLocation 到底是怎么工作的1.1 本地“正常”有可能是一種錯(cuò)覺先說(shuō)個(gè)扎心的事實(shí)你在HbuilderX內(nèi)置瀏覽器里跑得再歡和釘釘App里真實(shí)打開頁(yè)面完全是兩套環(huán)境。uni-app在瀏覽器里跑的是普通網(wǎng)頁(yè)釘釘App里跑的是被注入過原生橋接對(duì)象的網(wǎng)頁(yè)。dd.getLocation這個(gè)API只有在釘釘容器里才存在window.dd對(duì)象瀏覽器里你連dd都拿不到。我見過不少人寫代碼時(shí)習(xí)慣這么干dd.getLocation({ targetType: gcj02, success: function(res) { // ... } });這段代碼在本地瀏覽器里運(yùn)行應(yīng)該直接拋異常才對(duì)因?yàn)閐d是undefined?？扇绻?xiàng)目里加了統(tǒng)一封裝比如先判斷typeof dd undefined再走uni.getLocation兜底那你在本地看到的“一切正?！逼鋵?shí)根本不是你真正要走的邏輯。換句話說(shuō)本地正常只能證明頁(yè)面渲染和業(yè)務(wù)邏輯沒問題證明不了釘釘環(huán)境里這條路是通的。舉個(gè)生活化的類比dd.getLocation就像你到別人家做客時(shí)借用人家的廚房。你在自己家里怎么開火都行但到了別人家你得先敲門dd.config鑒權(quán)、等主人開門dd.ready回調(diào)才能進(jìn)去用廚房。部署到服務(wù)器之后出了狀況不是你家廚藝不行而是“敲門”這一步卡住了。1.2 一次正常的定位調(diào)用要過多少道關(guān)卡釘釘JSAPI的調(diào)用鏈路比想象中要長(zhǎng)。完整的流程是這樣的引入釘釘JSAPI腳本可以是外部script標(biāo)簽也可以用npm包dingtalk-jsapi。拿到后端的簽名參數(shù)包括agentId、corpId、timestamp、nonceStr、signature。調(diào)用dd.config做鑒權(quán)把簽名參數(shù)傳進(jìn)去。鑒權(quán)通過后在dd.ready回調(diào)里調(diào)用dd.getLocation。用戶在釘釘內(nèi)授權(quán)定位權(quán)限然后才能拿到經(jīng)緯度和精度。這里每道關(guān)卡都可能因?yàn)榄h(huán)境差異掛掉。尤其是dd.config這一步釘釘后端會(huì)用你當(dāng)前頁(yè)面的URL參與簽名計(jì)算本地是localhost部署后是正式域名只要URL不一致、或者后端生成簽名時(shí)取的URL和你實(shí)際訪問的URL不一致簽名校驗(yàn)就會(huì)失敗后續(xù)dd.getLocation自然就沒反應(yīng)。我把這個(gè)鏈路拆開講是想說(shuō)一個(gè)結(jié)論部署后定位失效大部分時(shí)候不是定位代碼本身的問題而是前面的“門”沒打開。下面幾節(jié)就按這個(gè)思路逐層拆解。2. 部署后最容易翻車的三個(gè)配置點(diǎn)2.1 釘釘后臺(tái)的可信域名和簽名校驗(yàn)釘釘?shù)腍5微應(yīng)用里有一個(gè)非常容易被忽略的配置服務(wù)器域名也就是可信域名。釘釘要求JSAPI只能在配置過的域名下使用你本地用localhost調(diào)試釘釘可能睜一只眼閉一只眼但部署到生產(chǎn)環(huán)境域名只要不在白名單里dd.config會(huì)直接失敗。這個(gè)配置的位置在釘釘開發(fā)者后臺(tái) → 你的應(yīng)用 → 應(yīng)用開發(fā) → H5微應(yīng)用 → 開發(fā)管理 → 服務(wù)器域名。路徑各個(gè)版本稍有差異但關(guān)鍵詞就是“服務(wù)器域名”四個(gè)字。添加的時(shí)候注意一定要填實(shí)際訪問的完整域名不要帶path也不要帶協(xié)議比如填寫example.com而不是https://example.com/h5/index.html。第二個(gè)容易踩的點(diǎn)是簽名。釘釘JSAPI的簽名機(jī)制是這樣的后端拿corpId、agentId、timestamp、nonceStr再用企業(yè)內(nèi)部應(yīng)用的AppKey和AppSecret去獲取jsapi_ticket最后用jsapi_ticket和當(dāng)前URL拼串做SHA-1哈希。這個(gè)URL必須是前端頁(yè)面實(shí)際訪問的完整URL而且要去掉#后面的部分。我這次踩的坑就在這后端同學(xué)直接用后端收到的請(qǐng)求URL去簽名而前端頁(yè)面URL因?yàn)槟承┰驇е欢褏?shù)兩者差了幾個(gè)字符結(jié)果就是簽名校驗(yàn)失敗。所以后來(lái)我統(tǒng)一了規(guī)范前端調(diào)用dd.config前先把location.href.split(#)[0]通過接口傳給后端保證簽名用的URL和實(shí)際訪問URL完全一致。2.2 uni-app打包后的資源路徑和路由模式這部分是純技術(shù)配置和釘釘本身沒關(guān)系但同樣能讓你部署后“看不見東西”——白屏、CSS丟失、JS找不到。uni-app打包H5后默認(rèn)資源路徑是絕對(duì)路徑比如/static/js/chunk-xxx.js。如果你的H5部署在域名根目錄還好如果是部署在子路徑比如https://example.com/h5/那這些資源會(huì)全部404。解決辦法在項(xiàng)目的manifest.json里找到h5節(jié)點(diǎn)把publicPath改成相對(duì)路徑或者你的實(shí)際部署路徑{ h5: { router: { mode: hash }, publicPath: ./ } }publicPath設(shè)成./可以讓頁(yè)面自動(dòng)從當(dāng)前目錄加載靜態(tài)資源部署在哪個(gè)子路徑都不怕。不過要注意純相對(duì)路徑在某些嵌套路由場(chǎng)景下可能會(huì)出問題如果你用了history模式更推薦設(shè)置成絕對(duì)路徑比如/h5/。再說(shuō)路由模式。uni-app的H5路由默認(rèn)是hash模式URL里會(huì)帶個(gè)#號(hào)比如https://example.com/h5/#/pages/index/index。這種模式有個(gè)好處就是不依賴服務(wù)端重寫刷新頁(yè)面也能找到對(duì)應(yīng)路由。而history模式URL很干凈但刷新或者直接訪問二級(jí)路徑時(shí)如果服務(wù)器沒做配置會(huì)直接404。對(duì)于釘釘內(nèi)嵌H5的場(chǎng)景我建議直接用hash模式省心、少踩坑。如果你非要用history模式那Nginx必須配好try_files重寫到index.html后面我會(huì)給配置。2.3 JSAPI腳本引入和環(huán)境判斷釘釘JSAPI的引入方式有兩種一種是在項(xiàng)目的index.html里直接掛script標(biāo)簽另一種是npm安裝dingtalk-jsapi然后在代碼里import。我個(gè)人更推薦npm方式因?yàn)榭梢园葱枰胍卜奖阕霏h(huán)境判斷。但不少人是直接改模板用的script標(biāo)簽這也沒問題前提是你得確認(rèn)這個(gè)script在生產(chǎn)環(huán)境能被正常加載。另一個(gè)坑是環(huán)境判斷。代碼里如果不做任何判斷就調(diào)用dd.config在某些非釘釘環(huán)境會(huì)直接報(bào)錯(cuò)。我給個(gè)參考寫法const isDingTalk typeof window.dd ! undefined window.dd ! null; if (isDingTalk) { dd.config({ agentId: res.agentId, corpId: res.corpId, timestamp: res.timestamp, nonceStr: res.nonceStr, signature: res.signature, jsApiList: [dd.getLocation] }); dd.ready(() { // 在這里調(diào)用 dd.getLocation }).catch(err { console.error(dd ready failed, err); }); } else { // 非釘釘環(huán)境走 uni.getLocation 兜底 }這個(gè)判斷最大的好處是你在HbuilderX內(nèi)置瀏覽器和普通瀏覽器里調(diào)試時(shí)不會(huì)再因?yàn)閐d對(duì)象不存在而白屏也不會(huì)在釘釘容器里因?yàn)闆]判斷而錯(cuò)過真正的定位邏輯。我在實(shí)際項(xiàng)目里還見過一種寫法在main.js里根據(jù)環(huán)境變量判斷是否引入釘釘SDK這個(gè)思路也可以但建議別搞得太復(fù)雜能跑、能排查才是最實(shí)際的。3. 完整排查實(shí)錄從現(xiàn)象定位到根因這一節(jié)我按實(shí)際場(chǎng)景來(lái)寫。我的頁(yè)面部署到服務(wù)器后同事反饋定位按鈕沒反應(yīng)。我第一反應(yīng)不是改代碼而是打開釘釘開發(fā)者工具把H5首頁(yè)地址輸進(jìn)去開啟vConsole觀察控制臺(tái)輸出。排查順序我覺得可以固定成一條線每次都按這個(gè)順序走效率高很多。3.1 現(xiàn)象一定位按鈕點(diǎn)了沒反應(yīng)首先看控制臺(tái)有沒有JS報(bào)錯(cuò)。如果報(bào)的是dd is not defined說(shuō)明釘釘JSAPI腳本沒加載成功或者當(dāng)前環(huán)境壓根不是釘釘。如果在釘釘里也報(bào)這個(gè)錯(cuò)那大概率是引入腳本的方式有問題檢查script標(biāo)簽的src是否可訪問、有沒有被CSP攔截。如果dd對(duì)象存在沒有報(bào)錯(cuò)但按鈕點(diǎn)了沒反應(yīng)這時(shí)候要確認(rèn)dd.config是否走完了。我在console里加了幾個(gè)log發(fā)現(xiàn)dd.config之后直接在dd.ready外調(diào)用了dd.getLocation這個(gè)順序是有問題的。釘釘官方要求所有JSAPI調(diào)用必須在dd.ready回調(diào)里執(zhí)行。雖然大部分時(shí)候在外面也能偶爾成功但那屬于運(yùn)氣好一旦鑒權(quán)還沒完成調(diào)用就直接丟了。還有一次dd.config成功、dd.ready也執(zhí)行了但dd.getLocation就是不觸發(fā)回調(diào)。最后發(fā)現(xiàn)是釘釘版本太老不支持dd.getLocation這個(gè)API。這種情況在老舊的企業(yè)釘釘版本里偶爾會(huì)遇到解決辦法要么升級(jí)釘釘要么走uni.getLocation做降級(jí)。對(duì)咱們做H5集成的人來(lái)說(shuō)降級(jí)方案真的不能少。3.2 現(xiàn)象二dd.getLocation報(bào)錯(cuò)誤碼如果dd.getLocation回調(diào)里返回了errorCode那問題會(huì)更明確。我把常見的情況整理成了表格現(xiàn)象可能原因處理方式errorCode為401簽名錯(cuò)誤URL與后端簽名用的URL不一致前端把location.href.split(#)[0]傳給后端重新簽名errorCode為403無(wú)權(quán)限企業(yè)未開通對(duì)應(yīng)權(quán)限點(diǎn)到釘釘開發(fā)者后臺(tái)檢查權(quán)限點(diǎn)是否申請(qǐng)并啟用errorCode為404當(dāng)前釘釘版本不支持該API建議升級(jí)釘釘或走uni.getLocation兜底提示no permission用戶未授權(quán)定位或應(yīng)用未配置定位權(quán)限檢查釘釘客戶端定位權(quán)限引導(dǎo)用戶開啟定位注意釘釘不同版本返回的錯(cuò)誤格式不一定完全一樣關(guān)鍵是看err對(duì)象里有沒有errorMessage一般里面會(huì)帶英文描述比如no permission、signature error之類的關(guān)鍵字。根據(jù)關(guān)鍵字再去翻釘釘開放平臺(tái)文檔比自己瞎猜快得多。3.3 現(xiàn)象三坐標(biāo)能拿到但地圖上位置偏移坐標(biāo)偏移的問題往往是坐標(biāo)系不統(tǒng)一造成的。釘釘?shù)膁d.getLocation默認(rèn)返回的是gcj02坐標(biāo)也就是俗稱的“火星坐標(biāo)”國(guó)內(nèi)主流地圖廠商比如高德、騰訊都直接用這個(gè)坐標(biāo)系。但如果你把坐標(biāo)丟給百度地圖或者拿到的經(jīng)緯度和地圖底圖對(duì)不上位置偏出去幾百米甚至更遠(yuǎn)就很正常。遇到這種情況先確認(rèn)你用的地圖SDK是哪個(gè)。高德地圖直接喂gcj02坐標(biāo)沒問題百度地圖需要轉(zhuǎn)成bd09有些海外地圖服務(wù)用的是wgs84那就要做gcj02到wgs84的轉(zhuǎn)換。轉(zhuǎn)換公式網(wǎng)上很多也可以直接用現(xiàn)成庫(kù)別自己手搓數(shù)學(xué)公式容易出精度問題。我在項(xiàng)目里是統(tǒng)一后端存儲(chǔ)為gcj02前端展示也統(tǒng)一用gcj02從源頭避免坐標(biāo)系混亂。3.4 現(xiàn)象四頁(yè)面直接白屏或樣式錯(cuò)亂如果部署后白屏那多半不是定位的問題是靜態(tài)資源沒加載出來(lái)。優(yōu)先級(jí)最高的排查項(xiàng)就是publicPath。我之前接過一個(gè)項(xiàng)目把H5包直接扔到了nginx的html/h5目錄結(jié)果index.html加載到了但里面的css和js全是404后來(lái)把manifest里的publicPath改成./就正常了。還有一種情況是Nginx配置。如果用了history模式Nginx沒有做try_files刷新一次就404。如果用了hash模式這個(gè)問題基本不存在。所以如果你不想碰服務(wù)端就老實(shí)選hash模式。4. 可直接照抄的部署配置4.1 uni-app構(gòu)建配置清單先說(shuō)uni-app這邊的配置我以HbuilderX 3.x版本為例。打開項(xiàng)目根目錄的manifest.json切到源碼視圖找到h5節(jié)點(diǎn)配置如下{ h5: { router: { mode: hash, base: /h5/ }, publicPath: /h5/, devServer: { port: 8080 } } }如果部署在根路徑base和publicPath都可以改成./或者/根據(jù)你自己的部署位置來(lái)。配置好后在HbuilderX菜單欄選“發(fā)行” → “網(wǎng)站-H5手機(jī)版”構(gòu)建產(chǎn)物會(huì)輸出到unpackage/dist/build/h5目錄把這個(gè)目錄里的所有文件原樣上傳到服務(wù)器即可。構(gòu)建的時(shí)候有幾個(gè)小細(xì)節(jié)值得注意一是盡量在發(fā)布前手動(dòng)刪除unpackage目錄里的舊dist避免緩存文件混進(jìn)去二是如果你的項(xiàng)目里有用到地圖SDK的key記得檢查H5端有沒有單獨(dú)配置key釘釘內(nèi)訪問用的是你項(xiàng)目的正式key別把測(cè)試key帶上去。三是條件編譯一定要用好釘釘相關(guān)代碼用#ifdef H5包起來(lái)避免影響其他端的構(gòu)建。4.2 Nginx部署示例假設(shè)你的H5要部署到https://example.com/h5/這個(gè)路徑對(duì)應(yīng)服務(wù)器目錄是/var/www/h5。Nginx配置可以這樣寫server { listen 443 ssl; server_name example.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; root /var/www/h5; index index.html; location /h5/ { alias /var/www/h5/; try_files $uri $uri/ /h5/index.html; } location /h5/static/ { alias /var/www/h5/static/; expires 7d; add_header Cache-Control public; } }如果用的是hash模式try_files那行其實(shí)不一定要但保留也沒問題防止以后切到history模式。如果你直接把項(xiàng)目部署到域名根目錄那就把location改成root /var/www/h5try_files改成try_files $uri $uri/ /index.html。有一點(diǎn)提醒一下釘釘?shù)腍5應(yīng)用要求使用HTTPS。如果你還是http釘釘端會(huì)提示非安全鏈接dd.config也可能直接失敗。所以服務(wù)器證書和443監(jiān)聽是少不了的證書可以用通用的免費(fèi)證書方案反正自動(dòng)續(xù)期腳本一掛基本不用管。4.3 釘釘后臺(tái)配置與簽名接口釘釘后臺(tái)部分你需要保證應(yīng)用類型是“H5微應(yīng)用”。進(jìn)入開發(fā)者后臺(tái)找到你的應(yīng)用在H5微應(yīng)用的開發(fā)管理里把首頁(yè)地址配置成實(shí)際訪問地址比如https://example.com/h5/index.html。然后在服務(wù)器域名里填入example.com確保和首頁(yè)地址域名一致。簽名接口這塊前端和后端要約定好。我在項(xiàng)目中用了一個(gè)很簡(jiǎn)單的接口路徑類似/dd/getSign前端把訪問URL傳過去后端返回以下參數(shù){ agentId: your-agent-id, corpId: your-corp-id, timestamp: 1700000000000, nonceStr: random-string, signature: sha1-hash-value }前端拿到這些參數(shù)后在dd.config里帶上并打開debug模式方便排查dd.config({ agentId: res.agentId, corpId: res.corpId, timestamp: res.timestamp, nonceStr: res.nonceStr, signature: res.signature, jsApiList: [dd.getLocation], debug: true });debug模式開啟后如果簽名有問題控制臺(tái)會(huì)打印出具體錯(cuò)誤信息排查效率會(huì)高很多。但這個(gè)debug模式上生產(chǎn)環(huán)境建議關(guān)掉不然控制臺(tái)日志太吵也容易暴露內(nèi)部信息。5. 常見問題速查表與實(shí)踐心得5.1 問題速查表我把這次排查過程中遇到的各種問題、原因和動(dòng)作整理成一張表方便你遇到問題時(shí)直接翻現(xiàn)象可能原因處理方式本地正常釘釘里定位沒反應(yīng)dd.config簽名失敗或未在dd.ready中調(diào)用檢查簽名URL、可信域名調(diào)整調(diào)用時(shí)機(jī)部署后頁(yè)面白屏publicPath配置錯(cuò)誤修改manifest的h5.publicPath為實(shí)際路徑或./history模式刷新404Nginx未配置try_files添加try_files或改用hash模式dd對(duì)象不存在釘釘JSAPI腳本未加載或環(huán)境不是釘釘檢查script引入非釘釘環(huán)境走兜底dd.config返回簽名錯(cuò)誤簽名URL與后端計(jì)算不一致前端傳location.href.split(#)[0]給后端定位能拿到但坐標(biāo)偏移坐標(biāo)系不統(tǒng)一統(tǒng)一使用gcj02按地圖SDK要求轉(zhuǎn)換老版本釘釘不支持API釘釘版本過舊升級(jí)釘釘或降級(jí)到uni.getLocation部署后DNS或資源打不開域名白名單未配置在釘釘后臺(tái)添加服務(wù)器域名5.2 我踩過的幾個(gè)坑先說(shuō)一個(gè)印象最深的坑。那時(shí)候我剛從純H5切到uni-app圖省事直接在mounted生命周期里寫了dd.getLocation本地測(cè)試環(huán)境反正能拿到也沒細(xì)想。結(jié)果打包上線后釘釘里十次有八九次拿不到定位。后來(lái)看文檔才發(fā)現(xiàn)dd.config和dd.ready這套異步鑒權(quán)機(jī)制不是開玩笑的必須等ready了再調(diào)用。從那以后我就養(yǎng)成了習(xí)慣所有釘釘JSAPI調(diào)用統(tǒng)一封裝在一個(gè)Promise里等dd.ready后再resolve業(yè)務(wù)層只關(guān)心定位結(jié)果不關(guān)心底層鑒權(quán)時(shí)序。第二個(gè)坑是部署目錄。有一次我把H5包直接丟nginx根目錄了publicPath寫的/一切正常。后來(lái)項(xiàng)目要和其他系統(tǒng)共用一個(gè)域名就得挪到子目錄結(jié)果沒改publicPath部署完頁(yè)面全是白花花一片。那一次之后我只要涉及部署路徑變更第一件事必查manifest里的publicPath和路由base。第三個(gè)坑是緩存。釘釘里的H5頁(yè)面加載是有緩存的我發(fā)布新版本后同事反應(yīng)頁(yè)面還是舊的。一開始以為是服務(wù)器緩存沒刷新后來(lái)發(fā)現(xiàn)是釘釘客戶端的緩存策略比較激進(jìn)。解決辦法是發(fā)布后在釘釘里清一下緩存或者在前端資源URL上帶版本號(hào)。如果你用的是HbuilderX的發(fā)行功能每次打包會(huì)自動(dòng)生成帶hash的文件名一般不會(huì)有這個(gè)問題但如果某些公共庫(kù)是外部引用的緩存問題還是得留意。5.3 一點(diǎn)降級(jí)與兜底建議雖然dd.getLocation是釘釘內(nèi)的正路但做移動(dòng)端H5永遠(yuǎn)得留一手。我的做法是先用環(huán)境判斷區(qū)分是不是釘釘是釘釘就走dd.getLocation不是就走uni.getLocation。這樣既保證釘釘內(nèi)體驗(yàn)也方便普通瀏覽器測(cè)試。同時(shí)我給定位加了一個(gè)超時(shí)機(jī)制。dd.getLocation有時(shí)候會(huì)因?yàn)橛脩舨皇跈?quán)或者網(wǎng)絡(luò)問題卡住不能一直等。我一般會(huì)設(shè)定5秒超時(shí)超時(shí)后提示用戶檢查網(wǎng)絡(luò)或重新授權(quán)再給一個(gè)手動(dòng)重試按鈕。真要做得好一點(diǎn)可以監(jiān)聽visibilitychange頁(yè)面從后臺(tái)切回來(lái)的時(shí)候重新獲取一次定位很多用戶是在釘釘里切到地圖應(yīng)用再切回來(lái)這時(shí)候重新拉一次定位會(huì)更準(zhǔn)確。最后說(shuō)個(gè)關(guān)鍵心得釘釘內(nèi)嵌H5的問題90%都是環(huán)境差異導(dǎo)致的不是代碼邏輯問題。所以排查順序一定要固定先看可信域名和簽名再看JSAPI調(diào)用時(shí)機(jī)再看打包配置和服務(wù)器配置。這套順序我現(xiàn)在已經(jīng)形成肌肉記憶了也把最核心的檢查項(xiàng)做成了一份發(fā)布前自檢清單每次發(fā)版前過一遍能省掉非常多“線上救火”的時(shí)間。在這里也分享一個(gè)小技巧發(fā)布前在釘釘開發(fā)者工具里完整走一遍流程同時(shí)把vConsole打開。這個(gè)小習(xí)慣看起來(lái)不起眼但能幫你把dd.config的錯(cuò)誤信息、JSAPI的調(diào)用日志看得清清楚楚比上線后讓同事截圖再猜要高效得多。