React Leaflet标记图标损坏，修改默认Icon配置后仍无法正常显示

问题根因 #

Leaflet 内置的默认图标路径规则和现代前端构建工具（Vite、Webpack 等）的静态资源处理逻辑不兼容，导致图标资源路径解析错误，出现损坏无法加载的问题。

解决方案 #

方案1：适配构建工具调整资源引用语法 #

• 如果使用 Vite 作为构建工具，Vite 不支持 CommonJS 的 require 语法导入静态资源，需替换为 ES 模块导入方式：

import L from "leaflet";
import { Map, TileLayer, Marker, Popup } from "react-leaflet";
import "leaflet/dist/leaflet.css";

// 导入Leaflet自带图标资源，使用自定义本地图标替换对应路径即可
import iconRetina from "leaflet/dist/images/marker-icon-2x.png";
import icon from "leaflet/dist/images/marker-icon.png";
import shadow from "leaflet/dist/images/marker-shadow.png";

delete L.Icon.Default.prototype._getIconUrl;

L.Icon.Default.mergeOptions({
  iconRetinaUrl: iconRetina,
  iconUrl: icon,
  shadowUrl: shadow,
});

• 如果使用 Webpack 5 作为构建工具，require 导入静态资源返回的是模块对象，需取.default属性获取真实资源路径：

import L from "leaflet";
import { Map, TileLayer, Marker, Popup } from "react-leaflet";
import "leaflet/dist/leaflet.css";

delete L.Icon.Default.prototype._getIconUrl;

L.Icon.Default.mergeOptions({
  iconRetinaUrl: require("leaflet/dist/images/marker-icon-2x.png").default,
  iconUrl: require("leaflet/dist/images/marker-icon.png").default,
  shadowUrl: require("leaflet/dist/images/marker-shadow.png").default,
});

方案2：自定义Icon实例显式传入Marker #

不想修改全局默认Icon配置的情况下，可以单独定义Icon实例，传入每个Marker的icon属性即可：

// 定义自定义图标
const markerIcon = new L.Icon({
  iconRetinaUrl: require("leaflet/dist/images/marker-icon-2x.png").default,
  iconUrl: require("leaflet/dist/images/marker-icon.png").default,
  shadowUrl: require("leaflet/dist/images/marker-shadow.png").default,
  iconSize: [25, 41], // 图标尺寸，可根据实际调整
  iconAnchor: [12, 41], // 图标锚点位置
  popupAnchor: [1, -34], // 弹窗锚点位置
  shadowSize: [41, 41] // 阴影尺寸
})

// 组件中使用Marker时传入icon参数
<Marker position={[纬度, 经度]} icon={markerIcon}>
  <Popup>弹窗内容</Popup>
</Marker>

额外排查点 #

如果使用本地自定义图标，需要确认相对路径是否正确，比如代码文件存放在src/pages目录，图标存放在src/assets/images目录，那么引用路径应该写../assets/images/xxx.png。

内容的提问来源于stack exchange，提问作者Sai Krishnadas