folium离线模式全攻略：手把手教你打包本地资源库（含CSS/JS文件下载）

Folium离线部署终极指南：从资源打包到内网实战

当你需要在隔离网络环境中运行地理可视化应用时，依赖在线资源的folium地图往往会变成一片空白。本文将彻底解决这个痛点，带你从零构建完整的离线解决方案。

1. 离线化核心原理剖析

folium的在线依赖主要分布在三个层面：

1. 基础库资源：包括leaflet.js、jQuery等前端库
2. 样式资源：CSS样式表和字体文件
3. 地图瓦片：实际地图图片数据

典型的离线报错场景：

import folium
m = folium.Map(location=[39.9, 116.4], zoom_start=10)
m.save('map.html')  # 生成的HTML文件仅4KB左右

关键诊断步骤：

• 检查生成的HTML文件大小（正常应包含所有资源）
• 浏览器开发者工具查看网络请求失败项
• 确认控制台报错信息

2. 基础资源本地化实战

2.1 手动下载核心资源

创建资源目录结构：

folium_offline/
├── js/
├── css/
└── fonts/

必须下载的资源清单：

资源类型	文件名	原始CDN地址
JS库	leaflet.js	https://cdn.jsdelivr.net/npm/leaflet@1.9.3/dist/leaflet.js
JS库	jquery-3.7.1.min.js	https://code.jquery.com/jquery-3.7.1.min.js
CSS	leaflet.css	https://cdn.jsdelivr.net/npm/leaflet@1.9.3/dist/leaflet.css

提示：建议使用wget或curl批量下载，保存时保持原始文件名

2.2 修改folium源码实现本地加载

定位到Python环境中的folium/folium.py，修改资源声明：

_default_js = [
    ('leaflet', 'file:///path/to/folium_offline/js/leaflet.js'),
    ('jquery', 'file:///path/to/folium_offline/js/jquery-3.7.1.min.js')
]

_default_css = [
    ('leaflet_css', 'file:///path/to/folium_offline/css/leaflet.css')
]

常见编码问题解决方案：

# 修改offline.py中的文件读取逻辑
with open(filepath, 'r', encoding='utf-8') as f:  # 显式指定编码
    return f.read()

3. 地图瓦片离线化方案

3.1 瓦片下载工具推荐

• QGIS：可视化下载特定区域瓦片
• Mobile Atlas Creator：支持多种地图源
• Python脚本批量下载：

import requests
import os

zxy = [(z,x,y) for z in range(10) for x in range(2**z) for y in range(2**z)]
for z,x,y in zxy:
    url = f"https://tile.openstreetmap.org/{z}/{x}/{y}.png"
    os.makedirs(f"tiles/{z}/{x}", exist_ok=True)
    with open(f"tiles/{z}/{x}/{y}.png", "wb") as f:
        f.write(requests.get(url).content)

3.2 自定义瓦片配置

folium.Map(
    tiles='file:///path/to/tiles/{z}/{x}/{y}.png',
    attr='Custom Offline Tiles',
    zoom_start=10
)

瓦片存储优化技巧：

• 按缩放级别分目录存储
• 使用MBTiles格式整合所有瓦片
• 考虑使用GeoServer发布本地瓦片服务

4. 完整离线部署流程

4.1 资源打包方案

创建标准化资源包：

offline_folium_pkg/
├── __init__.py
├── resources/
│   ├── js/
│   ├── css/
│   └── tiles/
└── config.json

安装时自动部署资源的setup.py配置示例：

from setuptools import setup
import os

def package_files(directory):
    paths = []
    for (path, _, filenames) in os.walk(directory):
        for filename in filenames:
            paths.append(os.path.join('..', path, filename))
    return paths

extra_files = package_files('offline_folium_pkg/resources')

setup(
    name="offline_folium",
    version="0.1",
    packages=["offline_folium"],
    package_data={"": extra_files},
    include_package_data=True,
)

4.2 企业级部署建议

1. 网络架构：

   • 搭建内部CDN托管静态资源
   • 配置Nginx反向代理缓存地图服务

2. 安全策略：

   • 资源文件完整性校验
   • 访问权限控制
   • 定期更新机制

3. 性能优化：

   # Nginx配置示例
   location /tiles/ {
       gzip on;
       expires 365d;
       access_log off;
   }
   

5. 常见问题排错指南

问题现象：地图容器显示但瓦片空白

• 检查控制台是否有404错误
• 确认瓦片路径是否正确
• 验证跨域访问权限

问题现象：字体图标不显示

• 检查字体文件路径
• 确认CSS中字体引用路径
• 测试字体文件可访问性

典型错误日志分析：

GET file:///path/to/font.ttf net::ERR_UNKNOWN_URL_SCHEME

解决方案：改用本地HTTP服务或base64嵌入字体

调试技巧：

• 使用folium.Figure()创建调试视图
• 逐步添加图层定位问题
• 比较在线/离线生成的HTML差异

6. 高级应用场景

6.1 结合GeoJSON离线数据

with open('local_data.geojson') as f:
    geojson_data = json.load(f)

folium.GeoJson(
    geojson_data,
    name='离线数据集',
    style_function=lambda x: {'fillColor': '#ff0000'}
).add_to(map)

6.2 自定义插件离线化

以MarkerCluster为例：

1. 下载插件JS/CSS：https://cdnjs.cloudflare.com/ajax/libs/leaflet.markercluster/1.4.1/
2. 修改插件初始化代码：

L.markerClusterGroup({
    iconCreateFunction: function(cluster) {
        return L.divIcon({
            html: '<div>'+cluster.getChildCount()+'</div>',
            className: 'marker-cluster'
        });
    }
});

6.3 性能优化方案

瓦片加载优化对比表：

方案	优点	缺点	适用场景
预下载全部瓦片	完全离线	存储占用大	固定区域小范围
动态瓦片服务	灵活更新	需要服务器	大范围多变区域
矢量瓦片	体积小精度高	渲染性能要求高	高精度需求

实际项目中，我们曾为某应急指挥系统实施离线方案，将地图加载时间从超时降低到800ms内，关键是在资源完整性和更新便捷性之间找到了平衡点。