網(wǎng)離線化：從瓦片下載到Leaflet部署實戰(zhàn))
前陣子公司一個項目要部署到內(nèi)網(wǎng)環(huán)境業(yè)務(wù)方指著大屏說地圖這塊必須保留而且不能斷網(wǎng)。我盯著需求書看了半天腦子里蹦出來的思路其實已經(jīng)很清晰了——高德地圖離線化。這里說的離線化不是把手機高德APP的離線包下載下來完事而是指在完全隔離的網(wǎng)絡(luò)里把一套可交互的地圖應(yīng)用完整跑起來。整體方案拆開來看就一句話先把高德瓦片數(shù)據(jù)搬到內(nèi)網(wǎng)再用開源GIS引擎渲染這些瓦片實現(xiàn)標(biāo)記、彈窗、軌跡、聚合這些常用交互功能。聽起來不算復(fù)雜但真正動手會發(fā)現(xiàn)里面全是細(xì)節(jié)。從瓦片下載腳本到Nginx發(fā)布從坐標(biāo)糾偏到前端引擎選型每一步都可能踩坑。這篇文章把我從零到一做完的經(jīng)驗完整寫出來適合在內(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)場景的硬約束內(nèi)網(wǎng)環(huán)境最直接的特點就是與外網(wǎng)物理隔離或邏輯隔離。業(yè)務(wù)系統(tǒng)部署在這樣的網(wǎng)絡(luò)里意味著前端頁面無法訪問在線地圖SDK也無法請求任何外網(wǎng)站點。很多做慣了在線地圖開發(fā)的同學(xué)第一個反應(yīng)還是引JSAPI、配Key、調(diào)接口到了內(nèi)網(wǎng)全被卡住。除了網(wǎng)絡(luò)隔離還有幾個現(xiàn)實問題在線版高德JS API的JS文件放在CDN上內(nèi)網(wǎng)訪問不了。即使手動把JS文件下載下來腳本內(nèi)部還會動態(tài)請求驗證、定位、路況等接口全部依賴外網(wǎng)。內(nèi)網(wǎng)環(huán)境多數(shù)也不允許隨意開放外網(wǎng)訪問權(quán)限域名白名單、秘鑰管理都是問題。在線API有配額和計費規(guī)則調(diào)用量大時成本壓不住。所以內(nèi)網(wǎng)地圖項目不能按在線開發(fā)的思路來做。你想保留高德地圖的視覺效果和交互體驗就得把地圖數(shù)據(jù)整體“搬”進來同時把渲染和交互能力也全部本地化。1.2 技術(shù)選型瓦片方案、離線SDK還是自繪當(dāng)時我對比了三條路線高德離線SDK、自繪地圖、瓦片方案。高德官方提供的離線SDK主要面向Android、iOS原生應(yīng)用可以在端側(cè)下載城市離線包。但我們的項目是Web大屏官方JS API并沒有正式離線版。有人試過把JS API的腳本抓到本地再通過代理把運行時請求轉(zhuǎn)發(fā)到內(nèi)網(wǎng)模擬但高德JS內(nèi)部還依賴很多在線服務(wù)接口一旦某個請求失敗地圖渲染就會出問題。維護成本太高容易翻車。自繪地圖這條路最可控但需要自己準(zhǔn)備底圖數(shù)據(jù)、道路數(shù)據(jù)、POI數(shù)據(jù)還要做風(fēng)格渲染項目周期根本不允許。而且沒有專業(yè)美工調(diào)出來的地圖風(fēng)格很難看業(yè)務(wù)方大概率不會接受。瓦片方案是目前最務(wù)實的做法把高德地圖已經(jīng)渲染好的圖片瓦片按層級預(yù)先下載到本地然后通過Nginx發(fā)布成靜態(tài)文件服務(wù)前端用開源引擎加載這些瓦片。優(yōu)點很明顯視覺風(fēng)格和高德在線保持一致地圖數(shù)據(jù)量可控渲染性能高交互能力用開源輪子補齊。1.3 整體鏈路設(shè)計整個鏈路分四段確認(rèn)需要的區(qū)域范圍和最大縮放級別。用腳本把該范圍內(nèi)每個級別的高德瓦片批量下載到本地。在內(nèi)網(wǎng)部署Nginx或其他靜態(tài)文件服務(wù)把瓦片目錄發(fā)布出去。前端頁面用Leaflet等開源GIS引擎加載內(nèi)網(wǎng)瓦片服務(wù)疊加業(yè)務(wù)圖層和交互功能。這套鏈路的關(guān)鍵點在于第2步的瓦片坐標(biāo)換算、第3步的發(fā)布代理以及第4步的坐標(biāo)體系一致性問題。下面逐個展開。2. 動手前先搞懂瓦片規(guī)則與坐標(biāo)體系2.1 XYZ瓦片到底怎么編號很多同學(xué)第一次接觸瓦片時會被一堆數(shù)字搞得頭暈。其實原理很簡單地圖服務(wù)商把全球地圖按金字塔模型切成很多張正方形小圖片每張就是一個瓦片。第0級通常只有1張或2張瓦片越往下放大級別越高瓦片數(shù)量越多。這里用OpenStreetMap推廣開的XYZ規(guī)則這是目前WebGIS最通用的瓦片尋址方式z表示縮放級別。x表示瓦片所在列從西到東從0開始。y表示瓦片所在行從北到南從0開始。高德地圖瓦片在Web端也是按這個規(guī)則組織的只是不同數(shù)據(jù)源的代號和URL模板有所不同。你拿到瓦片服務(wù)的地圖URL后通常只需要把{z}、{x}、{y}三個參數(shù)替換成實際數(shù)值就能直接請求到圖片。比如某一級某個位置的瓦片請求URL模板大概是{你的數(shù)據(jù)源地址}/mapstyle/{z}/{x}/{y}.png?param...具體域名和參數(shù)每個項目不一樣核心是記住替換z/x/y。建議在實際寫腳本前先在瀏覽器地址欄里手改幾組數(shù)字確認(rèn)這套URL模板能正常返回圖片再動手寫批量下載程序。2.2 經(jīng)緯度換算瓦片編號公式與代碼判斷一個地理坐標(biāo)落在哪個瓦片里需要做一次坐標(biāo)換算。公式看起來有一點數(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是緯度的弧度值。這個y公式就是Web Mercator投影的反算不用理解太深知道它是把地球球面坐標(biāo)映射到平面瓦片網(wǎng)格上就行。代碼實現(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是為了代碼簡潔。這個函數(shù)等價于上文公式里的ln(tan(φ) sec(φ))只是Math庫里的反雙曲正弦剛好有這個性質(zhì)寫起來更緊湊。實際下載某個矩形區(qū)域的瓦片時很多人會寫出“先算左上角瓦片再算右下角瓦片然后雙重循環(huán)遍歷”的邏輯。這里有一個必須注意的細(xì)節(jié)瓦片y方向是自北向南遞增的所以左上角的緯度更大右上角經(jīng)度更大。也就是說取范圍時要按下面這種方式算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第一次寫這個邏輯時很容易把左上角和右下角的坐標(biāo)算反導(dǎo)致下載回來的瓦片錯位或缺一大片。把min和max都做一遍比較再用range遍歷是最穩(wěn)妥的寫法。2.3 GCJ-02、WGS-84和Web Mercator的糾葛這是離線地圖開發(fā)里最大的坑也是很多人做得好好的項目突然出現(xiàn)幾百米偏移的根本原因。簡單說國內(nèi)商用地圖服務(wù)商包括高德在對外提供地圖數(shù)據(jù)時坐標(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)直接打到地圖上就會偏移。偏移量不是固定值在北京市區(qū)通常幾百米方向也不完全一致無法通過簡單加減修正。解決辦法有兩種一是業(yè)務(wù)設(shè)備出數(shù)時直接做一次坐標(biāo)轉(zhuǎn)換把WGS-84轉(zhuǎn)成GCJ-02再入庫二是在前端渲染前統(tǒng)一轉(zhuǎn)換。前者更好因為數(shù)據(jù)入庫后是干凈的。后面的章節(jié)我會給出一段可用的轉(zhuǎn)換代碼。這里先記住結(jié)論數(shù)據(jù)坐標(biāo)體系必須和高德瓦片保持一致統(tǒng)一用GCJ-02偏差問題就消失。3. 核心實操編寫瓦片下載腳本3.1 確定下載范圍、級別與體量在下腳本之前先想清楚要下載哪幾級瓦片。內(nèi)網(wǎng)項目常見的地圖展示場景是城市級或園區(qū)級。整體覆蓋可以考慮10到12級看全局業(yè)務(wù)聚焦區(qū)域下載到15級甚至17級。但級別越高瓦片數(shù)量呈4倍增長不是線性的。以北京六環(huán)內(nèi)區(qū)域為例我做過一個粗略估算縮放級別覆蓋場景北京六環(huán)范圍瓦片數(shù)預(yù)計體積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)驗估值具體體積取決于瓦片內(nèi)容復(fù)雜度和圖片壓縮率。地圖內(nèi)容密集的區(qū)域單張瓦片可能到80KB而郊區(qū)純色瓦片可能只有10KB。下載前先按這個量級估算好硬盤空間。不建議一上來就全級別全范圍下載。先下載低級別觀察效果再逐步增加范圍和級別。否則腳本寫錯了或者范圍框大了帶寬和時間成本都很浪費。3.2 Python腳本落地完整實現(xiàn)與踩坑下載腳本我建議用Python寫生態(tài)成熟requests加concurrent.futures就能搞定并發(fā)。貼一段我實際用下來的結(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模板具體按項目數(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(全部下載完成)這段代碼里有幾個當(dāng)時踩坑后加進去的點值得講解。第一是重試機制。有些瓦片服務(wù)對高頻請求會返回429限流重試時加退避時間否則連續(xù)下載幾千張瓦片時很容易被臨時封禁。第二是斷點續(xù)傳。腳本判斷文件存在且大小不為0就跳過避免中途掛了要全部重新下載。第三是失敗列表落盤。下載完成后檢查failed_tiles.txt再針對失敗項單獨補拉比在終端里翻日志高效得多。并發(fā)數(shù)建議控制在8到16之間。開太高容易被數(shù)據(jù)源限流開太低下載幾萬張瓦片會等很久。帶寬和內(nèi)網(wǎng)部署階段通常8線程是平衡點。3.3 內(nèi)網(wǎng)Python環(huán)境的準(zhǔn)備與依賴離線安裝下載腳本理論上可以在有網(wǎng)環(huán)境跑完再把瓦片擺渡進內(nèi)網(wǎng)但實際操作中內(nèi)網(wǎng)服務(wù)器往往也需要跑數(shù)據(jù)處理程序比如瓦片重命名、目錄整理、格式清洗。這時候內(nèi)網(wǎng)機器的Python環(huán)境就要提前準(zhǔn)備好。內(nèi)網(wǎng)Linux機器常見的坑是Python版本過舊。很多國產(chǎn)化Linux服務(wù)器自帶的還是Python 2.7或者3.6跑現(xiàn)代腳本會報語法錯誤。優(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會報ssl相關(guān)錯誤新版Python也裝不上requests這些包。依賴包離線安裝也很簡單在外網(wǎng)機器上執(zhí)行pip download -d /tmp/pkgs requests然后把整個pkgs目錄拷進內(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ù)腳本就不會再缺依賴。4. 用Nginx發(fā)布本地瓦片服務(wù)4.1 目錄結(jié)構(gòu)與命名校驗瓦片下載完成后要檢查目錄是否按標(biāo)準(zhǔn)路徑組織。Nginx靜態(tài)服務(wù)的目錄結(jié)構(gòu)需要和瓦片URL對齊。一個規(guī)范的目錄結(jié)構(gòu)如下/data/map_tiles/ └── 15/ ├── 26000/ │ ├── 13000.png │ ├── 13001.png │ └── ... ├── 26001/ │ └── ... └── ...也就是z目錄下面套x目錄再往下是y.png文件。Leaflet等前端引擎發(fā)請求時會自動替換URL里的{z}/{x}/{y}所以目錄結(jié)構(gòu)必須嚴(yán)格匹配多一層少一層都會404。有時候下載腳本會以不同規(guī)則保存比如把z/x/y寫反了或者文件名缺少擴展名。建議下載完成后寫一個小腳本隨機抽幾十個路徑檢查文件是否存在以及大小是否正常避免部署到Nginx才發(fā)現(xiàn)一堆404。4.2 Nginx配置與緩存策略內(nèi)網(wǎng)訪問量通常不會非常大但大屏項目往往有多個終端同時拉圖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讓瀏覽器緩存一個月可以極大減少重復(fù)請求。access_log建議關(guān)掉否則幾天下來日志文件就能積累幾GB全是瓦片請求記錄。還要注意location的alias與root區(qū)別。alias會把location匹配到的路徑替換成指定目錄所以/tiles/15/1/2.png會映射到/data/map_tiles/15/1/2.png。如果用rootNginx會把完整URI拼在root目錄后面變成/data/map_tiles/tiles/15/1/2.png目錄結(jié)構(gòu)就錯了。這是配置靜態(tài)瓦片服務(wù)時最容易犯的錯。如果前端應(yīng)用部署在另一臺機器需要在瓦片服務(wù)的server里加跨域頭add_header Access-Control-Allow-Origin *;否則瀏覽器會攔截跨域圖片請求地圖白屏。5. 前端交互功能集成Leaflet版離線地圖實戰(zhàn)5.1 引擎選擇的思路前端引擎我首選Leaflet。相比OpenLayersLeaflet更輕配置簡單開發(fā)效率高相比MapLibre GLLeaflet對標(biāo)準(zhǔn)瓦片服務(wù)的兼容性更好學(xué)習(xí)成本也更低。項目只做2D地圖場景Leaflet足夠用。既然瓦片數(shù)據(jù)是高德的為什么不嘗試強行加載高德JS API前面提到過高德JS API離線后內(nèi)部很多接口不可用。即使勉強讓底圖渲染出來了標(biāo)記點、氣泡彈窗這些能力還是依賴它的DOM和事件系統(tǒng)出問題很難排查。用Leaflet替換后渲染和交互全部本地化只把高德當(dāng)作純瓦片數(shù)據(jù)源這個解耦讓項目穩(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這里有兩個參數(shù)值得說明。keepBuffer: 4表示地圖周圍多加載4圈瓦片讓拖動時不出現(xiàn)白邊閃爍。updateWhenIdle: false則是讓地圖在縮放或平移過程中就持續(xù)加載新瓦片而不是等動畫完全停下來才加載。內(nèi)網(wǎng)帶寬低時這兩項對體驗提升很明顯。Leaflet的縮放、拖拽、雙擊放大、滾輪縮放這些交互默認(rèn)就帶不需要額外配置。如果不希望用戶拖動到?jīng)]有瓦片的區(qū)域可以設(shè)置minZoom/maxZoom超出范圍的級別前端直接不允許瀏覽。5.3 業(yè)務(wù)場景標(biāo)記、彈窗、軌跡與聚合內(nèi)網(wǎng)地圖項目最常見的需求是打點展示設(shè)備位置。用Marker加Popup就能實現(xiàn)const marker L.marker([39.9042, 116.4074]).addTo(map); marker.bindPopup( b設(shè)備編號BJ-JK-0001/bbr 狀態(tài)正常運行br 最近上報2025-06-12 10:33 );如果點位數(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); }); }上千個點位時直接打Marker會把頁面卡死。這時候用Leaflet.markercluster插件做聚合。把插件的js和css下載到本地通過相對路徑引入const clusterLayer L.markerClusterGroup({ maxClusterRadius: 40 }); devices.forEach(d { clusterLayer.addLayer(L.marker([d.lat, d.lng])); }); map.addLayer(clusterLayer);聚合插件的效果是地圖縮放級別低時把相近的點聚合成一個數(shù)字氣泡放大后氣泡拆開交互體驗接近在線地圖。軌跡展示是另一個高頻需求。用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é)點能做出很直觀的車輛或人員軌跡回放頁面。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ū)實測過國內(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)用方式很簡單把GPS采集的原始經(jīng)緯度傳給wgs84ToGcj02返回的坐標(biāo)就是能和底圖對齊的點。手機端定位上報的數(shù)據(jù)以及在蘋果設(shè)備上偶發(fā)的位置偏差問題很多都是因為拿了WGS-84坐標(biāo)沒轉(zhuǎn)換就上圖導(dǎo)致點位看著偏到別人家樓頂。這里要注意緯度值范圍內(nèi)不能把海域計算跳過否則轉(zhuǎn)換精度下降。實際使用中只要坐標(biāo)在國土地理范圍內(nèi)統(tǒng)一走這個函數(shù)即可。6. 常見問題排查與性能調(diào)優(yōu)實錄6.1 高頻問題速查表做離線地圖項目過程中我遇到最多的一批問題整理成表格方便快速對照故障現(xiàn)象可能原因解決思路頁面白屏瓦片不顯示Nginx alias/root配置錯誤導(dǎo)致404檢查瀏覽器Network確認(rèn)請求URL是否映射到正確目錄部分瓦片灰色或花屏下載時某個級別瓦片缺失或文件損壞用failed_tiles.txt補拉刪除0KB文件重新下載地圖偏移幾百米業(yè)務(wù)數(shù)據(jù)用WGS-84坐標(biāo)疊加GCJ-02底圖數(shù)據(jù)入庫前統(tǒng)一調(diào)用wgs84ToGcj02轉(zhuǎn)換點位出現(xiàn)但標(biāo)記模糊前端沒有引入正確的CSS文件確認(rèn)Leaflet.css和markercluster.css放本地并正確引用了拖動地圖頻繁白邊瓦片加載慢keepBuffer設(shè)置過小前端設(shè)置keepBuffer: 4或更大并提前預(yù)取周邊瓦片地圖上POI圖標(biāo)疊成一坨點位太多渲染卡頓改用markercluster聚合或者做Canvas圖層瀏覽器報跨域錯誤前端和瓦片服務(wù)不在同一域名端口在Nginx瓦片服務(wù)里加Access-Control-Allow-Origin頭瓦片404是最常見的拿到路徑后先手動在瀏覽器打開瓦片URL確認(rèn)Nginx返回的是圖片而不是錯誤頁。如果返回403大概率是沒有配置跨域頭或路徑權(quán)限有問題。6.2 性能調(diào)優(yōu)三板斧第一板斧是瓦片體積控制。從在線數(shù)據(jù)源下載的圖片已經(jīng)比較優(yōu)化但部分瓦片仍然有壓縮空間。批量做一次pngquant壓縮地圖底圖的瓦片體積能降20%到40%。Nginx端再開啟gzip傳輸體積進一步下降。壓縮前先備份對比壓縮后有無肉眼可見的清晰度損失有些底圖文字細(xì)節(jié)會被壓糊。第二板斧是前端緩存策略。Leaflet對瓦片有內(nèi)存緩存配合瀏覽器HTTP緩存第二次打開頁面時大部分瓦片直接從本地緩存讀取請求量會少很多。如果項目里地圖切換頻率很高可以做一個內(nèi)存中的瓦片緩存池簡單做法是維護一個Map對象key用z/x/y拼接value存Image對象避免重復(fù)創(chuàng)建Image導(dǎo)致內(nèi)存上漲。第三板斧是分層加載。內(nèi)網(wǎng)項目如果地圖資源有幾百GB不可能全部發(fā)布到Nginx后每個終端都去拉全量數(shù)據(jù)。常見做法是分級別存儲常用級別放本地不常用級別放內(nèi)網(wǎng)NAS或?qū)ο蟠鎯ginx通過內(nèi)網(wǎng)回源緩存。但因為內(nèi)網(wǎng)一般沒有外網(wǎng)回源條件更現(xiàn)實的方案是按業(yè)務(wù)區(qū)域裁切范圍區(qū)域外不下載區(qū)域內(nèi)盡量覆蓋到需要的最高級別。還有一個容易忽略的坑如果內(nèi)網(wǎng)機器配置不高渲染大屏?xí)r不要同時開太多Leaflet實例。多個頁簽或者多個大屏都初始化地圖內(nèi)存占用會疊加。切屏前主動調(diào)map.remove()銷毀地圖實例而不是簡單隱藏div。這個排查起來很費勁最好在代碼里就養(yǎng)成清理的習(xí)慣。結(jié)尾這套內(nèi)網(wǎng)高德地圖離線化方案做完之后我的直觀感受是真正花時間的不是技術(shù)實現(xiàn)本身而是把瓦片數(shù)據(jù)、坐標(biāo)體系和前端工程之間那層說不清道不明的關(guān)聯(lián)徹底搞清楚。尤其是坐標(biāo)轉(zhuǎn)換內(nèi)網(wǎng)項目里數(shù)據(jù)來源五花八門有GPS設(shè)備上報的有標(biāo)定過的有從第三方平臺導(dǎo)出的只要有一個環(huán)節(jié)忘了統(tǒng)一到GCJ-02地圖上就必然出現(xiàn)肉眼可見的偏移。最后再分享一個小技巧瓦片數(shù)據(jù)下載完成后別急著清理有網(wǎng)環(huán)境的腳本和中間文件。項目上線后業(yè)務(wù)范圍大概率會調(diào)整今天只要北京城區(qū)明天可能就要擴展到天津。把下載腳本、范圍配置、失敗列表都納入版本管理下次擴展時重新跑一遍腳本只增量下載就能快速補齊數(shù)據(jù)不用從頭再來。 高德地圖內(nèi)網(wǎng)離線化：從瓦片下載到Leaflet部署實戰(zhàn)
前陣子公司一個項目要部署到內(nèi)網(wǎng)環(huán)境業(yè)務(wù)方指著大屏說地圖這塊必須保留而且不能斷網(wǎng)。我盯著需求書看了半天腦子里蹦出來的思路其實已經(jīng)很清晰了——高德地圖離線化。這里說的離線化不是把手機高德APP的離線包下載下來完事而是指在完全隔離的網(wǎng)絡(luò)里把一套可交互的地圖應(yīng)用完整跑起來。整體方案拆開來看就一句話先把高德瓦片數(shù)據(jù)搬到內(nèi)網(wǎng)再用開源GIS引擎渲染這些瓦片實現(xiàn)標(biāo)記、彈窗、軌跡、聚合這些常用交互功能。聽起來不算復(fù)雜但真正動手會發(fā)現(xiàn)里面全是細(xì)節(jié)。從瓦片下載腳本到Nginx發(fā)布從坐標(biāo)糾偏到前端引擎選型每一步都可能踩坑。這篇文章把我從零到一做完的經(jīng)驗完整寫出來適合在內(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)場景的硬約束內(nèi)網(wǎng)環(huán)境最直接的特點就是與外網(wǎng)物理隔離或邏輯隔離。業(yè)務(wù)系統(tǒng)部署在這樣的網(wǎng)絡(luò)里意味著前端頁面無法訪問在線地圖SDK也無法請求任何外網(wǎng)站點。很多做慣了在線地圖開發(fā)的同學(xué)第一個反應(yīng)還是引JSAPI、配Key、調(diào)接口到了內(nèi)網(wǎng)全被卡住。除了網(wǎng)絡(luò)隔離還有幾個現(xiàn)實問題在線版高德JS API的JS文件放在CDN上內(nèi)網(wǎng)訪問不了。即使手動把JS文件下載下來腳本內(nèi)部還會動態(tài)請求驗證、定位、路況等接口全部依賴外網(wǎng)。內(nèi)網(wǎng)環(huán)境多數(shù)也不允許隨意開放外網(wǎng)訪問權(quán)限域名白名單、秘鑰管理都是問題。在線API有配額和計費規(guī)則調(diào)用量大時成本壓不住。所以內(nèi)網(wǎng)地圖項目不能按在線開發(fā)的思路來做。你想保留高德地圖的視覺效果和交互體驗就得把地圖數(shù)據(jù)整體“搬”進來同時把渲染和交互能力也全部本地化。1.2 技術(shù)選型瓦片方案、離線SDK還是自繪當(dāng)時我對比了三條路線高德離線SDK、自繪地圖、瓦片方案。高德官方提供的離線SDK主要面向Android、iOS原生應(yīng)用可以在端側(cè)下載城市離線包。但我們的項目是Web大屏官方JS API并沒有正式離線版。有人試過把JS API的腳本抓到本地再通過代理把運行時請求轉(zhuǎn)發(fā)到內(nèi)網(wǎng)模擬但高德JS內(nèi)部還依賴很多在線服務(wù)接口一旦某個請求失敗地圖渲染就會出問題。維護成本太高容易翻車。自繪地圖這條路最可控但需要自己準(zhǔn)備底圖數(shù)據(jù)、道路數(shù)據(jù)、POI數(shù)據(jù)還要做風(fēng)格渲染項目周期根本不允許。而且沒有專業(yè)美工調(diào)出來的地圖風(fēng)格很難看業(yè)務(wù)方大概率不會接受。瓦片方案是目前最務(wù)實的做法把高德地圖已經(jīng)渲染好的圖片瓦片按層級預(yù)先下載到本地然后通過Nginx發(fā)布成靜態(tài)文件服務(wù)前端用開源引擎加載這些瓦片。優(yōu)點很明顯視覺風(fēng)格和高德在線保持一致地圖數(shù)據(jù)量可控渲染性能高交互能力用開源輪子補齊。1.3 整體鏈路設(shè)計整個鏈路分四段確認(rèn)需要的區(qū)域范圍和最大縮放級別。用腳本把該范圍內(nèi)每個級別的高德瓦片批量下載到本地。在內(nèi)網(wǎng)部署Nginx或其他靜態(tài)文件服務(wù)把瓦片目錄發(fā)布出去。前端頁面用Leaflet等開源GIS引擎加載內(nèi)網(wǎng)瓦片服務(wù)疊加業(yè)務(wù)圖層和交互功能。這套鏈路的關(guān)鍵點在于第2步的瓦片坐標(biāo)換算、第3步的發(fā)布代理以及第4步的坐標(biāo)體系一致性問題。下面逐個展開。2. 動手前先搞懂瓦片規(guī)則與坐標(biāo)體系2.1 XYZ瓦片到底怎么編號很多同學(xué)第一次接觸瓦片時會被一堆數(shù)字搞得頭暈。其實原理很簡單地圖服務(wù)商把全球地圖按金字塔模型切成很多張正方形小圖片每張就是一個瓦片。第0級通常只有1張或2張瓦片越往下放大級別越高瓦片數(shù)量越多。這里用OpenStreetMap推廣開的XYZ規(guī)則這是目前WebGIS最通用的瓦片尋址方式z表示縮放級別。x表示瓦片所在列從西到東從0開始。y表示瓦片所在行從北到南從0開始。高德地圖瓦片在Web端也是按這個規(guī)則組織的只是不同數(shù)據(jù)源的代號和URL模板有所不同。你拿到瓦片服務(wù)的地圖URL后通常只需要把{z}、{x}、{y}三個參數(shù)替換成實際數(shù)值就能直接請求到圖片。比如某一級某個位置的瓦片請求URL模板大概是{你的數(shù)據(jù)源地址}/mapstyle/{z}/{x}/{y}.png?param...具體域名和參數(shù)每個項目不一樣核心是記住替換z/x/y。建議在實際寫腳本前先在瀏覽器地址欄里手改幾組數(shù)字確認(rèn)這套URL模板能正常返回圖片再動手寫批量下載程序。2.2 經(jīng)緯度換算瓦片編號公式與代碼判斷一個地理坐標(biāo)落在哪個瓦片里需要做一次坐標(biāo)換算。公式看起來有一點數(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是緯度的弧度值。這個y公式就是Web Mercator投影的反算不用理解太深知道它是把地球球面坐標(biāo)映射到平面瓦片網(wǎng)格上就行。代碼實現(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是為了代碼簡潔。這個函數(shù)等價于上文公式里的ln(tan(φ) sec(φ))只是Math庫里的反雙曲正弦剛好有這個性質(zhì)寫起來更緊湊。實際下載某個矩形區(qū)域的瓦片時很多人會寫出“先算左上角瓦片再算右下角瓦片然后雙重循環(huán)遍歷”的邏輯。這里有一個必須注意的細(xì)節(jié)瓦片y方向是自北向南遞增的所以左上角的緯度更大右上角經(jīng)度更大。也就是說取范圍時要按下面這種方式算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第一次寫這個邏輯時很容易把左上角和右下角的坐標(biāo)算反導(dǎo)致下載回來的瓦片錯位或缺一大片。把min和max都做一遍比較再用range遍歷是最穩(wěn)妥的寫法。2.3 GCJ-02、WGS-84和Web Mercator的糾葛這是離線地圖開發(fā)里最大的坑也是很多人做得好好的項目突然出現(xiàn)幾百米偏移的根本原因。簡單說國內(nèi)商用地圖服務(wù)商包括高德在對外提供地圖數(shù)據(jù)時坐標(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)直接打到地圖上就會偏移。偏移量不是固定值在北京市區(qū)通常幾百米方向也不完全一致無法通過簡單加減修正。解決辦法有兩種一是業(yè)務(wù)設(shè)備出數(shù)時直接做一次坐標(biāo)轉(zhuǎn)換把WGS-84轉(zhuǎn)成GCJ-02再入庫二是在前端渲染前統(tǒng)一轉(zhuǎn)換。前者更好因為數(shù)據(jù)入庫后是干凈的。后面的章節(jié)我會給出一段可用的轉(zhuǎn)換代碼。這里先記住結(jié)論數(shù)據(jù)坐標(biāo)體系必須和高德瓦片保持一致統(tǒng)一用GCJ-02偏差問題就消失。3. 核心實操編寫瓦片下載腳本3.1 確定下載范圍、級別與體量在下腳本之前先想清楚要下載哪幾級瓦片。內(nèi)網(wǎng)項目常見的地圖展示場景是城市級或園區(qū)級。整體覆蓋可以考慮10到12級看全局業(yè)務(wù)聚焦區(qū)域下載到15級甚至17級。但級別越高瓦片數(shù)量呈4倍增長不是線性的。以北京六環(huán)內(nèi)區(qū)域為例我做過一個粗略估算縮放級別覆蓋場景北京六環(huán)范圍瓦片數(shù)預(yù)計體積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)驗估值具體體積取決于瓦片內(nèi)容復(fù)雜度和圖片壓縮率。地圖內(nèi)容密集的區(qū)域單張瓦片可能到80KB而郊區(qū)純色瓦片可能只有10KB。下載前先按這個量級估算好硬盤空間。不建議一上來就全級別全范圍下載。先下載低級別觀察效果再逐步增加范圍和級別。否則腳本寫錯了或者范圍框大了帶寬和時間成本都很浪費。3.2 Python腳本落地完整實現(xiàn)與踩坑下載腳本我建議用Python寫生態(tài)成熟requests加concurrent.futures就能搞定并發(fā)。貼一段我實際用下來的結(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模板具體按項目數(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(全部下載完成)這段代碼里有幾個當(dāng)時踩坑后加進去的點值得講解。第一是重試機制。有些瓦片服務(wù)對高頻請求會返回429限流重試時加退避時間否則連續(xù)下載幾千張瓦片時很容易被臨時封禁。第二是斷點續(xù)傳。腳本判斷文件存在且大小不為0就跳過避免中途掛了要全部重新下載。第三是失敗列表落盤。下載完成后檢查failed_tiles.txt再針對失敗項單獨補拉比在終端里翻日志高效得多。并發(fā)數(shù)建議控制在8到16之間。開太高容易被數(shù)據(jù)源限流開太低下載幾萬張瓦片會等很久。帶寬和內(nèi)網(wǎng)部署階段通常8線程是平衡點。3.3 內(nèi)網(wǎng)Python環(huán)境的準(zhǔn)備與依賴離線安裝下載腳本理論上可以在有網(wǎng)環(huán)境跑完再把瓦片擺渡進內(nèi)網(wǎng)但實際操作中內(nèi)網(wǎng)服務(wù)器往往也需要跑數(shù)據(jù)處理程序比如瓦片重命名、目錄整理、格式清洗。這時候內(nèi)網(wǎng)機器的Python環(huán)境就要提前準(zhǔn)備好。內(nèi)網(wǎng)Linux機器常見的坑是Python版本過舊。很多國產(chǎn)化Linux服務(wù)器自帶的還是Python 2.7或者3.6跑現(xiàn)代腳本會報語法錯誤。優(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會報ssl相關(guān)錯誤新版Python也裝不上requests這些包。依賴包離線安裝也很簡單在外網(wǎng)機器上執(zhí)行pip download -d /tmp/pkgs requests然后把整個pkgs目錄拷進內(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ù)腳本就不會再缺依賴。4. 用Nginx發(fā)布本地瓦片服務(wù)4.1 目錄結(jié)構(gòu)與命名校驗瓦片下載完成后要檢查目錄是否按標(biāo)準(zhǔn)路徑組織。Nginx靜態(tài)服務(wù)的目錄結(jié)構(gòu)需要和瓦片URL對齊。一個規(guī)范的目錄結(jié)構(gòu)如下/data/map_tiles/ └── 15/ ├── 26000/ │ ├── 13000.png │ ├── 13001.png │ └── ... ├── 26001/ │ └── ... └── ...也就是z目錄下面套x目錄再往下是y.png文件。Leaflet等前端引擎發(fā)請求時會自動替換URL里的{z}/{x}/{y}所以目錄結(jié)構(gòu)必須嚴(yán)格匹配多一層少一層都會404。有時候下載腳本會以不同規(guī)則保存比如把z/x/y寫反了或者文件名缺少擴展名。建議下載完成后寫一個小腳本隨機抽幾十個路徑檢查文件是否存在以及大小是否正常避免部署到Nginx才發(fā)現(xiàn)一堆404。4.2 Nginx配置與緩存策略內(nèi)網(wǎng)訪問量通常不會非常大但大屏項目往往有多個終端同時拉圖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讓瀏覽器緩存一個月可以極大減少重復(fù)請求。access_log建議關(guān)掉否則幾天下來日志文件就能積累幾GB全是瓦片請求記錄。還要注意location的alias與root區(qū)別。alias會把location匹配到的路徑替換成指定目錄所以/tiles/15/1/2.png會映射到/data/map_tiles/15/1/2.png。如果用rootNginx會把完整URI拼在root目錄后面變成/data/map_tiles/tiles/15/1/2.png目錄結(jié)構(gòu)就錯了。這是配置靜態(tài)瓦片服務(wù)時最容易犯的錯。如果前端應(yīng)用部署在另一臺機器需要在瓦片服務(wù)的server里加跨域頭add_header Access-Control-Allow-Origin *;否則瀏覽器會攔截跨域圖片請求地圖白屏。5. 前端交互功能集成Leaflet版離線地圖實戰(zhàn)5.1 引擎選擇的思路前端引擎我首選Leaflet。相比OpenLayersLeaflet更輕配置簡單開發(fā)效率高相比MapLibre GLLeaflet對標(biāo)準(zhǔn)瓦片服務(wù)的兼容性更好學(xué)習(xí)成本也更低。項目只做2D地圖場景Leaflet足夠用。既然瓦片數(shù)據(jù)是高德的為什么不嘗試強行加載高德JS API前面提到過高德JS API離線后內(nèi)部很多接口不可用。即使勉強讓底圖渲染出來了標(biāo)記點、氣泡彈窗這些能力還是依賴它的DOM和事件系統(tǒng)出問題很難排查。用Leaflet替換后渲染和交互全部本地化只把高德當(dāng)作純瓦片數(shù)據(jù)源這個解耦讓項目穩(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這里有兩個參數(shù)值得說明。keepBuffer: 4表示地圖周圍多加載4圈瓦片讓拖動時不出現(xiàn)白邊閃爍。updateWhenIdle: false則是讓地圖在縮放或平移過程中就持續(xù)加載新瓦片而不是等動畫完全停下來才加載。內(nèi)網(wǎng)帶寬低時這兩項對體驗提升很明顯。Leaflet的縮放、拖拽、雙擊放大、滾輪縮放這些交互默認(rèn)就帶不需要額外配置。如果不希望用戶拖動到?jīng)]有瓦片的區(qū)域可以設(shè)置minZoom/maxZoom超出范圍的級別前端直接不允許瀏覽。5.3 業(yè)務(wù)場景標(biāo)記、彈窗、軌跡與聚合內(nèi)網(wǎng)地圖項目最常見的需求是打點展示設(shè)備位置。用Marker加Popup就能實現(xiàn)const marker L.marker([39.9042, 116.4074]).addTo(map); marker.bindPopup( b設(shè)備編號BJ-JK-0001/bbr 狀態(tài)正常運行br 最近上報2025-06-12 10:33 );如果點位數(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); }); }上千個點位時直接打Marker會把頁面卡死。這時候用Leaflet.markercluster插件做聚合。把插件的js和css下載到本地通過相對路徑引入const clusterLayer L.markerClusterGroup({ maxClusterRadius: 40 }); devices.forEach(d { clusterLayer.addLayer(L.marker([d.lat, d.lng])); }); map.addLayer(clusterLayer);聚合插件的效果是地圖縮放級別低時把相近的點聚合成一個數(shù)字氣泡放大后氣泡拆開交互體驗接近在線地圖。軌跡展示是另一個高頻需求。用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é)點能做出很直觀的車輛或人員軌跡回放頁面。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ū)實測過國內(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)用方式很簡單把GPS采集的原始經(jīng)緯度傳給wgs84ToGcj02返回的坐標(biāo)就是能和底圖對齊的點。手機端定位上報的數(shù)據(jù)以及在蘋果設(shè)備上偶發(fā)的位置偏差問題很多都是因為拿了WGS-84坐標(biāo)沒轉(zhuǎn)換就上圖導(dǎo)致點位看著偏到別人家樓頂。這里要注意緯度值范圍內(nèi)不能把海域計算跳過否則轉(zhuǎn)換精度下降。實際使用中只要坐標(biāo)在國土地理范圍內(nèi)統(tǒng)一走這個函數(shù)即可。6. 常見問題排查與性能調(diào)優(yōu)實錄6.1 高頻問題速查表做離線地圖項目過程中我遇到最多的一批問題整理成表格方便快速對照故障現(xiàn)象可能原因解決思路頁面白屏瓦片不顯示Nginx alias/root配置錯誤導(dǎo)致404檢查瀏覽器Network確認(rèn)請求URL是否映射到正確目錄部分瓦片灰色或花屏下載時某個級別瓦片缺失或文件損壞用failed_tiles.txt補拉刪除0KB文件重新下載地圖偏移幾百米業(yè)務(wù)數(shù)據(jù)用WGS-84坐標(biāo)疊加GCJ-02底圖數(shù)據(jù)入庫前統(tǒng)一調(diào)用wgs84ToGcj02轉(zhuǎn)換點位出現(xiàn)但標(biāo)記模糊前端沒有引入正確的CSS文件確認(rèn)Leaflet.css和markercluster.css放本地并正確引用了拖動地圖頻繁白邊瓦片加載慢keepBuffer設(shè)置過小前端設(shè)置keepBuffer: 4或更大并提前預(yù)取周邊瓦片地圖上POI圖標(biāo)疊成一坨點位太多渲染卡頓改用markercluster聚合或者做Canvas圖層瀏覽器報跨域錯誤前端和瓦片服務(wù)不在同一域名端口在Nginx瓦片服務(wù)里加Access-Control-Allow-Origin頭瓦片404是最常見的拿到路徑后先手動在瀏覽器打開瓦片URL確認(rèn)Nginx返回的是圖片而不是錯誤頁。如果返回403大概率是沒有配置跨域頭或路徑權(quán)限有問題。6.2 性能調(diào)優(yōu)三板斧第一板斧是瓦片體積控制。從在線數(shù)據(jù)源下載的圖片已經(jīng)比較優(yōu)化但部分瓦片仍然有壓縮空間。批量做一次pngquant壓縮地圖底圖的瓦片體積能降20%到40%。Nginx端再開啟gzip傳輸體積進一步下降。壓縮前先備份對比壓縮后有無肉眼可見的清晰度損失有些底圖文字細(xì)節(jié)會被壓糊。第二板斧是前端緩存策略。Leaflet對瓦片有內(nèi)存緩存配合瀏覽器HTTP緩存第二次打開頁面時大部分瓦片直接從本地緩存讀取請求量會少很多。如果項目里地圖切換頻率很高可以做一個內(nèi)存中的瓦片緩存池簡單做法是維護一個Map對象key用z/x/y拼接value存Image對象避免重復(fù)創(chuàng)建Image導(dǎo)致內(nèi)存上漲。第三板斧是分層加載。內(nèi)網(wǎng)項目如果地圖資源有幾百GB不可能全部發(fā)布到Nginx后每個終端都去拉全量數(shù)據(jù)。常見做法是分級別存儲常用級別放本地不常用級別放內(nèi)網(wǎng)NAS或?qū)ο蟠鎯ginx通過內(nèi)網(wǎng)回源緩存。但因為內(nèi)網(wǎng)一般沒有外網(wǎng)回源條件更現(xiàn)實的方案是按業(yè)務(wù)區(qū)域裁切范圍區(qū)域外不下載區(qū)域內(nèi)盡量覆蓋到需要的最高級別。還有一個容易忽略的坑如果內(nèi)網(wǎng)機器配置不高渲染大屏?xí)r不要同時開太多Leaflet實例。多個頁簽或者多個大屏都初始化地圖內(nèi)存占用會疊加。切屏前主動調(diào)map.remove()銷毀地圖實例而不是簡單隱藏div。這個排查起來很費勁最好在代碼里就養(yǎng)成清理的習(xí)慣。結(jié)尾這套內(nèi)網(wǎng)高德地圖離線化方案做完之后我的直觀感受是真正花時間的不是技術(shù)實現(xiàn)本身而是把瓦片數(shù)據(jù)、坐標(biāo)體系和前端工程之間那層說不清道不明的關(guān)聯(lián)徹底搞清楚。尤其是坐標(biāo)轉(zhuǎn)換內(nèi)網(wǎng)項目里數(shù)據(jù)來源五花八門有GPS設(shè)備上報的有標(biāo)定過的有從第三方平臺導(dǎo)出的只要有一個環(huán)節(jié)忘了統(tǒng)一到GCJ-02地圖上就必然出現(xiàn)肉眼可見的偏移。最后再分享一個小技巧瓦片數(shù)據(jù)下載完成后別急著清理有網(wǎng)環(huán)境的腳本和中間文件。項目上線后業(yè)務(wù)范圍大概率會調(diào)整今天只要北京城區(qū)明天可能就要擴展到天津。把下載腳本、范圍配置、失敗列表都納入版本管理下次擴展時重新跑一遍腳本只增量下載就能快速補齊數(shù)據(jù)不用從頭再來。