简介面向需要在内网或离线环境中接入天地图服务的开发者这份资源提供了经过本地化改造的JS与CSS文件用于解决无互联网连接时地图加载失败、控件异常等问题。压缩包共5个文件包含4个JS文件与1个CSS文件整体体积仅100KB。JS部分封装了天地图API的调用逻辑覆盖瓦片请求地址替换、坐标转换、图层加载等核心调整CSS文件则对地图控件外观进行定制使图层控制、比例尺、指北针等元素在离线模式下保持正常显示与操作。已有2350人浏览学习。通过这套文件开发者可快速理解内网场景下天地图离线化的实现路径将公网请求重定向至本地地图服务、调整数据存储目录配置、适配离线瓦片资源等。资源体积小、结构简单适合具备JS与CSS基础、正在搭建内网GIS应用或学习地图API二次开发的工程技术人员参考。 直接在博文中输出正文不要任何前置说明。我们开始一点一点拆分。先说结论我要写一篇面向WebGIS开发者、前端工程师、内网部署实施人员的实战型博文核心是“天地图离线地图的JS和CSS怎么落地”。整篇文章会围绕JS和CSS这两个前端资源在离线场景下的获取、引入、改造、优化展开中间穿插瓦片对接、坐标系匹配、缓存策略、常见报错等实操内容。文章结构我设定为六个章节。第一章先讲清楚JS和CSS在离线地图中各自承担什么角色破除“离线地图下载瓦片”这个常见误区。第二章做资源本地化讲清楚从官方CDN迁移到内网服务器的完整操作。第三章进入JS API的核心接入逻辑把地图初始化和离线瓦片自定义图层讲透。第四章聚焦CSS的实际使用场景从控件样式到覆盖物弹窗做一个系统梳理。第五章是内网部署踩坑实录把坐标系、跨域、缓存这些高频问题逐一排查。第六章收尾分享按需裁剪和性能优化的经验。我先写开头200字起前100字必须融进“天地图”“离线地图”“JS”“CSS”这四个核心关键词。切入角度就选“很多人以为离线地图就是下载瓦片”这个常见误解直接打破它。很多时候提到“天地图离线地图”大家的第一反应是去下载瓦片切片一堆人围着硬盘拷贝几个TB的影像图却忽略了真正让地图“跑起来”的前端资源——也就是标题里说的那套JS和CSS。天地图的Web服务在线用很简单一个script标签引进去就完事一旦进入内网离线环境麻烦就全来了控件渲染不出来、图层叠加报错、弹窗样式错乱、比例尺消失这些问题十有八九都出在JS和CSS的本地化改造上。本文把我的完整实测过程和踩坑记录整理出来给正在做内网GIS项目、天地图二次开发的朋友做一个可直接参考的落地方案。1. 天地图JS和CSS到底在离线方案里扮演什么角色1.1 JS是渲染大脑CSS是外观皮肤先纠正一个很普遍的理解偏差很多人以为天地图离线部署的核心是瓦片数据把大量精力花在切片入库上却把JS和CSS当成“顺带拷一下”的附件。实际上离线地图能正常交互靠的是一整套前端运行时JS负责地图初始化、图层请求、坐标系转换、事件绑定CSS负责人机交互界面的渲染。瓦片是“肉”JS和CSS是“血管和神经”缺了后两者地图页面只能看到网格背景或一张不会动的底图。天地图官网提供的JavaScript API通常称为天地图WebAPI本身由一组JS文件构成内部封装了地图渲染引擎、矢量图层加载器、覆盖物管理器和事件系统。CSS则是独立的样式文件控制了缩放控件、比例尺控件、图层切换面板、版权信息栏的视觉表现。在线环境下这些资源从官方CDN加载浏览器跨域请求没问题离线环境下它们必须成为你内网静态资源的一部分。1.2 离线部署的真正难点不在代码而在资源链路我在给一个政企客户做内网地图平台时项目经理最开始只提了一个需求把天地图的瓦片同步到内网服务器上。瓦片准备妥当之后前端页面却怎么都调不通。打开浏览器控制台满屏的404和跨域报错官方CDN的外网地址在内网根本访问不到页面上的地图容器始终是空白。这就是离线地图项目的真实状态难点不在于地图业务代码本身而在于整条资源链路。官方API的JS文件里可能还引用了其他子资源字体、样式、图片图标CSS里也可能用相对路径引用了背景图。如果只是把主JS和主CSS下载下来扔到内网你会发现控件图标消失、缩放按钮错位、弹窗气泡的箭头丢失这些都是资源链路没打通的表现。所以做离线改造第一步不是写地图业务逻辑而是把整个资源树完整地搬到内网并重写其中所有资源引用路径。1.3 离线地图适配的主要场景与开发思路根据我的经验需要做天地图离线JS和CSS本地化的场景大概有三类。第一类是政企内网项目数据敏感不允许外网访问这是最常见的场景。第二类是工地、野外、灾备等弱网场景网络不稳定把前端资源全部本地化之后即使断网只要瓦片在本地缓存中地图依然可以浏览。第三类是基于天地图底图做二次开发的产品需要将地图能力打包进自己的安装包。三种场景虽然需求不同但技术路径都是一样的获取官方JS和CSS资源本地化改造封装成离线可用的一套静态资源库再对接本地瓦片服务。本篇的整个方案也是围绕这条路径展开的。这里还要提醒一点不要试图去混淆在线域名和本地路径最稳妥的做法是把官方资源下载到内网后统一用相对路径引用这样部署到任何一台内网服务器上都不需要改代码。2. 离线资源本地化从官方CDN迁移到内网服务器2.1 需要下载的资源清单与引入顺序天地图JS API的在线引用方式是在HTML的head标签里加一个script标签和一组link标签指向官方资源域名。离线化改造的第一步就是把这几类资源一一对应地下载到本地JavaScript运行时文件核心的API文件文件名类似T.js或带版本号的API包这是地图引擎的主入口。样式样式表文件用于地图控件和弹窗的CSS往往有好几个文件包括基础控件样式和覆盖物样式。字体与图标文件控件里可能有文字图标使用字体图标的方案对应的woff/ttf文件必须一起下载。图片资源缩放控件、比例尺控件、全屏按钮等用到的背景图片或SVG图标。资源下载完成后建议按照“样式在前、脚本在后”的顺序引入。CSS放在head中避免页面渲染出无样式的地图容器JS放在body末尾或使用defer属性保证DOM结构加载完成后再执行地图初始化。顺序不对经常会出现初始化时报找不到容器节点或者控件样式闪烁的问题。2.2 替换域名与相对路径改写的完整操作资源文件落地以后最重要的一步是把所有引用官方CDN绝对路径的地方改成相对路径。打开下载下来的JS和CSS文件全局搜索官方域名把它替换为空或替换为./。这一步通常在文本编辑器里用全局替换就能完成但有个坑JS文件里有些字符串不是直接的路径引用而是拼接出来的URL比如根据瓦片级别动态生成请求地址这种字符串你替换掉之后反而会把在线瓦片地址也改错了。正确的操作是先把下载下来的JS文件放在项目的map/js/目录CSS放在map/css/目录然后用编辑器对CSS文件做相对路径修正对JS文件则重点检查“引用同目录其他JS”和“创建DOM元素时加载的外部脚本”这两类代码。对于动态生成的地址保留官方域名在后续封装本地服务时用反向代理或域名映射去解决不要在JS源码里硬改。2.3 批量下载工具与资源梳理经验实际执行时我建议用浏览器开发者工具的Network面板打开官方示例页面一个个核对加载了哪些资源文件再配合wget或curl批量下载。对于大文件的递归依赖可以用本地代理工具如Fiddler抓包获取资源列表再逐一下载。下载完之后不要急着部署先做一次资源完整性检查把所有文件放到一个临时目录在本地起一个HTTP服务用一个最简单的HTML页面去引这些资源如果控制台没有报404或资源加载失败再做地图初始化的测试。这一步能帮你快速发现漏下载的字体、图标或子资源省得在内网环境里反复调试。注意下载后的资源目录名尽量保持英文且不含空格内网Nginx或IIS对中文路径的处理很容易引发意料之外的404。这是我踩过的坑先在本地暴露出来。3. JS API接入的核心逻辑与离线瓦片对接3.1 初始化地图与授权参数的处理天地图JS API的对外用法并不复杂加载JS后调用几个全局构造函数即可。T.Map负责地图实例T.TileLayer负责瓦片图层。在线版本通常在初始化时传递一个tk参数这是天地图平台申请的开发者密钥用于统计配额和访问控制。离线环境下各地图业务系统和瓦片服务都已迁入内网tk校验的用途已经弱化了。但很多开发者在接入时还是漏掉了这一步没有在初始化参数中传递tk导致在线模式调不通。正确的做法是区分场景——完全离线时可以不传或使用本地网关校验如果还保留了部分在线的数据源则必须正确配置tk。我的建议是封装一个统一的地图初始化函数把tk、瓦片服务地址、地图容器ID、默认中心点全部收敛为配置项后续部署到不同环境只需要改一份配置文件。3.2 离线瓦片URL规则与自定义图层离线地图能否显示关键在于瓦片URL规则是否和本地的瓦片目录结构一致。天地图的在线瓦片地址遵循一个经典套路http://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk密钥。离线部署时通常会用GeoServer或Tileserver这种瓦片服务器来切片和发布。前端要做的事情就变成了用JS发送瓦片请求并且拼出符合本地服务器规则的URL。在天地图API中可以使用一个最基础的动态添加图层的方式。如果你是自己拼接瓦片那么需要精确匹配瓦片坐标的缩放级别z、行号y、列号x。这对JS开发者来说是最考验人的地方因为天地图官方V4版本里行列号规则和明文PNG瓦片的规则有差异。我这里给一个通用的对接方法不直接依赖官方API的瓦片请求内部逻辑而是新建一个自定义图层类重写获取瓦片URL的方法把天地图在线地址替换成内网瓦片服务的地址。核心就是把TILEMATRIX、TILEROW、TILECOL这三个参数动态拼进去然后再拼上当前地图的级别和行列号。3.3 坐标系与投影的参数匹配这一步是用JS和CSS做离线地图时最容易翻车的环节。天地图底图常用两种投影CGCS20004326经纬度和Web墨卡托900913。大多数GIS从业者熟悉的天地图矢量底图是经纬度直投的也就是说它在高纬度地区的变形看起来比较明显而互联网地图行业常用的Web墨卡托投影则更适合全球范围内的常规展示。内网部署时你本地的瓦片切片服务可能用的是Web墨卡托但页面里仍按4326的参数去初始化结果就是地图能加载但瓦片位置对不上出现错位、花屏或白底。我的实践经验是初始化地图时通过projection参数显式声明坐标系同时在发送瓦片请求时确定行列号计算用的基准。如果瓦片服务按900913切片那就用墨卡托投影初始化地图并按对应规则计算行列号如果按4326切片就用地理坐标系初始化地图。另外要注意不同缩放级别下行列号偏移的问题通常是因为层级LOD定义不一致切片服务的origin、resolutions参数要和前端的级别定义对齐。4. CSS在离线地图中的实际使用场景4.1 调整地图控件样式与离线图标资源CSS在离线地图里的第一个大用场是调整缩放控件、比例尺、版权信息、图层切换按钮这些控件的视觉样式。官方CSS在在线环境下自动生效到了离线环境如果你把官方的控件图标文件一并本地化了那基本不用大改只是把背景图的引用路径修正成相对路径即可。但实际情况中几乎每个项目都要对控件样式做定制。比如政企项目里缩放按钮要放在右上角而不是默认的左上角比例尺要么去掉要么换成跟随主题色的样式。这时单纯靠改CSS还不行因为地图控件的DOM结构是在JS初始化时动态生成的。正确的做法是等地图加载完成之后通过JS拿到控件DOM节点再挂上自定义的class配合CSS覆盖样式。我建议在CSS里用更高优先级的类选择器去覆盖官方样式而不是直接修改官方CSS文件否则日后升级API版本时改造会非常痛苦。再有一点很多人容易忽略控件里的文字图标如果依赖字体文件离线后字体文件缺失会导致控件上出现方框或乱码。这类问题排查方式是打开图层控制按钮看渲染出来的文本节点再去CSS文件里找对应的font-family定义然后把字体文件一同本地化。4.2 覆盖物、弹窗与信息窗体的样式定制天地图的覆盖物分为点标记、线、面状要素以及用于交互的信息窗体。官方信息窗体自带一套默认样式背景是白色卡片带一个尖角指向地图上的坐标点。离线部署后如果CSS文件没有随API一起引入信息窗体就会退化成浏览器默认的提示框效果甚至完全无法显示尖角样式。我在项目中遇到的一个典型需求是信息窗体要叠加一个轮播图表并且要有深色半透明背景。这时就需要重写官方弹窗的CSS类。这里同样建议不要在官方CSS上直接改而是新建一个额外的样式表利用CSS的后代选择器和ID选择器将自定义样式挂到地图容器内部。例如给你的地图容器设置一个唯一的id然后所有自定义样式都写成#mapContainer .tdt-info-window { ... }这种形式这样就不会污染其他页面组件。4.3 深色主题和业务地图样式的实现思路还有一类需求是深色底图主题。很多可视化大屏项目喜欢把天地图底图调成深灰色或蓝黑色地图控件的配色也全部换成荧光绿或科技蓝。天地图本身的底图瓦片是浅色的离线改造时如果不想改动瓦片数据前端可以有两条路一条是在瓦片加载完成之后用CSS滤镜调色比如filter: grayscale brightness invert的组合拳另一条是使用canvas重新绘制瓦片再渲染到图层上。CSS滤镜的方案实现成本低直接给地图canvas容器加样式即可但要注意性能尤其在大范围拖拽时滤镜计算会产生明显卡顿。canvas重绘方案性能更稳但对前端功底要求稍高需要在瓦片请求返回时对图片做一次处理。我的经验是展示型的大屏项目用CSS滤镜够用交互频繁的操作型系统建议用canvas重绘根据场景取舍。5. 内网部署踩坑实录与性能优化5.1 常见报错与排查链路离线地图部署中最高频的报错我整理成一张排查表供参考现象大概率原因排查与修复方向地图容器空白JS文件未正确加载打开控制台看script是否404重点检查资源路径控件不显示CSS或字体文件缺失查看Network面板确认字体和图标资源是否加载瓦片错位或拉伸坐标系不匹配核对切片的投影和初始化参数调整投影设定弹窗样式错乱官方的弹窗CSS未引入检查弹窗相关class是否被覆盖补齐样式引用比例尺控件显示nullJS计算比例尺所需的参数被跳过检查初始化时坐标系或地图分辨率设置是否完整页面整体样式冲突引用了全局CSS选择器用容器ID限定范围避免与其他组件样式互相污染遇到问题不要闷头改代码我建议先打开控制台看Network面板里的红色404和警告信息80%的离线地图问题都出在资源链路而不是业务逻辑上。把404问题先清零再看渲染和交互问题排查顺序基本不会走偏。5.2 浏览器缓存与加载速度优化离线地图虽然少了公网链路的延迟但内网并发请求瓦片时浏览器对同一域名的连接数有限制瓦片数量多时会出现排队。优化手段有两个方向。一是合理设置HTTP缓存头瓦片数据在离线环境基本不变可以设置较长的Cache-Control: max-age和Expires时间让浏览器把瓦片缓存在本地二次浏览时直接从缓存读取。二是做域名拆分把瓦片请求分散到多个子域名比如tile1.map.local、tile2.map.local突破单个域名的并发连接限制。对JS和CSS本身的优化主要是压缩和合并。下载官方源码后用压缩工具去掉注释和多余空白再把多个CSS合并成一个文件多个JS按依赖顺序合并成一个入口文件。经过压缩合并后页面加载地图的时间通常能减少三分之一以上我实测明显。5.3 资源按需裁剪与本地服务托管不是所有的官方JS和CSS功能你都需要这就要说到资源裁剪。天地图API内置了多种图层类型、测绘工具、量算工具如果你的业务只需要底图和点标记就可以删掉不必要的模块。资源裁剪会让测试回归量变大更稳妥的方案是保留完整文件但仅加载需要的部分配合本地HTTP服务的gzip压缩也能获得相近的性能提升。内网部署的托管方式我推荐用Nginx直接托管静态目录然后对瓦片服务做反向代理。这样一个入口地址既能承载JS和CSS也能转发瓦片请求页面代码里就不需要配多个IP和端口后续迁移维护都很方便。Nginx里再开启gzip、设置缓存头性能和稳定性基本就都到位了。6. 从一套离线地图到可复用的前端资源包随着项目越做越多我逐渐意识到天地图离线地图的JS和CSS不应该只属于单个项目而应该沉淀成一套可复用的前端资源包。把下载的官方JS和CSS、改造后的控件样式、自定义的初始化封装函数、瓦片URL拼接逻辑全部归档配合版本号管理后续新项目直接引入这套资源包接入的周期从两三天压缩到半天。具体归档时我建议资源包保持“三个分离”的原则官方原始文件与自定义扩展文件分离、业务配置与地图能力代码分离、瓦片服务地址与前端资源地址分离。这样既能随时应对官方API升级也能在多个项目间快速复用还能避免换环境时到处查找硬编码地址的麻烦。最后再分享一个实操经验资源包内一定要带一个“自检页面”页面上只展示一张基础地图所有静态资源和瓦片服务都走一遍请求。部署到任何一个新环境先跑自检页面验证再跑业务页面任何资源链路的遗漏都会在自检页面上第一时间暴露出来。大部分现场部署事故我复盘下来都是因为少了这一步检查。本文还有配套的精品资源点击获取
简介面向需要在内网或离线环境中接入天地图服务的开发者这份资源提供了经过本地化改造的JS与CSS文件用于解决无互联网连接时地图加载失败、控件异常等问题。压缩包共5个文件包含4个JS文件与1个CSS文件整体体积仅100KB。JS部分封装了天地图API的调用逻辑覆盖瓦片请求地址替换、坐标转换、图层加载等核心调整CSS文件则对地图控件外观进行定制使图层控制、比例尺、指北针等元素在离线模式下保持正常显示与操作。已有2350人浏览学习。通过这套文件开发者可快速理解内网场景下天地图离线化的实现路径将公网请求重定向至本地地图服务、调整数据存储目录配置、适配离线瓦片资源等。资源体积小、结构简单适合具备JS与CSS基础、正在搭建内网GIS应用或学习地图API二次开发的工程技术人员参考。 直接在博文中输出正文不要任何前置说明。我们开始一点一点拆分。先说结论我要写一篇面向WebGIS开发者、前端工程师、内网部署实施人员的实战型博文核心是“天地图离线地图的JS和CSS怎么落地”。整篇文章会围绕JS和CSS这两个前端资源在离线场景下的获取、引入、改造、优化展开中间穿插瓦片对接、坐标系匹配、缓存策略、常见报错等实操内容。文章结构我设定为六个章节。第一章先讲清楚JS和CSS在离线地图中各自承担什么角色破除“离线地图下载瓦片”这个常见误区。第二章做资源本地化讲清楚从官方CDN迁移到内网服务器的完整操作。第三章进入JS API的核心接入逻辑把地图初始化和离线瓦片自定义图层讲透。第四章聚焦CSS的实际使用场景从控件样式到覆盖物弹窗做一个系统梳理。第五章是内网部署踩坑实录把坐标系、跨域、缓存这些高频问题逐一排查。第六章收尾分享按需裁剪和性能优化的经验。我先写开头200字起前100字必须融进“天地图”“离线地图”“JS”“CSS”这四个核心关键词。切入角度就选“很多人以为离线地图就是下载瓦片”这个常见误解直接打破它。很多时候提到“天地图离线地图”大家的第一反应是去下载瓦片切片一堆人围着硬盘拷贝几个TB的影像图却忽略了真正让地图“跑起来”的前端资源——也就是标题里说的那套JS和CSS。天地图的Web服务在线用很简单一个script标签引进去就完事一旦进入内网离线环境麻烦就全来了控件渲染不出来、图层叠加报错、弹窗样式错乱、比例尺消失这些问题十有八九都出在JS和CSS的本地化改造上。本文把我的完整实测过程和踩坑记录整理出来给正在做内网GIS项目、天地图二次开发的朋友做一个可直接参考的落地方案。1. 天地图JS和CSS到底在离线方案里扮演什么角色1.1 JS是渲染大脑CSS是外观皮肤先纠正一个很普遍的理解偏差很多人以为天地图离线部署的核心是瓦片数据把大量精力花在切片入库上却把JS和CSS当成“顺带拷一下”的附件。实际上离线地图能正常交互靠的是一整套前端运行时JS负责地图初始化、图层请求、坐标系转换、事件绑定CSS负责人机交互界面的渲染。瓦片是“肉”JS和CSS是“血管和神经”缺了后两者地图页面只能看到网格背景或一张不会动的底图。天地图官网提供的JavaScript API通常称为天地图WebAPI本身由一组JS文件构成内部封装了地图渲染引擎、矢量图层加载器、覆盖物管理器和事件系统。CSS则是独立的样式文件控制了缩放控件、比例尺控件、图层切换面板、版权信息栏的视觉表现。在线环境下这些资源从官方CDN加载浏览器跨域请求没问题离线环境下它们必须成为你内网静态资源的一部分。1.2 离线部署的真正难点不在代码而在资源链路我在给一个政企客户做内网地图平台时项目经理最开始只提了一个需求把天地图的瓦片同步到内网服务器上。瓦片准备妥当之后前端页面却怎么都调不通。打开浏览器控制台满屏的404和跨域报错官方CDN的外网地址在内网根本访问不到页面上的地图容器始终是空白。这就是离线地图项目的真实状态难点不在于地图业务代码本身而在于整条资源链路。官方API的JS文件里可能还引用了其他子资源字体、样式、图片图标CSS里也可能用相对路径引用了背景图。如果只是把主JS和主CSS下载下来扔到内网你会发现控件图标消失、缩放按钮错位、弹窗气泡的箭头丢失这些都是资源链路没打通的表现。所以做离线改造第一步不是写地图业务逻辑而是把整个资源树完整地搬到内网并重写其中所有资源引用路径。1.3 离线地图适配的主要场景与开发思路根据我的经验需要做天地图离线JS和CSS本地化的场景大概有三类。第一类是政企内网项目数据敏感不允许外网访问这是最常见的场景。第二类是工地、野外、灾备等弱网场景网络不稳定把前端资源全部本地化之后即使断网只要瓦片在本地缓存中地图依然可以浏览。第三类是基于天地图底图做二次开发的产品需要将地图能力打包进自己的安装包。三种场景虽然需求不同但技术路径都是一样的获取官方JS和CSS资源本地化改造封装成离线可用的一套静态资源库再对接本地瓦片服务。本篇的整个方案也是围绕这条路径展开的。这里还要提醒一点不要试图去混淆在线域名和本地路径最稳妥的做法是把官方资源下载到内网后统一用相对路径引用这样部署到任何一台内网服务器上都不需要改代码。2. 离线资源本地化从官方CDN迁移到内网服务器2.1 需要下载的资源清单与引入顺序天地图JS API的在线引用方式是在HTML的head标签里加一个script标签和一组link标签指向官方资源域名。离线化改造的第一步就是把这几类资源一一对应地下载到本地JavaScript运行时文件核心的API文件文件名类似T.js或带版本号的API包这是地图引擎的主入口。样式样式表文件用于地图控件和弹窗的CSS往往有好几个文件包括基础控件样式和覆盖物样式。字体与图标文件控件里可能有文字图标使用字体图标的方案对应的woff/ttf文件必须一起下载。图片资源缩放控件、比例尺控件、全屏按钮等用到的背景图片或SVG图标。资源下载完成后建议按照“样式在前、脚本在后”的顺序引入。CSS放在head中避免页面渲染出无样式的地图容器JS放在body末尾或使用defer属性保证DOM结构加载完成后再执行地图初始化。顺序不对经常会出现初始化时报找不到容器节点或者控件样式闪烁的问题。2.2 替换域名与相对路径改写的完整操作资源文件落地以后最重要的一步是把所有引用官方CDN绝对路径的地方改成相对路径。打开下载下来的JS和CSS文件全局搜索官方域名把它替换为空或替换为./。这一步通常在文本编辑器里用全局替换就能完成但有个坑JS文件里有些字符串不是直接的路径引用而是拼接出来的URL比如根据瓦片级别动态生成请求地址这种字符串你替换掉之后反而会把在线瓦片地址也改错了。正确的操作是先把下载下来的JS文件放在项目的map/js/目录CSS放在map/css/目录然后用编辑器对CSS文件做相对路径修正对JS文件则重点检查“引用同目录其他JS”和“创建DOM元素时加载的外部脚本”这两类代码。对于动态生成的地址保留官方域名在后续封装本地服务时用反向代理或域名映射去解决不要在JS源码里硬改。2.3 批量下载工具与资源梳理经验实际执行时我建议用浏览器开发者工具的Network面板打开官方示例页面一个个核对加载了哪些资源文件再配合wget或curl批量下载。对于大文件的递归依赖可以用本地代理工具如Fiddler抓包获取资源列表再逐一下载。下载完之后不要急着部署先做一次资源完整性检查把所有文件放到一个临时目录在本地起一个HTTP服务用一个最简单的HTML页面去引这些资源如果控制台没有报404或资源加载失败再做地图初始化的测试。这一步能帮你快速发现漏下载的字体、图标或子资源省得在内网环境里反复调试。注意下载后的资源目录名尽量保持英文且不含空格内网Nginx或IIS对中文路径的处理很容易引发意料之外的404。这是我踩过的坑先在本地暴露出来。3. JS API接入的核心逻辑与离线瓦片对接3.1 初始化地图与授权参数的处理天地图JS API的对外用法并不复杂加载JS后调用几个全局构造函数即可。T.Map负责地图实例T.TileLayer负责瓦片图层。在线版本通常在初始化时传递一个tk参数这是天地图平台申请的开发者密钥用于统计配额和访问控制。离线环境下各地图业务系统和瓦片服务都已迁入内网tk校验的用途已经弱化了。但很多开发者在接入时还是漏掉了这一步没有在初始化参数中传递tk导致在线模式调不通。正确的做法是区分场景——完全离线时可以不传或使用本地网关校验如果还保留了部分在线的数据源则必须正确配置tk。我的建议是封装一个统一的地图初始化函数把tk、瓦片服务地址、地图容器ID、默认中心点全部收敛为配置项后续部署到不同环境只需要改一份配置文件。3.2 离线瓦片URL规则与自定义图层离线地图能否显示关键在于瓦片URL规则是否和本地的瓦片目录结构一致。天地图的在线瓦片地址遵循一个经典套路http://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk密钥。离线部署时通常会用GeoServer或Tileserver这种瓦片服务器来切片和发布。前端要做的事情就变成了用JS发送瓦片请求并且拼出符合本地服务器规则的URL。在天地图API中可以使用一个最基础的动态添加图层的方式。如果你是自己拼接瓦片那么需要精确匹配瓦片坐标的缩放级别z、行号y、列号x。这对JS开发者来说是最考验人的地方因为天地图官方V4版本里行列号规则和明文PNG瓦片的规则有差异。我这里给一个通用的对接方法不直接依赖官方API的瓦片请求内部逻辑而是新建一个自定义图层类重写获取瓦片URL的方法把天地图在线地址替换成内网瓦片服务的地址。核心就是把TILEMATRIX、TILEROW、TILECOL这三个参数动态拼进去然后再拼上当前地图的级别和行列号。3.3 坐标系与投影的参数匹配这一步是用JS和CSS做离线地图时最容易翻车的环节。天地图底图常用两种投影CGCS20004326经纬度和Web墨卡托900913。大多数GIS从业者熟悉的天地图矢量底图是经纬度直投的也就是说它在高纬度地区的变形看起来比较明显而互联网地图行业常用的Web墨卡托投影则更适合全球范围内的常规展示。内网部署时你本地的瓦片切片服务可能用的是Web墨卡托但页面里仍按4326的参数去初始化结果就是地图能加载但瓦片位置对不上出现错位、花屏或白底。我的实践经验是初始化地图时通过projection参数显式声明坐标系同时在发送瓦片请求时确定行列号计算用的基准。如果瓦片服务按900913切片那就用墨卡托投影初始化地图并按对应规则计算行列号如果按4326切片就用地理坐标系初始化地图。另外要注意不同缩放级别下行列号偏移的问题通常是因为层级LOD定义不一致切片服务的origin、resolutions参数要和前端的级别定义对齐。4. CSS在离线地图中的实际使用场景4.1 调整地图控件样式与离线图标资源CSS在离线地图里的第一个大用场是调整缩放控件、比例尺、版权信息、图层切换按钮这些控件的视觉样式。官方CSS在在线环境下自动生效到了离线环境如果你把官方的控件图标文件一并本地化了那基本不用大改只是把背景图的引用路径修正成相对路径即可。但实际情况中几乎每个项目都要对控件样式做定制。比如政企项目里缩放按钮要放在右上角而不是默认的左上角比例尺要么去掉要么换成跟随主题色的样式。这时单纯靠改CSS还不行因为地图控件的DOM结构是在JS初始化时动态生成的。正确的做法是等地图加载完成之后通过JS拿到控件DOM节点再挂上自定义的class配合CSS覆盖样式。我建议在CSS里用更高优先级的类选择器去覆盖官方样式而不是直接修改官方CSS文件否则日后升级API版本时改造会非常痛苦。再有一点很多人容易忽略控件里的文字图标如果依赖字体文件离线后字体文件缺失会导致控件上出现方框或乱码。这类问题排查方式是打开图层控制按钮看渲染出来的文本节点再去CSS文件里找对应的font-family定义然后把字体文件一同本地化。4.2 覆盖物、弹窗与信息窗体的样式定制天地图的覆盖物分为点标记、线、面状要素以及用于交互的信息窗体。官方信息窗体自带一套默认样式背景是白色卡片带一个尖角指向地图上的坐标点。离线部署后如果CSS文件没有随API一起引入信息窗体就会退化成浏览器默认的提示框效果甚至完全无法显示尖角样式。我在项目中遇到的一个典型需求是信息窗体要叠加一个轮播图表并且要有深色半透明背景。这时就需要重写官方弹窗的CSS类。这里同样建议不要在官方CSS上直接改而是新建一个额外的样式表利用CSS的后代选择器和ID选择器将自定义样式挂到地图容器内部。例如给你的地图容器设置一个唯一的id然后所有自定义样式都写成#mapContainer .tdt-info-window { ... }这种形式这样就不会污染其他页面组件。4.3 深色主题和业务地图样式的实现思路还有一类需求是深色底图主题。很多可视化大屏项目喜欢把天地图底图调成深灰色或蓝黑色地图控件的配色也全部换成荧光绿或科技蓝。天地图本身的底图瓦片是浅色的离线改造时如果不想改动瓦片数据前端可以有两条路一条是在瓦片加载完成之后用CSS滤镜调色比如filter: grayscale brightness invert的组合拳另一条是使用canvas重新绘制瓦片再渲染到图层上。CSS滤镜的方案实现成本低直接给地图canvas容器加样式即可但要注意性能尤其在大范围拖拽时滤镜计算会产生明显卡顿。canvas重绘方案性能更稳但对前端功底要求稍高需要在瓦片请求返回时对图片做一次处理。我的经验是展示型的大屏项目用CSS滤镜够用交互频繁的操作型系统建议用canvas重绘根据场景取舍。5. 内网部署踩坑实录与性能优化5.1 常见报错与排查链路离线地图部署中最高频的报错我整理成一张排查表供参考现象大概率原因排查与修复方向地图容器空白JS文件未正确加载打开控制台看script是否404重点检查资源路径控件不显示CSS或字体文件缺失查看Network面板确认字体和图标资源是否加载瓦片错位或拉伸坐标系不匹配核对切片的投影和初始化参数调整投影设定弹窗样式错乱官方的弹窗CSS未引入检查弹窗相关class是否被覆盖补齐样式引用比例尺控件显示nullJS计算比例尺所需的参数被跳过检查初始化时坐标系或地图分辨率设置是否完整页面整体样式冲突引用了全局CSS选择器用容器ID限定范围避免与其他组件样式互相污染遇到问题不要闷头改代码我建议先打开控制台看Network面板里的红色404和警告信息80%的离线地图问题都出在资源链路而不是业务逻辑上。把404问题先清零再看渲染和交互问题排查顺序基本不会走偏。5.2 浏览器缓存与加载速度优化离线地图虽然少了公网链路的延迟但内网并发请求瓦片时浏览器对同一域名的连接数有限制瓦片数量多时会出现排队。优化手段有两个方向。一是合理设置HTTP缓存头瓦片数据在离线环境基本不变可以设置较长的Cache-Control: max-age和Expires时间让浏览器把瓦片缓存在本地二次浏览时直接从缓存读取。二是做域名拆分把瓦片请求分散到多个子域名比如tile1.map.local、tile2.map.local突破单个域名的并发连接限制。对JS和CSS本身的优化主要是压缩和合并。下载官方源码后用压缩工具去掉注释和多余空白再把多个CSS合并成一个文件多个JS按依赖顺序合并成一个入口文件。经过压缩合并后页面加载地图的时间通常能减少三分之一以上我实测明显。5.3 资源按需裁剪与本地服务托管不是所有的官方JS和CSS功能你都需要这就要说到资源裁剪。天地图API内置了多种图层类型、测绘工具、量算工具如果你的业务只需要底图和点标记就可以删掉不必要的模块。资源裁剪会让测试回归量变大更稳妥的方案是保留完整文件但仅加载需要的部分配合本地HTTP服务的gzip压缩也能获得相近的性能提升。内网部署的托管方式我推荐用Nginx直接托管静态目录然后对瓦片服务做反向代理。这样一个入口地址既能承载JS和CSS也能转发瓦片请求页面代码里就不需要配多个IP和端口后续迁移维护都很方便。Nginx里再开启gzip、设置缓存头性能和稳定性基本就都到位了。6. 从一套离线地图到可复用的前端资源包随着项目越做越多我逐渐意识到天地图离线地图的JS和CSS不应该只属于单个项目而应该沉淀成一套可复用的前端资源包。把下载的官方JS和CSS、改造后的控件样式、自定义的初始化封装函数、瓦片URL拼接逻辑全部归档配合版本号管理后续新项目直接引入这套资源包接入的周期从两三天压缩到半天。具体归档时我建议资源包保持“三个分离”的原则官方原始文件与自定义扩展文件分离、业务配置与地图能力代码分离、瓦片服务地址与前端资源地址分离。这样既能随时应对官方API升级也能在多个项目间快速复用还能避免换环境时到处查找硬编码地址的麻烦。最后再分享一个实操经验资源包内一定要带一个“自检页面”页面上只展示一张基础地图所有静态资源和瓦片服务都走一遍请求。部署到任何一个新环境先跑自检页面验证再跑业务页面任何资源链路的遗漏都会在自检页面上第一时间暴露出来。大部分现场部署事故我复盘下来都是因为少了这一步检查。本文还有配套的精品资源点击获取
