前陣子公司一個(gè)項(xiàng)目要部署到內(nèi)網(wǎng)環(huán)境業(yè)務(wù)方指著大屏說地圖這塊必須保留而且不能斷網(wǎng)。我盯著需求書看了半天腦子里蹦出來的思路其實(shí)已經(jīng)很清晰了——高德地圖離線化。這里說的離線化不是把手機(jī)高德APP的離線包下載下來完事而是指在完全隔離的網(wǎng)絡(luò)里把一套可交互的地圖應(yīng)用完整跑起來。整體方案拆開來看就一句話先把高德瓦片數(shù)據(jù)搬到內(nèi)網(wǎng)再用開源GIS引擎渲染這些瓦片實(shí)現(xiàn)標(biāo)記、彈窗、軌跡、聚合這些常用交互功能。聽起來不算復(fù)雜但真正動(dòng)手會(huì)發(fā)現(xiàn)里面全是細(xì)節(jié)。從瓦片下載腳本到Nginx發(fā)布從坐標(biāo)糾偏到前端引擎選型每一步都可能踩坑。這篇文章把我從零到一做完的經(jīng)驗(yàn)完整寫出來適合在內(nèi)網(wǎng)、政務(wù)網(wǎng)、園區(qū)專網(wǎng)或涉密程度不高的企業(yè)內(nèi)網(wǎng)里做地圖展示的開發(fā)者參考。1. 為什么做高德地圖內(nèi)網(wǎng)離線化1.1 內(nèi)網(wǎng)場(chǎng)景的硬約束內(nèi)網(wǎng)環(huán)境最直接的特點(diǎn)就是與外網(wǎng)物理隔離或邏輯隔離。業(yè)務(wù)系統(tǒng)部署在這樣的網(wǎng)絡(luò)里意味著前端頁面無法訪問在線地圖SDK也無法請(qǐng)求任何外網(wǎng)站點(diǎn)。很多做慣了在線地圖開發(fā)的同學(xué)第一個(gè)反應(yīng)還是引JSAPI、配Key、調(diào)接口到了內(nèi)網(wǎng)全被卡住。除了網(wǎng)絡(luò)隔離還有幾個(gè)現(xiàn)實(shí)問題在線版高德JS API的JS文件放在CDN上內(nèi)網(wǎng)訪問不了。即使手動(dòng)把JS文件下載下來腳本內(nèi)部還會(huì)動(dòng)態(tài)請(qǐng)求驗(yàn)證、定位、路況等接口全部依賴外網(wǎng)。內(nèi)網(wǎng)環(huán)境多數(shù)也不允許隨意開放外網(wǎng)訪問權(quán)限域名白名單、秘鑰管理都是問題。在線API有配額和計(jì)費(fèi)規(guī)則調(diào)用量大時(shí)成本壓不住。所以內(nèi)網(wǎng)地圖項(xiàng)目不能按在線開發(fā)的思路來做。你想保留高德地圖的視覺效果和交互體驗(yàn)就得把地圖數(shù)據(jù)整體“搬”進(jìn)來同時(shí)把渲染和交互能力也全部本地化。1.2 技術(shù)選型瓦片方案、離線SDK還是自繪當(dāng)時(shí)我對(duì)比了三條路線高德離線SDK、自繪地圖、瓦片方案。高德官方提供的離線SDK主要面向Android、iOS原生應(yīng)用可以在端側(cè)下載城市離線包。但我們的項(xiàng)目是Web大屏官方JS API并沒有正式離線版。有人試過把JS API的腳本抓到本地再通過代理把運(yùn)行時(shí)請(qǐng)求轉(zhuǎn)發(fā)到內(nèi)網(wǎng)模擬但高德JS內(nèi)部還依賴很多在線服務(wù)接口一旦某個(gè)請(qǐng)求失敗地圖渲染就會(huì)出問題。維護(hù)成本太高容易翻車。自繪地圖這條路最可控但需要自己準(zhǔn)備底圖數(shù)據(jù)、道路數(shù)據(jù)、POI數(shù)據(jù)還要做風(fēng)格渲染項(xiàng)目周期根本不允許。而且沒有專業(yè)美工調(diào)出來的地圖風(fēng)格很難看業(yè)務(wù)方大概率不會(huì)接受。瓦片方案是目前最務(wù)實(shí)的做法把高德地圖已經(jīng)渲染好的圖片瓦片按層級(jí)預(yù)先下載到本地然后通過Nginx發(fā)布成靜態(tài)文件服務(wù)前端用開源引擎加載這些瓦片。優(yōu)點(diǎn)很明顯視覺風(fēng)格和高德在線保持一致地圖數(shù)據(jù)量可控渲染性能高交互能力用開源輪子補(bǔ)齊。1.3 整體鏈路設(shè)計(jì)整個(gè)鏈路分四段確認(rèn)需要的區(qū)域范圍和最大縮放級(jí)別。用腳本把該范圍內(nèi)每個(gè)級(jí)別的高德瓦片批量下載到本地。在內(nèi)網(wǎng)部署Nginx或其他靜態(tài)文件服務(wù)把瓦片目錄發(fā)布出去。前端頁面用Leaflet等開源GIS引擎加載內(nèi)網(wǎng)瓦片服務(wù)疊加業(yè)務(wù)圖層和交互功能。這套鏈路的關(guān)鍵點(diǎn)在于第2步的瓦片坐標(biāo)換算、第3步的發(fā)布代理以及第4步的坐標(biāo)體系一致性問題。下面逐個(gè)展開。2. 動(dòng)手前先搞懂瓦片規(guī)則與坐標(biāo)體系2.1 XYZ瓦片到底怎么編號(hào)很多同學(xué)第一次接觸瓦片時(shí)會(huì)被一堆數(shù)字搞得頭暈。其實(shí)原理很簡(jiǎn)單地圖服務(wù)商把全球地圖按金字塔模型切成很多張正方形小圖片每張就是一個(gè)瓦片。第0級(jí)通常只有1張或2張瓦片越往下放大級(jí)別越高瓦片數(shù)量越多。這里用OpenStreetMap推廣開的XYZ規(guī)則這是目前WebGIS最通用的瓦片尋址方式z表示縮放級(jí)別。x表示瓦片所在列從西到東從0開始。y表示瓦片所在行從北到南從0開始。高德地圖瓦片在Web端也是按這個(gè)規(guī)則組織的只是不同數(shù)據(jù)源的代號(hào)和URL模板有所不同。你拿到瓦片服務(wù)的地圖URL后通常只需要把{z}、{x}、{y}三個(gè)參數(shù)替換成實(shí)際數(shù)值就能直接請(qǐng)求到圖片。比如某一級(jí)某個(gè)位置的瓦片請(qǐng)求URL模板大概是{你的數(shù)據(jù)源地址}/mapstyle/{z}/{x}/{y}.png?param...具體域名和參數(shù)每個(gè)項(xiàng)目不一樣核心是記住替換z/x/y。建議在實(shí)際寫腳本前先在瀏覽器地址欄里手改幾組數(shù)字確認(rèn)這套URL模板能正常返回圖片再動(dòng)手寫批量下載程序。2.2 經(jīng)緯度換算瓦片編號(hào)公式與代碼判斷一個(gè)地理坐標(biāo)落在哪個(gè)瓦片里需要做一次坐標(biāo)換算。公式看起來有一點(diǎn)數(shù)學(xué)味道但寫起來很固定可以直接抄n 2^z x int((lng 180.0) / 360.0 * n) y int((1.0 - ln(tan(lat_rad) 1 / cos(lat_rad)) / pi) / 2.0 * n)其中l(wèi)at_rad是緯度的弧度值。這個(gè)y公式就是Web Mercator投影的反算不用理解太深知道它是把地球球面坐標(biāo)映射到平面瓦片網(wǎng)格上就行。代碼實(shí)現(xiàn)如下import math def lon_lat_to_tile(lon, lat, zoom): lat_rad math.radians(lat) n 2 ** zoom x int((lon 180.0) / 360.0 * n) y int((1.0 - math.asinh(math.tan(lat_rad)) / math.pi) / 2.0 * n) return x, y注意這里用math.asinh是為了代碼簡(jiǎn)潔。這個(gè)函數(shù)等價(jià)于上文公式里的ln(tan(φ) sec(φ))只是Math庫里的反雙曲正弦剛好有這個(gè)性質(zhì)寫起來更緊湊。實(shí)際下載某個(gè)矩形區(qū)域的瓦片時(shí)很多人會(huì)寫出“先算左上角瓦片再算右下角瓦片然后雙重循環(huán)遍歷”的邏輯。這里有一個(gè)必須注意的細(xì)節(jié)瓦片y方向是自北向南遞增的所以左上角的緯度更大右上角經(jīng)度更大。也就是說取范圍時(shí)要按下面這種方式算def collect_tiles(min_lon, min_lat, max_lon, max_lat, zoom): x1, y1 lon_lat_to_tile(min_lon, max_lat, zoom) # 注意緯度用最大緯度 x2, y2 lon_lat_to_tile(max_lon, min_lat, zoom) # 這里用最小緯度 tiles [] for x in range(min(x1, x2), max(x1, x2) 1): for y in range(min(y1, y2), max(y1, y2) 1): tiles.append((zoom, x, y)) return tiles第一次寫這個(gè)邏輯時(shí)很容易把左上角和右下角的坐標(biāo)算反導(dǎo)致下載回來的瓦片錯(cuò)位或缺一大片。把min和max都做一遍比較再用range遍歷是最穩(wěn)妥的寫法。2.3 GCJ-02、WGS-84和Web Mercator的糾葛這是離線地圖開發(fā)里最大的坑也是很多人做得好好的項(xiàng)目突然出現(xiàn)幾百米偏移的根本原因。簡(jiǎn)單說國內(nèi)商用地圖服務(wù)商包括高德在對(duì)外提供地圖數(shù)據(jù)時(shí)坐標(biāo)并不是GPS原生的WGS-84坐標(biāo)而是經(jīng)過一次非線性偏移的GCJ-02坐標(biāo)。高德瓦片本身已經(jīng)按GCJ-02做了糾偏所以在高德自己的前端引擎里加載用戶感覺不到問題。但如果換成Leaflet這類開源引擎直接加載高德瓦片底圖本身是GCJ-02的而你的業(yè)務(wù)數(shù)據(jù)如果是從GPS設(shè)備、第三方傳感器拿到的WGS-84坐標(biāo)直接打到地圖上就會(huì)偏移。偏移量不是固定值在北京市區(qū)通常幾百米方向也不完全一致無法通過簡(jiǎn)單加減修正。解決辦法有兩種一是業(yè)務(wù)設(shè)備出數(shù)時(shí)直接做一次坐標(biāo)轉(zhuǎn)換把WGS-84轉(zhuǎn)成GCJ-02再入庫二是在前端渲染前統(tǒng)一轉(zhuǎn)換。前者更好因?yàn)閿?shù)據(jù)入庫后是干凈的。后面的章節(jié)我會(huì)給出一段可用的轉(zhuǎn)換代碼。這里先記住結(jié)論數(shù)據(jù)坐標(biāo)體系必須和高德瓦片保持一致統(tǒng)一用GCJ-02偏差問題就消失。3. 核心實(shí)操編寫瓦片下載腳本3.1 確定下載范圍、級(jí)別與體量在下腳本之前先想清楚要下載哪幾級(jí)瓦片。內(nèi)網(wǎng)項(xiàng)目常見的地圖展示場(chǎng)景是城市級(jí)或園區(qū)級(jí)。整體覆蓋可以考慮10到12級(jí)看全局業(yè)務(wù)聚焦區(qū)域下載到15級(jí)甚至17級(jí)。但級(jí)別越高瓦片數(shù)量呈4倍增長不是線性的。以北京六環(huán)內(nèi)區(qū)域?yàn)槔易鲞^一個(gè)粗略估算縮放級(jí)別覆蓋場(chǎng)景北京六環(huán)范圍瓦片數(shù)預(yù)計(jì)體積10全市概覽約20~60張1~5MB12區(qū)縣主干路約500~1000張30~80MB15街道建筑約4000~6000張300~800MB17樓宇與園區(qū)細(xì)節(jié)約1.5萬~2.5萬張1~3GB以上是經(jīng)驗(yàn)估值具體體積取決于瓦片內(nèi)容復(fù)雜度和圖片壓縮率。地圖內(nèi)容密集的區(qū)域單張瓦片可能到80KB而郊區(qū)純色瓦片可能只有10KB。下載前先按這個(gè)量級(jí)估算好硬盤空間。不建議一上來就全級(jí)別全范圍下載。先下載低級(jí)別觀察效果再逐步增加范圍和級(jí)別。否則腳本寫錯(cuò)了或者范圍框大了帶寬和時(shí)間成本都很浪費(fèi)。3.2 Python腳本落地完整實(shí)現(xiàn)與踩坑下載腳本我建議用Python寫生態(tài)成熟requests加concurrent.futures就能搞定并發(fā)。貼一段我實(shí)際用下來的結(jié)構(gòu)import math import os import time import requests from concurrent.futures import ThreadPoolExecutor, as_completed HEADERS { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36, Referer: https://your.site/, # 按數(shù)據(jù)源要求設(shè)置 } # 瓦片URL模板具體按項(xiàng)目數(shù)據(jù)源填充 URL_TEMPLATE https://your-tile-host/{z}/{x}/{y}.png def lon_lat_to_tile(lon, lat, zoom): lat_rad math.radians(lat) n 2 ** zoom x int((lon 180.0) / 360.0 * n) y int((1.0 - math.asinh(math.tan(lat_rad)) / math.pi) / 2.0 * n) return x, y def download_one(z, x, y, save_dir): save_path os.path.join(save_dir, str(z), str(x), f{y}.png) if os.path.exists(save_path) and os.path.getsize(save_path) 0: return True url URL_TEMPLATE.format(zz, xx, yy) for attempt in range(3): try: resp requests.get(url, headersHEADERS, timeout10) if resp.status_code 200: os.makedirs(os.path.dirname(save_path), exist_okTrue) with open(save_path, wb) as f: f.write(resp.content) return True elif resp.status_code 429: time.sleep(2 * (attempt 1)) except Exception: time.sleep(1) return False def download_region(min_lon, min_lat, max_lon, max_lat, zoom, save_dir): x1, y1 lon_lat_to_tile(min_lon, max_lat, zoom) x2, y2 lon_lat_to_tile(max_lon, min_lat, zoom) tasks [] for x in range(min(x1, x2), max(x1, x2) 1): for y in range(min(y1, y2), max(y1, y2) 1): tasks.append((zoom, x, y)) failed [] with ThreadPoolExecutor(max_workers8) as pool: futures {pool.submit(download_one, *task): task for task in tasks} for future in as_completed(futures): task futures[future] try: if not future.result(): failed.append(task) except Exception: failed.append(task) if failed: print(f失敗數(shù)量: {len(failed)}) with open(failed_tiles.txt, w) as f: for z, x, y in failed: f.write(f{z}/{x}/{y}\n) else: print(全部下載完成)這段代碼里有幾個(gè)當(dāng)時(shí)踩坑后加進(jìn)去的點(diǎn)值得講解。第一是重試機(jī)制。有些瓦片服務(wù)對(duì)高頻請(qǐng)求會(huì)返回429限流重試時(shí)加退避時(shí)間否則連續(xù)下載幾千張瓦片時(shí)很容易被臨時(shí)封禁。第二是斷點(diǎn)續(xù)傳。腳本判斷文件存在且大小不為0就跳過避免中途掛了要全部重新下載。第三是失敗列表落盤。下載完成后檢查failed_tiles.txt再針對(duì)失敗項(xiàng)單獨(dú)補(bǔ)拉比在終端里翻日志高效得多。并發(fā)數(shù)建議控制在8到16之間。開太高容易被數(shù)據(jù)源限流開太低下載幾萬張瓦片會(huì)等很久。帶寬和內(nèi)網(wǎng)部署階段通常8線程是平衡點(diǎn)。3.3 內(nèi)網(wǎng)Python環(huán)境的準(zhǔn)備與依賴離線安裝下載腳本理論上可以在有網(wǎng)環(huán)境跑完再把瓦片擺渡進(jìn)內(nèi)網(wǎng)但實(shí)際操作中內(nèi)網(wǎng)服務(wù)器往往也需要跑數(shù)據(jù)處理程序比如瓦片重命名、目錄整理、格式清洗。這時(shí)候內(nèi)網(wǎng)機(jī)器的Python環(huán)境就要提前準(zhǔn)備好。內(nèi)網(wǎng)Linux機(jī)器常見的坑是Python版本過舊。很多國產(chǎn)化Linux服務(wù)器自帶的還是Python 2.7或者3.6跑現(xiàn)代腳本會(huì)報(bào)語法錯(cuò)誤。優(yōu)先用源碼編譯安裝新版Python步驟不復(fù)雜# 先確認(rèn)編譯工具鏈 yum install -y gcc gcc-c make openssl-devel zlib-devel bzip2-devel readline-devel sqlite-devel libffi-devel # 下載Python源碼后編譯 ./configure --prefix/usr/local/python3.11 --enable-optimizations make make install ln -s /usr/local/python3.11/bin/python3.11 /usr/local/bin/python3 ln -s /usr/local/python3.11/bin/pip3.11 /usr/local/bin/pip3編譯前務(wù)必裝上openssl-devel和libffi-devel否則pip會(huì)報(bào)ssl相關(guān)錯(cuò)誤新版Python也裝不上requests這些包。依賴包離線安裝也很簡(jiǎn)單在外網(wǎng)機(jī)器上執(zhí)行pip download -d /tmp/pkgs requests然后把整個(gè)pkgs目錄拷進(jìn)內(nèi)網(wǎng)內(nèi)網(wǎng)執(zhí)行pip install --no-index --find-links/tmp/pkgs requests這里的--no-index參數(shù)很關(guān)鍵表示不訪問PyPI只從本地目錄查找安裝包。把requests、urllib3、charset-normalizer這些常見包全部下載好后續(xù)腳本就不會(huì)再缺依賴。4. 用Nginx發(fā)布本地瓦片服務(wù)4.1 目錄結(jié)構(gòu)與命名校驗(yàn)瓦片下載完成后要檢查目錄是否按標(biāo)準(zhǔn)路徑組織。Nginx靜態(tài)服務(wù)的目錄結(jié)構(gòu)需要和瓦片URL對(duì)齊。一個(gè)規(guī)范的目錄結(jié)構(gòu)如下/data/map_tiles/ └── 15/ ├── 26000/ │ ├── 13000.png │ ├── 13001.png │ └── ... ├── 26001/ │ └── ... └── ...也就是z目錄下面套x目錄再往下是y.png文件。Leaflet等前端引擎發(fā)請(qǐng)求時(shí)會(huì)自動(dòng)替換URL里的{z}/{x}/{y}所以目錄結(jié)構(gòu)必須嚴(yán)格匹配多一層少一層都會(huì)404。有時(shí)候下載腳本會(huì)以不同規(guī)則保存比如把z/x/y寫反了或者文件名缺少擴(kuò)展名。建議下載完成后寫一個(gè)小腳本隨機(jī)抽幾十個(gè)路徑檢查文件是否存在以及大小是否正常避免部署到Nginx才發(fā)現(xiàn)一堆404。4.2 Nginx配置與緩存策略內(nèi)網(wǎng)訪問量通常不會(huì)非常大但大屏項(xiàng)目往往有多個(gè)終端同時(shí)拉圖Nginx配置得當(dāng)可以省很多后端壓力。核心配置如下server { listen 8000; server_name map.internal; location /tiles/ { alias /data/map_tiles/; access_log off; expires 30d; add_header Cache-Control public, max-age2592000; try_files $uri 404; } location / { root /data/map_web; index index.html; try_files $uri $uri/ /index.html; } }瓦片是靜態(tài)不變的文件開啟expires讓瀏覽器緩存一個(gè)月可以極大減少重復(fù)請(qǐng)求。access_log建議關(guān)掉否則幾天下來日志文件就能積累幾GB全是瓦片請(qǐng)求記錄。還要注意location的alias與root區(qū)別。alias會(huì)把location匹配到的路徑替換成指定目錄所以/tiles/15/1/2.png會(huì)映射到/data/map_tiles/15/1/2.png。如果用rootNginx會(huì)把完整URI拼在root目錄后面變成/data/map_tiles/tiles/15/1/2.png目錄結(jié)構(gòu)就錯(cuò)了。這是配置靜態(tài)瓦片服務(wù)時(shí)最容易犯的錯(cuò)。如果前端應(yīng)用部署在另一臺(tái)機(jī)器需要在瓦片服務(wù)的server里加跨域頭add_header Access-Control-Allow-Origin *;否則瀏覽器會(huì)攔截跨域圖片請(qǐng)求地圖白屏。5. 前端交互功能集成Leaflet版離線地圖實(shí)戰(zhàn)5.1 引擎選擇的思路前端引擎我首選Leaflet。相比OpenLayersLeaflet更輕配置簡(jiǎn)單開發(fā)效率高相比MapLibre GLLeaflet對(duì)標(biāo)準(zhǔn)瓦片服務(wù)的兼容性更好學(xué)習(xí)成本也更低。項(xiàng)目只做2D地圖場(chǎng)景Leaflet足夠用。既然瓦片數(shù)據(jù)是高德的為什么不嘗試強(qiáng)行加載高德JS API前面提到過高德JS API離線后內(nèi)部很多接口不可用。即使勉強(qiáng)讓底圖渲染出來了標(biāo)記點(diǎn)、氣泡彈窗這些能力還是依賴它的DOM和事件系統(tǒng)出問題很難排查。用Leaflet替換后渲染和交互全部本地化只把高德當(dāng)作純瓦片數(shù)據(jù)源這個(gè)解耦讓項(xiàng)目穩(wěn)定很多。5.2 初始化和基礎(chǔ)交互初始化地圖加載本地Nginx上的瓦片服務(wù)!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title內(nèi)網(wǎng)離線地圖/title link relstylesheet hrefassets/leaflet/leaflet.css / style html, body, #map { width: 100%; height: 100%; margin: 0; } /style /head body div idmap/div script srcassets/leaflet/leaflet.js/script script const map L.map(map, { center: [39.9042, 116.4074], zoom: 12, minZoom: 3, maxZoom: 17 }); L.tileLayer(http://map.internal:8000/tiles/{z}/{x}/{y}.png, { maxZoom: 17, attribution: Internal Map Service, keepBuffer: 4, updateWhenIdle: false }).addTo(map); /script /body /html這里有兩個(gè)參數(shù)值得說明。keepBuffer: 4表示地圖周圍多加載4圈瓦片讓拖動(dòng)時(shí)不出現(xiàn)白邊閃爍。updateWhenIdle: false則是讓地圖在縮放或平移過程中就持續(xù)加載新瓦片而不是等動(dòng)畫完全停下來才加載。內(nèi)網(wǎng)帶寬低時(shí)這兩項(xiàng)對(duì)體驗(yàn)提升很明顯。Leaflet的縮放、拖拽、雙擊放大、滾輪縮放這些交互默認(rèn)就帶不需要額外配置。如果不希望用戶拖動(dòng)到?jīng)]有瓦片的區(qū)域可以設(shè)置minZoom/maxZoom超出范圍的級(jí)別前端直接不允許瀏覽。5.3 業(yè)務(wù)場(chǎng)景標(biāo)記、彈窗、軌跡與聚合內(nèi)網(wǎng)地圖項(xiàng)目最常見的需求是打點(diǎn)展示設(shè)備位置。用Marker加Popup就能實(shí)現(xiàn)const marker L.marker([39.9042, 116.4074]).addTo(map); marker.bindPopup( b設(shè)備編號(hào)BJ-JK-0001/bbr 狀態(tài)正常運(yùn)行br 最近上報(bào)2025-06-12 10:33 );如果點(diǎn)位數(shù)量幾十上百建議用layerGroup統(tǒng)一管理const markerLayer L.layerGroup().addTo(map); function renderDevices(devices) { markerLayer.clearLayers(); devices.forEach(d { L.marker([d.lat, d.lng]) .bindPopup(d.name) .addTo(markerLayer); }); }上千個(gè)點(diǎn)位時(shí)直接打Marker會(huì)把頁面卡死。這時(shí)候用Leaflet.markercluster插件做聚合。把插件的js和css下載到本地通過相對(duì)路徑引入const clusterLayer L.markerClusterGroup({ maxClusterRadius: 40 }); devices.forEach(d { clusterLayer.addLayer(L.marker([d.lat, d.lng])); }); map.addLayer(clusterLayer);聚合插件的效果是地圖縮放級(jí)別低時(shí)把相近的點(diǎn)聚合成一個(gè)數(shù)字氣泡放大后氣泡拆開交互體驗(yàn)接近在線地圖。軌跡展示是另一個(gè)高頻需求。用L.polyline畫線const trackPoints [ [39.9010, 116.4030], [39.9020, 116.4050], [39.9042, 116.4074], [39.9060, 116.4110] ]; const trackLine L.polyline(trackPoints, { color: #ff6600, weight: 3, opacity: 0.9 }).addTo(map); map.fitBounds(trackLine.getBounds());配合L.circleMarker標(biāo)注軌跡上的關(guān)鍵節(jié)點(diǎn)能做出很直觀的車輛或人員軌跡回放頁面。5.4 坐標(biāo)糾偏與數(shù)據(jù)兼容前面說過GPS原始坐標(biāo)是WGS-84高德瓦片是GCJ-02。如果業(yè)務(wù)數(shù)據(jù)存的是WGS-84必須在前端或后端做一次轉(zhuǎn)換。我貼一份前端JavaScript的通用轉(zhuǎn)換函數(shù)來自開源社區(qū)實(shí)測(cè)過國內(nèi)主流城市可用function transformLat(x, y) { let ret -100.0 2.0 * x 3.0 * y 0.2 * y * y; ret 0.1 * x * y 0.2 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * Math.PI) 20.0 * Math.sin(2.0 * x * Math.PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(y * Math.PI) 40.0 * Math.sin(y / 3.0 * Math.PI)) * 2.0 / 3.0; ret (160.0 * Math.sin(y / 12.0 * Math.PI) 320 * Math.sin(y * Math.PI / 30.0)) * 2.0 / 3.0; return ret; } function transformLng(x, y) { let ret 300.0 x 2.0 * y 0.1 * x * x; ret 0.1 * x * y 0.1 * Math.sqrt(Math.abs(x)); ret (20.0 * Math.sin(6.0 * x * Math.PI) 20.0 * Math.sin(2.0 * x * Math.PI)) * 2.0 / 3.0; ret (20.0 * Math.sin(x * Math.PI) 40.0 * Math.sin(x / 3.0 * Math.PI)) * 2.0 / 3.0; ret (150.0 * Math.sin(x / 12.0 * Math.PI) 300.0 * Math.sin(x / 30.0 * Math.PI)) * 2.0 / 3.0; return ret; } function wgs84ToGcj02(lng, lat) { const a 6378245.0; const ee 0.006693421622965943; let dLat transformLat(lng - 105.0, lat - 35.0); let dLng transformLng(lng - 105.0, lat - 35.0); const radLat lat / 180.0 * Math.PI; let magic Math.sin(radLat); magic 1 - ee * magic * magic; const sqrtMagic Math.sqrt(magic); dLat (dLat * 180.0) / ((a * (1 - ee)) / (magic * sqrtMagic) * Math.PI); dLng (dLng * 180.0) / (a / sqrtMagic * Math.cos(radLat) * Math.PI); return [lng dLng, lat dLat]; }調(diào)用方式很簡(jiǎn)單把GPS采集的原始經(jīng)緯度傳給wgs84ToGcj02返回的坐標(biāo)就是能和底圖對(duì)齊的點(diǎn)。手機(jī)端定位上報(bào)的數(shù)據(jù)以及在蘋果設(shè)備上偶發(fā)的位置偏差問題很多都是因?yàn)槟昧薟GS-84坐標(biāo)沒轉(zhuǎn)換就上圖導(dǎo)致點(diǎn)位看著偏到別人家樓頂。這里要注意緯度值范圍內(nèi)不能把海域計(jì)算跳過否則轉(zhuǎn)換精度下降。實(shí)際使用中只要坐標(biāo)在國土地理范圍內(nèi)統(tǒng)一走這個(gè)函數(shù)即可。6. 常見問題排查與性能調(diào)優(yōu)實(shí)錄6.1 高頻問題速查表做離線地圖項(xiàng)目過程中我遇到最多的一批問題整理成表格方便快速對(duì)照故障現(xiàn)象可能原因解決思路頁面白屏瓦片不顯示Nginx alias/root配置錯(cuò)誤導(dǎo)致404檢查瀏覽器Network確認(rèn)請(qǐng)求URL是否映射到正確目錄部分瓦片灰色或花屏下載時(shí)某個(gè)級(jí)別瓦片缺失或文件損壞用failed_tiles.txt補(bǔ)拉刪除0KB文件重新下載地圖偏移幾百米業(yè)務(wù)數(shù)據(jù)用WGS-84坐標(biāo)疊加GCJ-02底圖數(shù)據(jù)入庫前統(tǒng)一調(diào)用wgs84ToGcj02轉(zhuǎn)換點(diǎn)位出現(xiàn)但標(biāo)記模糊前端沒有引入正確的CSS文件確認(rèn)Leaflet.css和markercluster.css放本地并正確引用了拖動(dòng)地圖頻繁白邊瓦片加載慢keepBuffer設(shè)置過小前端設(shè)置keepBuffer: 4或更大并提前預(yù)取周邊瓦片地圖上POI圖標(biāo)疊成一坨點(diǎn)位太多渲染卡頓改用markercluster聚合或者做Canvas圖層瀏覽器報(bào)跨域錯(cuò)誤前端和瓦片服務(wù)不在同一域名端口在Nginx瓦片服務(wù)里加Access-Control-Allow-Origin頭瓦片404是最常見的拿到路徑后先手動(dòng)在瀏覽器打開瓦片URL確認(rèn)Nginx返回的是圖片而不是錯(cuò)誤頁。如果返回403大概率是沒有配置跨域頭或路徑權(quán)限有問題。6.2 性能調(diào)優(yōu)三板斧第一板斧是瓦片體積控制。從在線數(shù)據(jù)源下載的圖片已經(jīng)比較優(yōu)化但部分瓦片仍然有壓縮空間。批量做一次pngquant壓縮地圖底圖的瓦片體積能降20%到40%。Nginx端再開啟gzip傳輸體積進(jìn)一步下降。壓縮前先備份對(duì)比壓縮后有無肉眼可見的清晰度損失有些底圖文字細(xì)節(jié)會(huì)被壓糊。第二板斧是前端緩存策略。Leaflet對(duì)瓦片有內(nèi)存緩存配合瀏覽器HTTP緩存第二次打開頁面時(shí)大部分瓦片直接從本地緩存讀取請(qǐng)求量會(huì)少很多。如果項(xiàng)目里地圖切換頻率很高可以做一個(gè)內(nèi)存中的瓦片緩存池簡(jiǎn)單做法是維護(hù)一個(gè)Map對(duì)象key用z/x/y拼接value存Image對(duì)象避免重復(fù)創(chuàng)建Image導(dǎo)致內(nèi)存上漲。第三板斧是分層加載。內(nèi)網(wǎng)項(xiàng)目如果地圖資源有幾百GB不可能全部發(fā)布到Nginx后每個(gè)終端都去拉全量數(shù)據(jù)。常見做法是分級(jí)別存儲(chǔ)常用級(jí)別放本地不常用級(jí)別放內(nèi)網(wǎng)NAS或?qū)ο蟠鎯?chǔ)Nginx通過內(nèi)網(wǎng)回源緩存。但因?yàn)閮?nèi)網(wǎng)一般沒有外網(wǎng)回源條件更現(xiàn)實(shí)的方案是按業(yè)務(wù)區(qū)域裁切范圍區(qū)域外不下載區(qū)域內(nèi)盡量覆蓋到需要的最高級(jí)別。還有一個(gè)容易忽略的坑如果內(nèi)網(wǎng)機(jī)器配置不高渲染大屏?xí)r不要同時(shí)開太多Leaflet實(shí)例。多個(gè)頁簽或者多個(gè)大屏都初始化地圖內(nèi)存占用會(huì)疊加。切屏前主動(dòng)調(diào)map.remove()銷毀地圖實(shí)例而不是簡(jiǎn)單隱藏div。這個(gè)排查起來很費(fèi)勁最好在代碼里就養(yǎng)成清理的習(xí)慣。結(jié)尾這套內(nèi)網(wǎng)高德地圖離線化方案做完之后我的直觀感受是真正花時(shí)間的不是技術(shù)實(shí)現(xiàn)本身而是把瓦片數(shù)據(jù)、坐標(biāo)體系和前端工程之間那層說不清道不明的關(guān)聯(lián)徹底搞清楚。尤其是坐標(biāo)轉(zhuǎn)換內(nèi)網(wǎng)項(xiàng)目里數(shù)據(jù)來源五花八門有GPS設(shè)備上報(bào)的有標(biāo)定過的有從第三方平臺(tái)導(dǎo)出的只要有一個(gè)環(huán)節(jié)忘了統(tǒng)一到GCJ-02地圖上就必然出現(xiàn)肉眼可見的偏移。最后再分享一個(gè)小技巧瓦片數(shù)據(jù)下載完成后別急著清理有網(wǎng)環(huán)境的腳本和中間文件。項(xiàng)目上線后業(yè)務(wù)范圍大概率會(huì)調(diào)整今天只要北京城區(qū)明天可能就要擴(kuò)展到天津。把下載腳本、范圍配置、失敗列表都納入版本管理下次擴(kuò)展時(shí)重新跑一遍腳本只增量下載就能快速補(bǔ)齊數(shù)據(jù)不用從頭再來。