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