Sapper SSR的Svelte项目中如何模块化导入Leaflet.js解决window缺失问题
Sapper 项目模块化引入 Leaflet 的 SSR 适配方案
核心思路
不需要刻意在SSR环境下模拟window对象,也不推荐引入jsdom这类工具在服务端模拟浏览器环境——这类操作会大幅增加服务端bundle体积,还容易触发难以排查的兼容问题。
Leaflet是纯浏览器端运行的地图库,将其加载逻辑完全隔离到客户端专属执行上下文,从根源上避免服务端代码访问浏览器全局对象,是最稳定的实现方案。这种写法完全兼容Sapper官方提供的标准Rollup配置,不需要修改任何打包规则,也不会增加额外的构建维护成本。
具体实现步骤
- 安装Leaflet依赖
在项目根目录执行:npm install leaflet - 改造
map.svelte组件代码
遵循两个简单规则即可避免SSR报错:- Leaflet的样式文件可以直接在script顶层导入,Sapper的Rollup配置会自动完成样式提取打包,不会触发任何SSR报错
- Leaflet的JS核心库不能在script顶层做静态导入,要放到仅客户端执行的
onMount生命周期里做动态导入
完整参考代码:
<script> import { onMount } from 'svelte'; // 顶层导入样式无SSR风险 import 'leaflet/dist/leaflet.css'; export let map; onMount(async () => { // 动态导入仅在客户端执行,此时浏览器环境已经具备完整的window、document全局 const L = (await import('leaflet')).default; map = L.map('map', { zoomControl: false }).setView([57.6773, 11.9583], 13); const osm = L.tileLayer('https://{s}.tile.osm.org/{z}/{x}/{y}.png', { name: 'Open Street Map', maxZoom: 24, attribution: '© <a href="http://osm.org/copyright">OpenStreetMap</a> contributors' }).addTo(map); }); </script> <!-- 必须给地图容器设置明确的宽高,否则Leaflet无法正常计算渲染尺寸 --> <div id="map" style="width: 100%; height: 600px"></div>
运行原理说明
- 原来的顶层静态导入
import L from 'leaflet'会在模块解析阶段立即执行,Sapper做SSR预渲染时会在Node环境加载组件代码,这时候Node环境不存在window对象,Leaflet初始化一访问全局变量就会直接抛错 - 动态导入
await import('leaflet')放在onMount回调里时,Sapper在SSR阶段会直接跳过onMount的代码逻辑,根本不会执行Leaflet的加载和初始化流程,自然不会触发window缺失的问题;等页面传到浏览器完成水合(hydration)后,onMount才会触发,此时浏览器环境完整,Leaflet可以正常初始化 - Rollup会自动把动态导入的Leaflet代码单独拆成客户端异步 chunk,不会把它打进服务端运行的bundle里,从打包层面就隔离了环境差异
常见附加问题提示
如果引入后出现Leaflet默认标记图标加载失败的问题,是因为打包后的静态资源路径和Leaflet内置的默认图标路径不匹配,和SSR适配逻辑无关,单独修正图标资源路径即可解决。
内容的提问来源于stack exchange,提问作者minisaurus
相关产品推荐
相关产品推荐

