GIS研习社 GIS研习社
编程与开发 Leaflet leaflet翻译成中文

Leaflet地图符号不显示？中文乱码怎么快速解决（附：字体配置全攻略）

编程与开发
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

遇到“Leaflet地图符号不显示？中文乱码怎么快速解决（附：字体配置全攻略）”这类问题时，很多 GIS 同学第一反应是数据坏了，或者 Leaflet 图层加载失败。实际上，地图符号不显示、中文标注变成方框、问号、乱码，常见原因往往集中在字体、编码、图标资源路径、样式表加载顺序和切片服务渲染环境这几个环节。

本文面向 WebGIS 开发者、GIS 工程初学者和正在用 Leaflet 做项目展示的同学，重点解决 Leaflet 地图符号不显示、Leaflet 中文乱码、Leaflet 字体配置、Marker 图标丢失、GeoJSON 标注异常等实际问题。

引言：Leaflet地图符号不显示通常不是一个单点问题

在 Leaflet 项目中，“符号不显示”可能指几种不同现象：

  • 默认 Marker 图标不显示，只剩一个空白点或破图图标。
  • 自定义 SVG、PNG 图标不显示。
  • GeoJSON 点线面样式没有生效。
  • 中文标注显示为乱码、方框、豆腐块。
  • 地图服务端切片中的中文注记不显示。
  • 前端弹窗 Popup、Tooltip 中的中文乱码。

这些问题看起来相似，但排查路径不同。正确做法是先判断问题发生在前端 Leaflet 渲染，还是发生在数据编码，或者发生在服务端切片/字体环境。

Leaflet地图符号不显示与Leaflet中文乱码排查流程图
Leaflet 地图符号不显示和中文乱码的常见排查路径：先看资源，再看编码，最后看字体与服务端渲染环境。

背景：为什么 Leaflet 中文乱码和符号丢失经常一起出现

Leaflet 本身是一个前端地图渲染库，它负责把瓦片、矢量数据、Marker、Popup、Tooltip 等内容显示在浏览器中。Leaflet 不会自动修复数据编码，也不会替你下载缺失的字体或图标资源。

所以当你看到 Leaflet 地图符号不显示时，常见背景通常有以下几类：

  • 项目从本地迁移到服务器后，图片路径变化，Marker 图标资源找不到。
  • 使用打包工具后，Leaflet 默认图标路径被改变。
  • GeoJSON、CSV、接口返回数据不是 UTF-8 编码，导致中文乱码。
  • 页面 HTML 没有声明 UTF-8，浏览器按错误编码解析文本。
  • 字体文件没有加载成功，中文或特殊符号无法显示。
  • 服务端生成地图切片时没有安装中文字体，中文注记在切片阶段已经丢失。
  • CSS 被覆盖，图标尺寸、透明度、z-index 或 display 属性异常。

对于 GIS 项目来说，符号和中文标注往往都来自同一批空间数据字段。如果编码错了，属性表中的名称字段会乱码；如果字体错了，中文虽然被正确读取，但浏览器或服务端没有字体来画出这些字。

原理：先区分“编码问题”“字体问题”和“资源路径问题”

1. 编码问题：文字内容本身被错误解析

编码问题指的是“文字在进入浏览器之前或被浏览器读取时已经错了”。例如原始 CSV 是 GBK 编码，但前端按 UTF-8 读取，就可能出现乱码。

典型表现：

  • Popup 中中文显示为“地å��”一类乱码。
  • GeoJSON 属性字段打开后就是乱码。
  • 接口返回的 JSON 在浏览器 Network 面板预览中已经乱码。

2. 字体问题：文字内容正确，但没有合适字体显示

字体问题指的是“数据是对的，但显示环境没有能绘制这些字符的字体”。中文显示成方框、空白、问号，常常与字体缺失有关。

典型表现：

  • 浏览器开发者工具中看到中文内容是正确的，但页面显示为方框。
  • 地图切片中的中文注记缺失，但英文和数字正常。
  • 服务器上生成的 PNG 切片没有中文，换到本地桌面软件却正常。

3. 资源路径问题：图标、CSS 或字体文件没有加载成功

Leaflet 地图符号不显示最常见的前端原因，是图标资源路径错误。默认 Marker 依赖 PNG 图片，如果图片 404，地图上就看不到熟悉的蓝色图钉。

典型表现：

  • 浏览器控制台出现 404。
  • Network 面板中 marker-icon.png、marker-shadow.png、字体文件加载失败。
  • 本地开发正常，部署到 Nginx、IIS、Tomcat 或静态服务器后异常。

步骤：快速解决 Leaflet 地图符号不显示和中文乱码

步骤 1：检查 Leaflet CSS 是否正确引入

Leaflet 的默认 Marker 图标、控件样式、缩放按钮样式都依赖 Leaflet CSS。如果只引入了 JS，没有引入 CSS，地图可能能显示，但控件和符号会异常。

<link rel="stylesheet" href="https://unpkg.com/leaflet/dist/leaflet.css">
<script src="https://unpkg.com/leaflet/dist/leaflet.js"></script>

建议检查：

  • CSS 是否在 Leaflet JS 之前加载。
  • 浏览器 Network 面板中 leaflet.css 是否返回 200。
  • 是否被 CSP、安全策略或内网代理拦截。
  • 是否存在其他 CSS 覆盖了 leaflet-marker-icon、leaflet-tooltip、leaflet-popup。

步骤 2：修复 Leaflet 默认 Marker 图标路径

如果地图底图正常，但默认 Marker 图标不显示，优先检查 marker-icon.png 和 marker-shadow.png 是否能访问。尤其是在 Vite、Webpack、Vue、React、Angular 项目中，Leaflet 默认图标路径经常需要手动配置。

var defaultIcon = L.icon({
  iconUrl: '/assets/leaflet/marker-icon.png',
  shadowUrl: '/assets/leaflet/marker-shadow.png',
  iconRetinaUrl: '/assets/leaflet/marker-icon-2x.png',
  iconSize: [25, 41],
  iconAnchor: [12, 41],
  popupAnchor: [1, -34],
  shadowSize: [41, 41]
});

L.marker([31.2304, 121.4737], { icon: defaultIcon })
  .addTo(map)
  .bindPopup('上海市中心');

如果你不想每次创建 Marker 都传 icon，也可以覆盖默认图标配置：

L.Icon.Default.mergeOptions({
  iconUrl: '/assets/leaflet/marker-icon.png',
  iconRetinaUrl: '/assets/leaflet/marker-icon-2x.png',
  shadowUrl: '/assets/leaflet/marker-shadow.png'
});

这里的关键不是代码形式，而是确保图片路径在最终部署环境中真实可访问。可以把图片 URL 复制到浏览器地址栏直接打开测试。

步骤 3：确认页面和接口统一使用 UTF-8

Leaflet 中文乱码最常见的基础修复，是统一页面、接口和数据文件编码为 UTF-8。

<meta charset="UTF-8">

如果数据来自后端接口，响应头建议包含：

Content-Type: application/json; charset=utf-8

如果是静态 GeoJSON 文件，建议保存为 UTF-8 无 BOM 格式，并让服务器返回正确的 MIME 类型：

Content-Type: application/geo+json; charset=utf-8

如果是 CSV 文件，尤其是从 Excel 导出的中文数据，常见情况是 GBK 或 UTF-8 BOM。前端直接读取时要特别小心。更稳妥的做法是在数据入库或发布前，用 QGIS、GDAL、Python 统一转换编码。

步骤 4：检查 GeoJSON 属性字段是否已经乱码

如果 GeoJSON 文件打开后属性字段本身就是乱码，那么 Leaflet 无法恢复原文。可以先用文本编辑器、QGIS 或 Python 检查数据。

{
  "type": "Feature",
  "properties": {
    "name": "人民广场"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [121.475, 31.232]
  }
}

Leaflet 中显示属性的基本写法如下：

L.geoJSON(geojsonData, {
  onEachFeature: function (feature, layer) {
    var name = feature.properties.name || '未命名';
    layer.bindPopup(name);
  }
}).addTo(map);

如果这里的 name 在控制台打印就是乱码，问题在数据源或接口编码；如果控制台是正确中文，但页面显示方框，问题更可能在字体。

步骤 5：为 Leaflet Popup、Tooltip 和标注配置中文字体

浏览器通常会自动使用系统中文字体，但在某些企业内网、Linux 桌面、嵌入式浏览器、Electron 应用、定制 WebView 环境中，中文字体可能不完整。建议在 CSS 中明确指定中文字体栈。

.leaflet-container,
.leaflet-popup-content,
.leaflet-tooltip {
  font-family: "Microsoft YaHei", "PingFang SC", "Noto Sans CJK SC", "Source Han Sans SC", Arial, sans-serif;
}

如果项目需要跨平台稳定显示中文，可以使用 Web Font，但要注意字体文件体积和授权问题。

@font-face {
  font-family: "GisChineseFont";
  src: url("/assets/fonts/NotoSansCJKsc-Regular.woff2") format("woff2");
  font-weight: normal;
  font-style: normal;
}

.leaflet-container {
  font-family: "GisChineseFont", "Microsoft YaHei", sans-serif;
}

这里推荐优先使用系统字体栈，只有在内网大屏、离线部署、专用终端等场景下再考虑内置字体文件。

步骤 6：修复 SVG、Canvas 或 DivIcon 中的特殊符号显示

很多 Leaflet 项目会用 L.divIcon 显示编号、分类符号、中文简称。如果 divIcon 中使用了图标字体、特殊符号或中文，也要检查字体是否加载成功。

var labelIcon = L.divIcon({
  className: 'site-label-icon',
  html: '<span>水文站</span>',
  iconSize: [80, 28],
  iconAnchor: [40, 14]
});

L.marker([30.67, 104.06], { icon: labelIcon }).addTo(map);
.site-label-icon span {
  display: inline-block;
  padding: 4px 8px;
  background: #1677ff;
  color: #ffffff;
  border-radius: 4px;
  font-family: "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
  font-size: 13px;
  white-space: nowrap;
}

如果使用 Font Awesome、Iconfont 或 Material Icons，符号不显示时要检查：

  • 字体 CSS 是否加载成功。
  • 字体文件 woff、woff2 是否 404。
  • 跨域字体是否被 CORS 拦截。
  • 图标 class 名是否与当前版本一致。

步骤 7：检查服务端切片中的中文字体

如果你加载的是 WMS、WMTS、XYZ 瓦片，中文注记可能不是 Leaflet 在浏览器里画出来的，而是在服务端已经渲染成图片。此时前端字体配置无法解决切片中的中文乱码。

常见服务端包括 GeoServer、MapServer、QGIS Server、Mapnik、自建 Python 切片程序等。排查方法是：

  1. 直接在浏览器中打开瓦片图片 URL，看图片中中文是否正常。
  2. 如果图片本身没有中文，问题在服务端渲染环境。
  3. 检查服务器操作系统是否安装中文字体。
  4. 检查地图样式文件是否指定了可用字体。
  5. 重启地图服务，清理瓦片缓存后再测试。

Linux 服务器上常见的中文字体方案是安装 Noto CJK 或思源黑体。安装后要确认渲染程序能识别该字体，而不是只完成系统安装。

步骤 8：用浏览器开发者工具定位问题

不要只靠肉眼猜。Leaflet 地图符号不显示时，浏览器开发者工具是最快的排查工具。

  1. 打开 F12 开发者工具。
  2. 切到 Network 面板，刷新页面。
  3. 筛选 Img、CSS、Font、Fetch/XHR。
  4. 检查 marker-icon.png、字体文件、GeoJSON、接口是否返回 200。
  5. 切到 Console 面板，看是否有 CORS、404、MIME type、JSON parse 错误。
  6. 选中地图元素，看 CSS 中 font-family、display、opacity、z-index 是否异常。

如果 Network 面板已经显示图标 404，就不要继续改 Leaflet 代码；如果接口返回内容已乱码，就不要继续改 CSS 字体。

常见坑：Leaflet 符号和中文显示最容易忽略的细节

坑 1：本地 file 协议打开页面

很多初学者直接双击 HTML 文件运行 Leaflet 示例。这样可能导致本地资源、字体、GeoJSON 请求受限制。建议使用本地 HTTP 服务测试。

python -m http.server 8000

然后访问：

http://localhost:8000

坑 2：只改了前端字体，却没有处理服务端切片

如果中文注记已经被渲染进瓦片图片，前端 CSS 无法改变瓦片里的文字。此时要去 GeoServer、MapServer 或切片程序中处理字体。

坑 3：图标路径在开发环境和生产环境不一致

开发时路径是 /src/assets/marker-icon.png，打包后可能变成 /assets/marker-icon-abcd.png。生产环境需要使用构建工具支持的资源引用方式，或者把 Leaflet 图标放到 public 静态目录。

坑 4：GeoJSON 文件不是 UTF-8

GeoJSON 标准推荐 UTF-8。中文 GIS 数据如果从 Shapefile、CSV、Excel 多次转换而来，很容易在某一步编码错乱。发布前应统一编码并抽样检查属性字段。

坑 5：Shapefile 字段编码传递到前端时已经错误

Shapefile 的中文属性依赖 .cpg 文件或软件识别编码。如果在转换为 GeoJSON 时编码识别错误，Leaflet 端看到的就是错误文本。建议用 GDAL 明确指定源编码。

ogr2ogr -f GeoJSON output.geojson input.shp -lco RFC7946=YES -oo ENCODING=GBK

坑 6：CSS 把 Marker 或 Tooltip 隐藏了

有些全局样式会误伤 Leaflet 元素。例如设置 img max-width、position、opacity、filter，或对 div span 做了全局 display 规则。遇到符号消失时，要检查是否存在样式覆盖。

方法比较：不同场景下应该改哪里

现象 最可能原因 优先处理方法
默认蓝色 Marker 不显示 Leaflet 图标图片路径错误 检查 marker-icon.png，手动配置 L.icon 或 L.Icon.Default
Popup 中文乱码 页面、接口或数据编码不一致 统一 UTF-8，检查响应头和 GeoJSON 文件编码
中文显示为方框 字体缺失或字体文件加载失败 配置中文字体栈，必要时引入 Web Font
瓦片中的中文不显示 服务端渲染环境没有中文字体 在 GeoServer、MapServer、QGIS Server 或切片服务器安装并配置字体
Iconfont 符号不显示 字体文件 404、跨域或 class 错误 检查 Font 请求、CORS、图标库版本和 class 名
GeoJSON 点位有数据但样式不显示 样式函数、坐标顺序或图层顺序错误 检查 style、pointToLayer、坐标是否为经度在前纬度在后

简单记忆：图片符号看资源路径，中文乱码看编码，方框豆腐块看字体，瓦片注记看服务端。

检查清单：发布前快速确认 Leaflet 字体配置和符号显示

  • HTML 页面已声明 UTF-8。
  • 接口响应头包含正确的 charset。
  • GeoJSON、CSV 等静态数据已统一为 UTF-8。
  • Leaflet CSS 和 JS 都成功加载。
  • marker-icon.png、marker-icon-2x.png、marker-shadow.png 可访问。
  • 自定义图标路径在生产环境中仍然有效。
  • Popup、Tooltip、DivIcon 设置了合理的中文字体栈。
  • 如果使用 Web Font，woff2 文件没有 404，也没有跨域错误。
  • 如果是服务端切片，服务器已安装并配置中文字体。
  • 浏览器 Console 中没有 JSON 解析、CORS、MIME type、404 错误。
  • 移动端、内网终端、大屏浏览器至少各抽测一次。

FAQ：Leaflet 地图符号不显示与中文乱码常见问题

问：Leaflet 中文乱码一定是字体问题吗？

不一定。Leaflet 中文乱码更常见的是编码问题，例如 GeoJSON、CSV、接口响应不是 UTF-8。字体问题通常表现为中文内容正确但显示成方框或空白。建议先在浏览器控制台打印属性值，如果打印内容已经乱码，就先处理编码。

问：为什么 Leaflet 默认 Marker 在本地正常，部署后不显示？

多数是图标图片路径变化导致的。打包或部署后，Leaflet 默认查找 marker-icon.png 的位置可能不再正确。应在生产环境中打开 Network 面板，检查图标图片是否 404，并手动配置 iconUrl、shadowUrl。

问：GeoJSON 中文属性在 QGIS 中正常，Leaflet 中乱码怎么办？

先确认导出的 GeoJSON 是否为 UTF-8。QGIS 中能正常显示，不代表导出文件或接口传输时编码一定正确。建议用文本编辑器检查文件编码，或重新导出为 UTF-8 GeoJSON，再通过 HTTP 服务访问测试。

问：Leaflet 地图瓦片上的中文不显示，改 CSS 有用吗？

通常没用。瓦片上的文字已经被服务端渲染成图片，前端 CSS 不能修改图片里的文字。应检查切片服务端是否安装中文字体，地图样式是否指定了可用中文字体，并清理瓦片缓存后重新生成。

问：Leaflet 使用 Iconfont 后符号变成小方块，怎么解决？

这通常是图标字体没有加载成功，或者 class 名不匹配。检查 iconfont.css、woff、woff2 是否返回 200；如果字体跨域加载，服务器需要允许字体资源跨域。还要确认当前使用的图标名称和图标库版本一致。

问：Leaflet DivIcon 中的中文标注被截断怎么办？

检查 iconSize、iconAnchor、white-space 和容器宽度。对于中文名称，建议设置 white-space: nowrap，并给 divIcon 合理宽度。如果名称很长，可以使用 Tooltip 或 Popup 展示完整内容。

结论：按“资源、编码、字体、服务端”四步排查最稳

Leaflet 地图符号不显示和中文乱码看似杂乱，但排查逻辑很清楚：默认 Marker 消失先看图标资源路径；Popup、Tooltip 中文乱码先看 UTF-8 编码；中文变方框先看字体配置；瓦片注记缺失则去服务端检查字体环境。

实际项目中，建议把 Leaflet 字体配置、默认图标路径、GeoJSON 编码检查纳入 WebGIS 发布清单。这样不仅能快速解决 Leaflet 中文乱码，也能减少上线后出现地图符号不显示、标注异常、内网环境显示不一致等问题。