企业官网建设流程全解析

简介：面向使用地图可视化组件、希望摆脱远程加载缓慢问题的开发者，这份打包内容包含前端依赖的完整静态文件，包括核心地图库、交互脚本、界面框架、图表字体等资源，以及配套的样式源文件和地图标记图片，共77个文件，整体仅1.81MB。将本地文件引用替换至生成的网页中，可避免跨境访问公共资源导致的长时间等待；在线地图场景也可通过服务器代理这些静态资源来加速打开，资源按目录清晰组织，区分样式、脚本、字体和图片，便于维护与集成。目前已有1467人学习下载，配合Python脚本可实现引用路径批量本地化，并为地图的样式定制、标记扩展和加载优化提供现成素材，适合数据可视化、地理信息展示和Web地图应用开发场景。

1. 离线地图页面为什么卡在 js/css 上：folium 本地资源的真正问题

开发好的 folium 地图页面，在办公室的联网环境里一切正常，一旦拷进隔离区或者内网展示，双击打开就只剩一个空壳：底图灰、缩放按钮没反应、控制台里一片 404。问题几乎都出在同一处——folium 默认把 Leaflet 的 JavaScript 和 CSS 放在了网上，页面加载时要去外网拉资源。这个标题里说的“本地资源 / src资源”，本质就是一套把 folium 生成的 HTML 从在线引用改成离线本地引用的流程。本文按“资源从哪来 → 怎么下载 → 怎么改引用 → 怎么避坑”的顺序给出可复现的做法，适合正在做地图数据展示、报告系统、内部可视化大屏的开发者，也适合刚接触 folium 没几天的初学者直接照着抄。

2. 先看清楚 folium 生成了什么：在线资源的根源与本地化的三个判定标准

2.1 一条 Map 指令背后，HTML 里究竟引用了什么

folium 不是把地图画成一张图片，而是生成一份包含 Leaflet 标记语言和脚本的独立 HTML。你在 Python 里写下的Map(...)经过封装，最终会输出一段完整的<html>，其中<head>里带有一串<link>和<script>标签，指向若干外部资源。用最小示例看一下实际输出：

import folium m = folium.Map(location=[45.0, 120.0], zoom_start=5) root = m.get_root() html_text = root.render() head_start = html_text.find('<head>') head_end = html_text.find('</head>') print(html_text[head_start:head_end + len('</head>')])

这段代码的关键是get_root().render()，它会返回整份 HTML 的字符串。我实际跑出来的<head>片段结构大致是下面这样，地址已做脱敏处理：

<head> <meta charset="utf-8" /> <link rel="stylesheet" href="https://cdn.example.com/leaflet/dist/leaflet.css"/> <script src="https://cdn.example.com/leaflet/dist/leaflet.js"></script> ... </head>

这里的href和src就是标题里说的“src资源”。folium 把 Leaflet 的样式和脚本看成外部依赖，默认从 CDN 拉取。HTML 本身只是骨架，真正的渲染逻辑在leaflet.js里，控件的样式和图标在leaflet.css里。CDN 地址写死在 folium 的资源清单中，跟你的代码、跟你的服务器没有任何关系。所以只要运行环境访问不了外网，这些src就全部失败，地图自然只剩一个空壳。

2.2 外链的三个现实代价：加载慢、内网不可用、维护不可控

第一个代价是白屏时间。每次用户打开页面，浏览器都要重新去外网做 DNS 解析、建立连接、下载资源。哪怕你的后端再快，前端也卡在“等 CDN 响应”这一步。内网环境尤其是这样，公网带宽窄、链路不稳定，一个leaflet.js可能要等十几秒，体验很糟糕。

第二个代价是内网不可用。很多单位的数据展示系统跑在隔离网络里，物理上就不通外网，默认 CDN 资源根本拉不进来。更麻烦的是，有些浏览器安全策略会拦截混合内容，HTTPS 页面里加载 HTTP 的外部资源直接失败，你连排查的机会都没有。

第三个代价是维护不可控。folium 升级后，使用的 Leaflet 版本可能变化，资源 URL 的路径、版本号也会变。旧版生成的 HTML 里写死的 CDN 链接一旦失效，页面就成了死页面。把这些资源本地化之后，HTML 变成自包含的产物，版本、路径、可用性都由你掌控，不再受上游 CDN 变动影响。

2.3 本地化的判定标准：不是改完 src 就算成功

很多人在这一步满足于“把 src 替换成相对路径”，却没意识到 folium 用的 Leaflet 是一个完整的前端库：js 负责地图渲染与交互，css 负责控件和图标样式，两者之外还有少量 css 内引用的图片子资源。所以本地化成功有三个标准。

第一，页面里所有外部域名的 js/css 请求数为 0。打开浏览器开发者工具的 Network 面板，筛选 JS 和 CSS，如果还有任何请求指向公网地址，就说明没改干净。第二，地图控件渲染完整。放大缩小按钮、缩放比例尺、图层控制面板都应该正常显示，而不是缺图标、错位、空白。第三，marker 图标和 css 子资源全部显示。很多项目翻车就翻在这里：js 本地化成功了，地图也能拖了，但 marker 图标变成一个小方块，因为leaflet.css内部还引用着images/marker-icon.png这类相对路径资源，同样需要本地化。

判定标准明确了，后面做替换时就有了检查依据，不会盲目认为自己已经“改完”。

3. folium 资源本地化的一趟完整流程：提取、下载、替换、部署

3.1 先拿到可以改的 HTML 字符串，而不是急着 save()

folium 的Map.save()很方便，但它直接把最终 HTML 写进文件，中间没有给你修改的机会。本地化的第一步，是改用get_root().render()把这个 HTML 以字符串形式拿到内存里，替换完成后再写文件。这样你既能看清单，又能做批量替换。

import folium m = folium.Map(location=[45.0, 120.0], zoom_start=5) # 后续可以继续往 m 上添加 Marker、TileLayer、Popup 等要素 root = m.get_root() html_text = root.render()

逻辑说明：get_root()拿到 folium 的元素树根节点，render()按模板渲染成字符串。render()可以反复调用，所以你可以先打印确认外链地址，再去做替换，不需要担心“渲染一次就不能再修改”。

参数说明：location传入地图中心经纬度，zoom_start控制初始缩放级别。本地化只影响资源加载方式，不影响这些地图语义参数。调大zoom_start地图初始显示范围变小，和资源无关。

3.2 批量提取 src/href 外链并下载到资源目录

有了html_text，接下来做三件事：用正则把所有外链提出来、为每个外链生成本地文件名、批量下载到指定目录。这比手写一张资源清单可靠得多，因为不同版本 folium 引用的资源列表并不完全一致，手写容易漏，正则提取则是一网打尽。

import os import re import hashlib import urllib.request from urllib.parse import urlparse ASSET_DIR = "assets" os.makedirs(ASSET_DIR, exist_ok=True) url_pattern = re.compile(r'(?:src|href)=["\'](https?://[^"\']+)["\']', re.IGNORECASE) external_urls = list(set(url_pattern.findall(html_text))) download_map = {} for url in external_urls: path = urlparse(url).path filename = path.split("/")[-1] or "index.html" # 用 URL 的 md5 前缀做文件名，避免不同目录下的同名文件互相覆盖 suffix = hashlib.md5(url.encode()).hexdigest()[:8] safe_name = f"{suffix}_{filename}" local_path = os.path.join(ASSET_DIR, safe_name) urllib.request.urlretrieve(url, local_path) download_map[url] = safe_name print(f"downloaded: {url} -> {local_path}")

逻辑说明：正则同时匹配<link>的href和<script>的src，并兼容单双引号。urlparse(url).path取出 URL 的路径部分，split('/')[-1]得到文件名；如果遇到https://.../dist/这类以斜杠结尾的地址，就用index.html兜底。文件名前面拼一个 URL 的 md5 前缀，是为了防止不同目录下同名资源互相覆盖，比如两个不同版本的leaflet.js。

参数说明：ASSET_DIR是资源落盘目录。在内网独立部署场景，它和 HTML 放在同一级，这样后面替换成相对路径后可以直接双击打开；如果要通过后端托管，就把它设成静态资源目录，比如 Flask 项目里的static。下载失败时，把报错 URL 复制到浏览器里手动打开确认，八成是网络代理或防火墙拦截。

3.3 替换路径并修复 CSS 内部子资源引用

文件下载只是第一步。接下来要把html_text里的外链整体替换成本地路径，同时处理 CSS 文件内部对图片字体的相对引用。后者最容易被漏掉：不处理的话，marker 图标、图层面板的关闭图标会全部变成空白块。

from urllib.parse import urljoin # 1) 把 HTML 里的 JS/CSS 外链统一替换成本地相对路径 for url, safe_name in download_map.items(): html_text = html_text.replace(url, ASSET_DIR + "/" + safe_name) # 2) 单独处理 css 文件内部的 url(...) 子资源 css_pattern = re.compile(r'url\((["\']?)([^"\')]+)\1\)') for url, safe_name in download_map.items(): local_css = os.path.join(ASSET_DIR, safe_name) if not local_css.endswith(".css"): continue with open(local_css, encoding="utf-8") as f: css_text = f.read() base_url = url[: url.rfind("/") + 1] css_dir = os.path.dirname(local_css) for quote, ref in css_pattern.findall(css_text): if ref.startswith(("data:", "http")): continue full_url = urljoin(base_url, ref) rel_path = urlparse(full_url).path.lstrip("/") target = os.path.join(ASSET_DIR, rel_path) os.makedirs(os.path.dirname(target), exist_ok=True) urllib.request.urlretrieve(full_url, target) local_ref = os.path.relpath(target, css_dir) css_text = css_text.replace(f'url({quote}{ref}{quote})', f'url({local_ref})') with open(local_css, "w", encoding="utf-8") as f: f.write(css_text)

逻辑说明：第一个循环是整体替换，把 HTML 里所有出现的 CDN 地址换成assets/xxx_leaflet.js这种相对路径。第二个循环处理 CSS 子资源：urljoin(base_url, ref)会把images/marker-icon.png这种相对引用，和 CSS 文件所在的原 CDN 目录拼成完整地址，再下载到本地。relpath计算的是子资源相对 CSS 文件的路径，这样 CSS 里url(images/marker-icon.png)就能正确指向本地文件，不会因为目录层级错乱而 404。

参数说明：base_url取的是原 CSS 文件所在的目录层级，确保相对引用正确拼接。data:开头的 base64 内嵌资源不需要下载，http开头的绝对引用一般不需要动，这两类都会被跳过。如果你用的是自定义字体或特殊图标库，这里的正则逻辑同样适用，只是下载的文件类型可能从图片变成 woff2、svg。

3.4 落地：file:// 直接打开、Flask 托管、notebook 内嵌三选一

本地化完成后的 HTML 可以按三种方式交付。第一种是双击直接用file://打开，前提是 HTML 与assets目录同级，且引用路径是相对的。第二种是交给后端托管，比如 Flask，此时建议把资源路径设计成静态目录，由路由统一返回。第三种是还在 notebook 里用，通过IPython.display.HTML渲染。

# 方式一：写成本地 HTML，直接双击打开 with open("localized_map.html", "w", encoding="utf-8") as f: f.write(html_text)

# 方式二：交给 Flask 托管，资源走独立路由 from flask import Flask, send_from_directory app = Flask(__name__) @app.route("/") def index(): with open("localized_map.html", encoding="utf-8") as f: return f.read() @app.route("/assets/<path:filename>") def assets(filename): return send_from_directory("assets", filename)

# 方式三：还在 notebook 里临时查看 from IPython.display import HTML HTML(html_text)

逻辑说明：三种方式的差别在资源路径的解析基准。file://下相对路径最省事；Flask 下路由规则要和 HTML 里写的目录一致，否则会 404；notebook 里直接显示html_text时，相对路径是相对 Jupyter 服务根路径解析的，所以如果资源不在 notebook 同目录，就会加载失败。

参数说明：send_from_directory的第二个参数建议用<path:filename>这种转换器，能接住多级子路径，比如assets/images/marker-icon.png，而不是只匹配一层文件名。

4. 把本地化做成常态：函数封装、目录约定与包内文件的取舍

4.1 封装 localize_folium_html()，一次搞定重复劳动

每次手动跑一遍下载和替换，既慢又容易出错。更稳妥的做法是把这套流程封装成一个纯函数，输入folium渲染出的 HTML 字符串，输出本地化后的 HTML 字符串。这样 build 脚本、Flask 路由、定时任务都能复用同一个逻辑。

def localize_folium_html(html_text, asset_dir="assets"): os.makedirs(asset_dir, exist_ok=True) url_pattern = re.compile(r'(?:src|href)=["\'](https?://[^"\']+)["\']', re.IGNORECASE) external_urls = list(set(url_pattern.findall(html_text))) download_map = {} for url in external_urls: filename = urlparse(url).path.split("/")[-1] or "index.html" suffix = hashlib.md5(url.encode()).hexdigest()[:8] safe_name = f"{suffix}_{filename}" urllib.request.urlretrieve(url, os.path.join(asset_dir, safe_name)) download_map[url] = safe_name for url, safe_name in download_map.items(): html_text = html_text.replace(url, f"{asset_dir}/{safe_name}") css_pattern = re.compile(r'url\((["\']?)([^"\')]+)\1\)') for url, safe_name in download_map.items(): local_css = os.path.join(asset_dir, safe_name) if not local_css.endswith(".css"): continue with open(local_css, encoding="utf-8") as f: css_text = f.read() css_dir = os.path.dirname(local_css) base_url = url[: url.rfind("/") + 1] for quote, ref in css_pattern.findall(css_text): if ref.startswith(("data:", "http")): continue full_url = urljoin(base_url, ref) rel_path = urlparse(full_url).path.lstrip("/") target = os.path.join(asset_dir, rel_path) os.makedirs(os.path.dirname(target), exist_ok=True) urllib.request.urlretrieve(full_url, target) local_ref = os.path.relpath(target, css_dir) css_text = css_text.replace(f'url({quote}{ref}{quote})', f'url({local_ref})') with open(local_css, "w", encoding="utf-8") as f: f.write(css_text) return html_text

逻辑说明：这个函数把上一章的三步整合成了一个入口。调用方式很简单：html_text = localize_folium_html(root.render(), "assets")，然后写文件或交给 Flask。函数内部分三段：提取下载、替换主引用、修复 css 子资源。

参数说明：asset_dir是资源目录名，调用方可以根据项目结构调整。比如 Flask 项目里传"static/map_assets"，纯静态交付传"assets"。函数没有对下载做超时和重试处理，生产环境建议在urlretrieve外包一层重试逻辑，或者改用requests库统一管理会话。

4.2 前后端分离：资源目录与构建脚本约定

本地化不该是“今天想起来改一次”的手工操作，而应该变成可重复的构建步骤。我一般会把整个流程拆成三个固定角色：

map_project/ ├── build_map.py # 生成地图并调用 localize_folium_html() ├── assets/ # 下载好的 js/css/images，随版本库提交 └── output/ └── localized_map.html

build_map.py负责数据读取、地图要素添加、本地化输出；assets目录是固定的资源落盘位置；output放最终交付的 HTML。这样做的好处是，任何人拉下代码都能用同一条命令生成一模一样的产物，不再依赖某台机器上的 CDN 网络。对于完全隔离的内网环境，我建议把下载好的assets目录直接提交进版本库，避免上线时再下载一次。对于可以联网的测试环境，则可以每次构建时重新下载，确保资源版本是最新的。

目录约定上有个细节：不要把 HTML 和资源混在一个目录里。HTML 放在output，资源放在assets，两者保持固定的相对深度，这样无论是放到 Nginx 子目录还是打包发给别人，目录结构都不会散架。

4.3 慎改 folium 包内部文件的三个理由

有人会觉得：“既然 folium 的默认资源清单写在包内部，那我直接把 CDN 地址改成相对路径不就行了？”这在技术上确实可行，但我一直不建议这么做。

第一个理由是升级被覆盖。folium 一旦升级，你所改的源文件就会被新版本整个替换掉，本地化逻辑瞬间失效，而且没有任何报错，页面静默回归到在线引用。第二个理由是团队协作问题。你改了本机site-packages里的文件，同事的机器没改，同一份代码跑出两个不同的结果，问题极难排查。第三个理由是它破坏了库的抽象边界。folium 的资源清单属于库的内部实现，今天它是 CDN，明天它可能换成内联资源，你基于“改这个文件就能离线”的假设是很脆弱的。

正确做法是把本地化放在自己的业务代码层，也就是 4.1 的localize_folium_html()。这个问题上，我吃过亏：有段时间靠改包内文件让地图离线跑通了，结果一升级，所有页面重新拉外网，排查了半天才反应过来是覆盖问题。从此之后，凡是和库内部实现相关的改动，一律隔离在应用层。

5. folium 本地资源 5 个真实翻车现场与排查办法

5.1 改了 src 还是白屏：浏览器缓存不是程序问题

现象：替换完 src，重新打开页面，地图区域依然是空白的，控制台也没有明显 404。在无痕窗口里打开却一切正常。

原因：浏览器对外链资源做了强缓存，同一个 URL 在之前加载过，本地化后文件名没变，或者路径虽然变了但file://下浏览器仍按域名粒度缓存了早期失败的响应。尤其是通过 CDN 302 跳转过的资源，更容易踩中这个坑。

解决：先用无痕窗口排除缓存因素，再确认页面资源是否真的从本地加载。如果确认是缓存问题，可以在资源文件名里加入内容 hash，或者引用时加一个版本查询串，比如assets/leaflet.js?v=20250101。缓存是前端“玄学”里最常见的一种，碰到白屏优先怀疑它。

5.2 marker 图标消失：忽略了 CSS 的 images/ 子资源

现象：地图能拖动、缩放按钮也有，但默认的 marker 图标变成一个小方块，或者根本看不到。

原因：leaflet.css内部通过url(images/marker-icon.png)引用图标，CSS 下载到本地后，这个相对路径仍然指向 HTML 同级的images/目录，而这个目录并不存在。只下载 css 主文件、不下载 css 内部引用资源，就会出现这种“半离线”状态。

解决：重新执行 3.3 里的 css 子资源处理流程，把所有url(...)相对引用基于原来的 CDN 目录补全后下载到本地，并在 css 内容里替换成相对 css 文件的位置。验证时直接看assets目录下有没有images子目录，以及里面是否有marker-icon.png。这里的血泪经验是：不要只看 HTML 里的 src，CSS 里的 url 也是资源。

5.3 相对路径和绝对路径混用，部署子目录后 404

现象：本地打开正常，放到服务器的/report/子目录后，页面能打开，但所有资源 404。

原因：HTML 里既有assets/leaflet.js这种相对路径，又有/assets/leaflet.js这种以根路径开头的绝对路径。在子目录部署时，相对路径解析到/report/assets/...，绝对路径解析到/assets/...，两者指向不同位置，后者必然 404。

解决：明确你的部署基线。如果走file://或子目录，统一用相对路径；如果走域名根路径，统一用带/的绝对路径。不要混用。在 Flask 这类框架里，最稳的方式是用url_for('static', filename='...')动态生成路径，而不是在 HTML 字符串里写死。

5.4 下载器突然失败：CDN 链接更新，正则按老地址匹配

现象：构建脚本在同事机器上跑的时候，报HTTP Error 403或SSL: CERTIFICATE_VERIFY_FAILED，之前还正常的下载突然中断。

原因：folium 版本不同，内部使用的资源 URL 不同，导致正则提取到的地址列表发生变化；另外公网 CDN 可能对频繁下载做了防盗链或限流，403 就是这样来的。你的脚本本身没写错，错在假定 URL 永远不变。

解决：下载前先打印external_urls，人工核对一遍是否合理；下载异常时保留日志，不要静默跳过。更稳妥的做法是把assets目录提交进版本库，构建时先检查本地是否已存在目标文件，存在就直接用，不存在才触发下载。这样既省时间，又稳定复现。

5.5 notebook 里显示正常，独立 HTML 却异常：路径基准变了

现象：在 Jupyter Notebook 里用HTML(html_text)显示地图，一切正常；把同一个html_text写成文件放到服务器上，地图控件全部失效。

原因：notebook 渲染html_text时，相对路径是相对 Jupyter 服务根路径解析的，所以assets/xxx.js能找到。但独立 HTML 的文件系统路径和 Jupyter 的 URL 路径完全不同，浏览器找不到原来的相对位置。

解决：区分“notebook 临时看”和“生产环境交付”两种场景。notebook 里显示时，要么把资源目录放在 notebook 同级并调整相对路径，要么直接显示内联后的 HTML；生产交付必须走完整的本地化函数，并且基于实际部署位置重新计算路径。

6. 最后一步再进阶：Network 核验 + 把瓦片也纳入离线体系

本地化 js/css 只是离线化的一半。如果要在彻底断网的展厅或机房里演示，底图瓦片默认也会请求外网，页面会出现网格状灰底。常见做法是把标准 XYZ 瓦片目录直接交给内部静态服务器，目录结构按{z}/{x}/{y}.png组织，再通过TileLayer指向内网地址：

local_tiles = "http://内网瓦片服务地址/{z}/{x}/{y}.png" folium.TileLayer(tiles=local_tiles, attr="internal").add_to(m)

这样地图交互和底图渲染全部走内网，不再依赖任何公网请求。瓦片服务可以用开源的瓦片缓存工具搭建，也可以直接把离线打包的瓦片目录丢给 Nginx 托管。注意检查瓦片服务的Access-Control-Allow-Origin头，跨域问题在 Web 地图里很常见，配置不当会导致瓦片加载失败但 JS/CSS 全部正常，很容易误判成本地化不彻底。

核验这一步别只靠肉眼。把本地化后的 HTML 和assets目录传到目标环境的静态服务器上，打开开发者工具的 Network 面板，筛选 JS、CSS、Img 三类请求，确认域名列表里没有任何公网地址。然后切到离线模式再刷新一次，页面依然能渲染地图容器和控件，说明本地化彻底成功。如果只是临时交付，也可以直接用无痕窗口模拟干净缓存环境。

有个印象很深的教训：有一回我把map.html和assets放到内网文档系统里，同事反馈地图区域一片空白，控制台没有 404，排查两小时才发现文档服务把.js的 MIME 类型返回成了text/plain，浏览器拒绝执行脚本。从那以后我每次核验都会多看一眼响应头的Content-Type，确认是application/javascript而不是其他类型。这个细节不难，但足以让整页地图安静地“死掉”。希望帮到你。

本文还有配套的精品资源，点击获取