企业官网建设流程全解析

最近在 Vue 3.0 项目里接了一个地图需求：做一个离线百度地图，限制区域显示，只展示某个城市。用户不能拖到隔壁城市去，瓦片不能依赖外网在线加载，还得在 Vue 3.0 组件里干干净净地集成。

需求描述只有一句话，真正落地时才发现牵扯到瓦片下载、坐标对齐、组件生命周期、边界控制好几个硬骨头。这篇文章把我从选型到落地的完整过程整理出来，给正在做 vue3.0 开发离线百度地图、或者做内网地图展示的朋友们做个参考。你能从这里拿到可复现的代码思路、瓦片准备流程、越界控制的实测方案，也能避开我在实际开发中踩过的坑。

1. 需求拆解：先弄清楚离线地图限制城市显示要解决哪几件事

1.1 需求背后的三个真实痛点

标题里每个关键词都对应一个实际问题。

“离线百度地图”意味着不能直接依赖在线瓦片服务。普通模式下新建一个 BMap.Map，地图会自动去地图服务器拉瓦片，内网部署环境下这些请求全部失败，页面就是一片空白。所以准备一套本地瓦片资源是绕不开的第一步。

“限制区域显示，只展示某个城市的地图”也不是简单地把视野中心定在城市就完事。用户拖动、滚轮缩放、双击放大，任何一个操作都可能把视野带到城市边界之外。一旦出界，不仅会暴露城市外的空白瓦片，还会让整个页面的“只展示某城市”失去意义。

“Vue 3.0开发”则是团队技术栈的要求。百度地图 JS API 本质上是全局脚本加原生事件模型，跟 Vue 组件的响应式、生命周期、卸载销毁都要额外做一层适配，不能按传统 jQuery 时代的写法直接裸用。

这三个词叠加在一起，就不是网上随便搜一篇地图 Demo 能解决的问题了。

1.2 方案选型：为什么选 BMap v3.0 而不是 BMapGL

做地图方案选型时，我第一时间对比了传统 BMap v3.0 和 BMapGL。

BMapGL 确实很新，很多功能更贴近现代地图引擎，还提供了更直接的范围限制方法，比如说限制地图视野不超出某块矩形区域。但考虑到这次的核心诉求是离线瓦片自绘和 Vue 3.0 组件内可控集成，BMapGL 的自定义图层机制和文档成熟度还没到让我放心使用的程度。

传统 BMap v3.0 的优势在于：

• 自定义 MapType 的用法相对成熟，可以直接接管底图瓦片请求。
• 全局 API 简单，BMap.Map、BMap.Point、BMap.TileLayer 这些核心对象文档和社区案例很多。
• 对 Vue 3.0 来说没有框架层面的冲突，只是要处理好加载时机和销毁时机。

下面是当时做的方案对比：

最终选定传统 BMap v3.0 + 自定义瓦片底图 + 事件纠偏控制边界，这个组合是目前落地离线城市地图比较稳的路径。

1.3 “只展示某个城市”到底怎么理解

这里要做一个产品层面的定义。日常开发中常有两种理解方式：

第一种是“视野范围限制”。地图打开后，中心点在城市内，用户可以在城市范围内拖动，但不能拖出城市矩形边界。这是一般地图功能的常规诉求。

第二种是“辐射范围限制”。只在地图上展示城市范围的瓦片和标注，城市外完全没有数据，用户即使拖出去了也没东西看，甚至视觉上直接一片灰。

我在这次项目里把两种都做了。操作层面用视野范围限制，数据层面用瓦片裁剪保证城市外没有可加载的内容。两者结合，才能做到标题期待的“限制区域显示，只展示某个城市的地图”。

有了这层清晰的认知，后续的每一项代码决策都有据可依。

2. 离线瓦片准备：城市地图的本地资源从哪来

2.1 瓦片金字塔与坐标体系

地图瓦片本质上就是把一整张世界地图按缩放级别切成若干正方形小图。zoom 级别越大，瓦片数量越多，单个瓦片对应的地理范围越小。整个结构像金字塔，底层是少数几张全球瓦片，高层是密密麻麻的城市街道。

这里最关键的一点是：百度地图的瓦片坐标体系是独立的。它基于百度自己的墨卡托投影划分瓦片行列号，和常见的“谷歌 XYZ”切片规则不是一回事。也就是说，你用通用地图下载工具下载的 XYZ 瓦片，直接喂给 BMap 的自定义 TileLayer，出来的效果大概率是位置错乱的。

我实际见过有同事把一套很完整的开源城市瓦片塞进 BMap，结果道路全错位，排查了一天才发现是坐标体系对不上。

所以准备离线瓦片的第一原则是：必须用百度地图坐标系下的瓦片资源，或者通过 BMap 自己暴露的瓦片坐标回调来生成下载清单。

2.2 确定城市范围和缩放级别

开发前先要明确城市在地图上的经纬度矩形范围。不需要精确到行政边界，先给一个包含主要城区的矩形即可，后续可以在遮罩层上再优化。比如项目里维护一份配置：

// src/config/map.ts export const MIN_ZOOM = 10 export const MAX_ZOOM = 15 export const CITY_CENTER = { lng: 0.0, lat: 0.0 } // 替换为目标城市的中心坐标 export const CITY_BOUNDS = { west: 0.0, // 替换为最小经度 south: 0.0, // 替换为最小纬度 east: 0.0, // 替换为最大经度 north: 0.0, // 替换为最大纬度 }

缩放级别的选择直接决定瓦片数量。级别跨度不能太大，普通城市的离线展示控制在 10 到 15 级，足够看清街道和小区轮廓，瓦片量也在可控范围内。

瓦片数量的增长速度很夸张，zoom 每增加一级，瓦片总数约为原来的四倍。单看某个城市范围的话，不同级别的数量大致可以按这种方式估算：把城市边界在每一级对应的瓦片行列号范围算出来，相乘就是该级所需瓦片数。叠加 10 到 15 级，总瓦片量通常在几千到几万张之间，压缩后几百 MB 以内，对现代应用服务器来说可以接受。

如果城市范围特别大，或者要展示到 16 级以上楼栋级别，建议按城区分块处理，不要一次性把所有瓦片塞进前端静态目录。

2.3 批量下载城市瓦片的两种可行方式

离线瓦片的来源有两种比较稳的路径。

第一种：临时写一个在线 BMap 调试页面，把地图中心定位到目标城市，再通过网络面板收集真实瓦片请求，然后把瓦片 URL 模板提取出来批量下载。这个方法最可靠，因为瓦片 URL 里的 x、y、z 就是 BMap 自己使用的坐标参数，不会出现坐标体系错位的问题。

核心思路是在页面里写一段遍历逻辑，针对每个 zoom 级别，把城市边界范围内涉及的瓦片行列号全部列出来，再拼出下载地址。可以参考下面的逻辑：

// 伪代码：BMap 页面控制台调试用 function collectTiles(zoom) { const projection = map.getMapType().getProjection() const bounds = map.getBounds() const swPixel = projection.lngLatToPoint(bounds.getSouthWest()) const nePixel = projection.lngLatToPoint(bounds.getNorthEast()) // 不同级别下像素坐标与瓦片坐标的换算关系 const minX = Math.floor(swPixel.x / 256) const maxX = Math.floor(nePixel.x / 256) const minY = Math.floor(nePixel.y / 256) const maxY = Math.floor(swPixel.y / 256) for (let x = minX; x <= maxX; x++) { for (let y = minY; y <= maxY; y++) { console.log(`${zoom}/${x}/${y}`) } } }

需要注意像素坐标和瓦片坐标的关系在不同投影算法下可能方向相反。我调试的时候遇到过 y 轴反转的情况，表现为下载出来的瓦片拼接后上下颠倒。这时把 y 的遍历范围反转再试一次就能解决。

拿到坐标清单后，用脚本批量下载到本地：

# 批量瓦片下载脚本示意 import os import requests base_url = "https://your-tile-host/?qt=tile&x={x}&y={y}&z={z}" # 替换为调试页抓到的瓦片模板 output_root = "./tiles" def download_tile(z, x, y): path = f"{output_root}/{z}/{x}/{y}.png" os.makedirs(os.path.dirname(path), exist_ok=True) url = base_url.format(x=x, y=y, z=z) resp = requests.get(url, timeout=10) if resp.status_code == 200: with open(path, "wb") as f: f.write(resp.content) # 遍历准备好的坐标清单 for z, x, y in tile_list: download_tile(z, x, y)

第二种：使用支持百度坐标系的瓦片下载工具。市面上不少离线地图工具会提供“高德/百度/谷歌坐标系”切换，选择百度坐标系后，直接框选城市范围下载即可。

无论用哪种方式，下载完一定要抽查几张瓦片，放到浏览器里和在线地图对比一下位置，确认没有错位再进行下一阶段。

2.4 瓦片目录规划与部署体积控制

离线瓦片保存在 Vue 项目里时，我推荐放在 public 目录下，这样构建时会被原样拷贝到打包产物根路径，不会被 Vite 做哈希处理：

public/ tiles/ 10/ 1/ 2.png 3/ 4.png 11/ ...

如果瓦片量很大，比如超过 1GB，直接放前端静态资源会对部署和更新造成压力。更合适的做法是把瓦片放到独立的静态目录，由 Nginx 统一托管，前端代码只负责拼接 URL。

location /tiles/ { alias /data/map-tiles/; }

这样瓦片更新时只需要替换服务器上的目录，不用重新打包前端应用。

体积压缩方面，地图瓦片普遍适合转为 WebP 格式。实测下来，同样内容的瓦片，WebP 比 PNG 大约能减少一半以上体积。如果项目兼容性允许，可以在瓦片下载后统一转换，能省出不少磁盘空间。

3. Vue 3 地图组件实现：本地瓦片接入与展示

3.1 创建 Vue 3 项目并引入 BMap 脚本

项目初始化直接用 Vite：

npm create vite@latest offline-map -- --template vue-ts

BMap 脚本我倾向于动态加载，而不是直接写死在 index.html。这样地图模块可以在需要时才加载，也方便统一管理加载完成的回调：

// src/utils/loadBMap.ts export function loadBMap(ak: string): Promise<void> { return new Promise((resolve, reject) => { if (window.BMap) { resolve() return } const script = document.createElement('script') script.src = `https://api.map.baidu.com/api?v=3.0&ak=${ak}` script.onload = () => resolve() script.onerror = () => reject(new Error('BMap 脚本加载失败')) document.head.appendChild(script) }) }

注意申请 API Key 时要配置域名白名单。开发环境用 localhost，生产环境必须填部署域名，否则脚本虽然能加载，内部 API 也会因为域名校验不通过而报错。

3.2 地图初始化与自定义瓦片底图

初始化地图时先建一个自定义 MapType，把瓦片请求指向本地路径：

// src/components/OfflineMap.vue <script setup lang="ts"> import { onMounted, onBeforeUnmount } from 'vue' import { loadBMap } from '../utils/loadBMap' import { CITY_CENTER, MIN_ZOOM, MAX_ZOOM } from '../config/map' let map: BMap.Map | null = null onMounted(async () => { await loadBMap('你的AK字符串') initMap() }) function initMap() { const customType = new BMap.MapType('offline', { minZoom: MIN_ZOOM, maxZoom: MAX_ZOOM, getTileUrl(tileCoord: BMap.TileCoord, zoom: number) { return `tiles/${zoom}/${tileCoord.x}/${tileCoord.y}.png` } }) map = new BMap.Map('map-container', { mapType: customType }) const center = new BMap.Point(CITY_CENTER.lng, CITY_CENTER.lat) map.centerAndZoom(center, 12) map.setMinZoom(MIN_ZOOM) map.setMaxZoom(MAX_ZOOM) map.enableScrollWheelZoom() } </script> <template> <div id="map-container" class="map-container"></div> </template> <style scoped> .map-container { width: 100%; height: 100vh; } </style>

这里有个实际经验：自定义 MapType 的 getTileUrl 返回的 x、y 是 BMap 自己的瓦片坐标编号。你的瓦片目录在下载时如果用同一套 BMap 坐标体系生成，路径就能直接对上。如果下载工具使用的是标准 XYZ，那必须在 getTileUrl 里做坐标换算，否则还是错位。

如果你在测试中发现自定义 MapType 之后默认底图依然漏出来，可以采用一个更粗暴的方式：添加一个不透明的自定义 TileLayer 层覆盖在默认底图上方。

const coverLayer = new BMap.TileLayer({ transparent: false, zIndex: 999, getTilesUrl(tileCoord: BMap.TileCoord, zoom: number) { return `tiles/${zoom}/${tileCoord.x}/${tileCoord.y}.png` } }) map.addTileLayer(coverLayer)

两种方案在多数 BMap v3.0 版本里都能用，具体取哪个看实际情况，优先尝试第一种自定义 MapType。

3.3 城市内标注与离线数据准备

离线地图的另一大限制是搜索和地理编码服务不能用。在线地图的 POI 搜索、路线规划接口都需要联网，离线环境下完全不可用。

所以城市内的关键点位要提前固化到前端数据里：

// src/data/pois.ts export const CITY_POIS = [ { name: '中心城区示范点', lng: 0.0, lat: 0.0 }, // 继续添加 ]

在地图初始化后循环添加标注：

CITY_POIS.forEach(poi => { const point = new BMap.Point(poi.lng, poi.lat) const marker = new BMap.Marker(point) marker.setLabel(new BMap.Label(poi.name, { offset: new BMap.Size(16, -24) })) map.addOverlay(marker) })

如果产品经理希望支持搜索，就要做本地数据源替换，把城市的 POI 数据导出成 JSON，前端写模糊匹配，而不是指望离线状态下的在线接口。

4. 限制区域显示：只展示某个城市地图的边界控制方案

4.1 边界控制的两种手段

“限制区域显示”落到代码层面分两种手段。

第一是数据层限制。城市边界外的瓦片根本没有下载，即使视野出界，也没有内容可看。这一步在做瓦片目录时已经完成了，相当于“被动限制”。

第二是交互层限制。通过事件监听，在视野越界时把地图拉回城市范围内。这一步是“主动控制”。

两者叠加，用户就会明显感到这是一块独立、可控的城市地图。

4.2 越界检测与拉回算法

交互层限制的核心代码是监听 moveend 事件，在地图停止移动后检查当前可视范围是否超出城市边界矩形。

function handleMoveEnd() { if (!map) return const bounds = map.getBounds() const ne = bounds.getNorthEast() const sw = bounds.getSouthWest() const city = CITY_BOUNDS const center = map.getCenter() let needFix = false if (ne.lng > city.east) { center.lng -= (ne.lng - city.east) / 2 needFix = true } if (sw.lng < city.west) { center.lng += (city.west - sw.lng) / 2 needFix = true } if (ne.lat > city.north) { center.lat -= (ne.lat - city.north) / 2 needFix = true } if (sw.lat < city.south) { center.lat += (city.south - sw.lat) / 2 needFix = true } if (needFix) { map.panTo(new BMap.Point(center.lng, center.lat)) } }

这里越界多少就修正一半，目的是把视野拉回边界以内，同时保留用户停留在城市内的一部分上下文。直接拉回城市中心会很突兀，把手感做僵硬。

还需要防抖。panTo 之后又会触发一次 moveend，如果不做处理，会出现“拉回瞬间又被检测到越界再拉回”的死循环，视觉上像抽搐。加一个短暂锁：

let fixLock = false setTimeout(() => { fixLock = false }, 300) function handleMoveEnd() { if (fixLock) return // 检测逻辑... if (needFix) { fixLock = true // 拉回... } }

4.3 缩放级别的双重限制

用户滚动鼠标滚轮时，地图可能瞬间缩放出城市范围。光有 moveend 的边界检测还不够，必须限制缩放级别。

初始化时已经调用了 setMinZoom 和 setMaxZoom，但 Pano 级别地图上这两个方法对“滚轮缩放瞬间越界”的约束不够硬。建议在 zoomend 事件里再做一次校验：

map.addEventListener('zoomend', () => { const zoom = map.getZoom() if (zoom > MAX_ZOOM) { map.setZoom(MAX_ZOOM) } if (zoom < MIN_ZOOM) { map.setZoom(MIN_ZOOM) } })

这样即使用户快速滚轮连续缩放，也能被强制限制在设定的级别区间内。

4.4 城市外遮罩与视觉强化

只做逻辑限制还不够。用户拖拽出界的瞬间，虽然马上会被拉回，但由于城市外没有瓦片数据，地图区域会出现灰底白块，视觉上很糟。

我的处理方式是在城市边界矩形外围添加半透明遮罩，原理是用覆盖物把城市范围以外的区域盖住。BMap Polygon 不支持挖洞，所以要做四个矩形覆盖在上下左右四块区域：

function addOutsideMask() { const city = CITY_BOUNDS const big = 1 // 这里的数值代表经纬度跨度，按实际情况写大一点 const rects = [ // 左侧 [ new BMap.Point(city.west - big, city.north + big), new BMap.Point(city.west, city.south - big) ], // 右侧 [ new BMap.Point(city.east, city.north + big), new BMap.Point(city.east + big, city.south - big) ], // 上方 [ new BMap.Point(city.west, city.north + big), new BMap.Point(city.east, city.north) ], // 下方 [ new BMap.Point(city.west, city.south), new BMap.Point(city.east, city.south - big) ], ] rects.forEach(rect => { const polygon = new BMap.Polygon([rect[0], rect[1], new BMap.Point(rect[1].lng, rect[0].lat), new BMap.Point(rect[0].lng, rect[1].lat)], { strokeOpacity: 0, fillColor: '#0a0a0a', fillOpacity: 0.45 }) map.addOverlay(polygon) }) }

这样一个 0.45 的半透明黑色遮罩会把城市周边区域压暗，用户一眼就能看出“城区之外不可进入”，视觉上非常明确。

如果以后需要更精确的城市行政边界，可以把边界导出为 GeoJSON，在地图上叠加一条边界 Polygon 或一条边界线，配合遮罩层一起使用。

4.5 缩放控件和缩略图的处理

地图自带的 OverviewMapControl 缩略图控件在离线场景下要特别注意。它允许用户直接在缩略图中拖拽红色标记框，而且不经过主地图的 moveend 事件，容易把视野挪到城市外。

我在项目里直接移除了缩略图控件：

map.removeControl(overviewControl)

导航控件可以保留，但缩放按钮的点击事件也会触发 zoomend，所以级别限制逻辑要覆盖它。

5. 离线地图开发常见问题与优化实录

5.1 组件生命周期与内存释放

BMap 实例是原生对象，不会跟随 Vue 组件卸载自动销毁。如果不处理，切换到其他路由后再回来，旧地图实例依然存在，可能产生重复的事件监听和内存泄漏。

组件卸载前一定要销毁：

onBeforeUnmount(() => { if (map) { map.destroy() map = null } })

如果有多个地图页面，建议把 BMap 初始化封装成独立的模块，每个组件维护自己的 map 实例，不要挂到全局共享变量上。

5.2 构建路径与部署注意事项

Vite 默认 base 是/，如果你的应用部署在域名根路径，那瓦片路径写tiles/10/1/2.png没问题。

但如果部署在子路径，比如https://example.com/app/，前端路由和静态资源路径都会变化，瓦片路径也得跟着变。我建议直接使用 Vite 注入的 BASE_URL：

const tileRoot = `${import.meta.env.BASE_URL}tiles` getTileUrl(tileCoord, zoom) { return `${tileRoot}/${zoom}/${tileCoord.x}/${tileCoord.y}.png` }

这样构建和部署时不会因为路径写死而出问题。

5.3 离线地图典型问题速查表

把这次开发中踩过的典型问题整理成一张表，方便后续排查：

5.4 瓦片体量与性能优化

城市瓦片全量下载后，体积到了几百 MB 时，启动加载和缓存占用都要注意。

建议开启浏览器缓存策略，瓦片路径带上版本号或者不经常变化，让浏览器长期缓存已访问过的瓦片。如果瓦片放在 Nginx 静态目录，可以加长 Cache-Control 时间：

location /tiles/ { expires 30d; add_header Cache-Control "public, max-age=2592000, immutable"; }

另外，地图缩放级别跨度不要贪大。项目里最开始为了展示效果把 maxZoom 设成了 18，结果 16 到 18 级的瓦片数量翻了十几倍，更新一次瓦片要跑很久。后来压缩到 15 级，视觉效果差别不大，开发和维护成本低了一截。

前端还可以关闭连续缩放减少卡顿：

map.enableContinuousZoom(false)

在低性能设备上，这一行能明显提升拖拽流畅度。

5.5 多城市扩展的配置化设计

如果这个项目后续要从“只展示某个城市”扩展到多个城市，建议从一开始就把城市配置独立出来。

我那边的做法是定义城市配置列表：

export interface CityConfig { cityName: string center: { lng: number; lat: number } bounds: { west: number; south: number; east: number; north: number } minZoom: number maxZoom: number tileRoot: string } export const CITIES: CityConfig[] = [ // 城市A配置 // 城市B配置 ]

切换城市时，地图实例销毁，重新根据配置初始化。瓦片目录则按城市独立存放：

tiles/ cityA/ 10/... 11/... cityB/ 10/...

这样做的收益在后期非常明显，后端加一个城市选项，前端直接传配置，新增城市不需要再动业务代码。

最后再分享一点实际体会

整个流程走下来，我最大的感受是：Vue 3.0 开发离线百度地图的核心难点不在 Vue，而在瓦片和坐标体系这两件事上。

瓦片只要坐标系对上了，接入工程就成功了一半。边界限制也不是想象中那么复杂，moveend 做越界检测加一个 300ms 锁，配合 minZoom/maxZoom 限制，实测手感已经很接近在线地图。千万不要把限制逻辑做成“每次移动就强制拉回城市中心”，那种体验谁用谁知道，头晕。

如果你这边也正好要做类似的功能，建议先花一天时间把城市瓦片和坐标体系理清楚，再动手写组件。项目真正开发的时间其实不长，大部分时间都消耗在瓦片错位和白屏排查上。

后续如果能往这个城市地图里加上本地化的 POI 检索，再结合后台配置动态下发城市数据，这套离线地图方案就非常通用了。