Jupyter Notebook导出PDF总是失败？GIS图表如何完美转换？附：环境配置与报错修复技巧！
Jupyter Notebook导出PDF总是失败？GIS图表如何完美转换？附：环境配置与报错修复技巧！如果你在做 GIS 数据分析报告时，Notebook 里有地图、坐标轴、中文标注、GeoPandas 图表或 Rasterio 结果图，导出 PDF 失败往往不是 Notebook 本身的问题，而是 LaTeX、浏览器渲染、字体、图片路径和地理图表输出格式共同造成的。
引言：为什么 GIS Notebook 导出 PDF 更容易失败
普通数据分析 Notebook 通常只有表格和折线图，而 GIS Notebook 经常包含矢量边界、栅格影像、底图瓦片、中文地图标题、投影信息和大尺寸图片。这些内容在 Jupyter Notebook 导出 PDF 时，会经过 HTML、LaTeX 或浏览器打印等不同链路，任何一个环节缺少依赖，都可能导致导出中断。
本文以 GIS 学习和工作中最常见的场景为主，讲清楚三件事：
- Jupyter Notebook 导出 PDF 失败通常发生在哪个环节。
- GIS 图表如何更稳定地转换为 PDF。
- 如何配置环境并修复常见报错，例如 Pandoc、XeLaTeX、中文字体、图片路径和地图显示异常。
背景：Jupyter Notebook 导出 PDF 的三条常用路径
在实际项目中，Jupyter Notebook 导出 PDF 主要有三种方法。理解这三条路径，可以快速判断报错应该从哪里查。
路径一：通过 LaTeX 导出 PDF
这是 Jupyter Notebook 传统的 PDF 导出方式。Notebook 会先通过 nbconvert 转成 LaTeX 文件，再调用 XeLaTeX 或其他 LaTeX 引擎生成 PDF。
这种方式适合排版正式、需要目录和公式的报告，但对环境依赖最重。只要系统缺少 Pandoc、TeX Live、MiKTeX、XeLaTeX 或中文字体配置，就可能失败。
路径二：先导出 HTML，再用浏览器打印为 PDF
这是对 GIS 图表最友好的方式之一。Notebook 先导出为 HTML，浏览器负责渲染页面，再通过“打印为 PDF”生成文件。
它对中文、地图截图、Matplotlib 图表和 Folium 静态页面的兼容性通常更好，适合大多数课程作业、项目汇报和快速交付。
路径三：直接在代码中保存图表，再手工整合 PDF
如果 Notebook 里包含高分辨率地图、专题图或遥感影像，推荐先把 GIS 图表导出为 PNG、SVG 或 PDF，再放进报告模板中。这种方法更可控，尤其适合 ArcGIS Pro、QGIS、GeoPandas 和 Matplotlib 混合使用的工作流。
原理：为什么 GIS 图表导出 PDF 会报错
Jupyter Notebook 导出 PDF 失败，本质上通常不是“导出按钮坏了”，而是以下几个对象在转换过程中不能被正确处理。
1. 中文字体无法被 LaTeX 或 Matplotlib 正确识别
GIS 图表里经常有中文标题、图例、行政区名称和坐标轴说明。如果 LaTeX 找不到中文字体，可能出现类似报错：
! LaTeX Error: File `ctex.sty' not found.
! Package fontspec Error: The font "SimHei" cannot be found.
Unicode character 未 set up for use with LaTeX.即使导出成功，也可能出现中文乱码、方框字或文字缺失。
2. Notebook 中的地图不是静态图片
Folium、Leaflet、ipyleaflet、Kepler.gl 等 WebGIS 地图在 Notebook 中通常依赖 HTML、JavaScript 和在线瓦片服务。LaTeX 导出 PDF 时并不会完整执行这些交互式脚本，因此地图可能空白。
如果你看到 Notebook 中地图正常，但导出的 PDF 里地图消失，优先怀疑这一点。
3. 图片路径或工作目录不一致
GIS 分析经常会把中间图表保存到本地文件，例如：
fig.savefig("outputs/map.png", dpi=300)如果 Notebook 导出时的工作目录不同，或者图片使用了相对路径但文件没有被正确引用，PDF 中就可能出现图片丢失。
4. 图幅过大或栅格分辨率过高
遥感影像、DEM 阴影图、土地利用栅格图可能尺寸很大。导出 PDF 时，如果图片分辨率过高，可能导致内存占用过大、导出卡住，或者 PDF 文件异常膨胀。
5. 环境中缺少 Pandoc、TeX 或浏览器组件
Jupyter 的 PDF 导出并不是单独完成的。常见依赖包括 nbconvert、Pandoc、TeX Live 或 MiKTeX。如果缺失其中一个组件，就会出现导出失败。
步骤：推荐的 GIS Notebook 转 PDF 稳定流程
步骤一：先确认你使用的是哪种导出方式
在 Notebook 菜单中，如果你选择的是类似“Download as PDF via LaTeX”，就会进入 LaTeX 路径。如果选择“Export Notebook As HTML”，再用浏览器打印，则是 HTML 路径。
对大多数 GIS 图表，建议优先使用下面的顺序：
- Notebook 中把地图和图表保存为静态图片。
- 导出 Notebook 为 HTML。
- 用 Chrome、Edge 或系统浏览器打印为 PDF。
- 如果必须使用 LaTeX，再配置 XeLaTeX 和中文字体。
步骤二：更新并检查 nbconvert
先在当前 Python 环境中检查 Jupyter 和 nbconvert 是否可用：
jupyter --version
jupyter nbconvert --version如果命令不存在，说明当前环境没有正确安装 Jupyter 或 nbconvert。可使用以下命令安装：
pip install notebook nbconvert如果你使用 Conda 环境，建议在对应环境中安装：
conda install notebook nbconvert注意：一定要在运行 Notebook 的同一个环境中执行安装命令。很多导出失败来自“浏览器里运行的是一个环境，命令行安装的是另一个环境”。
步骤三：优先导出 HTML 再打印 PDF
对包含 GeoPandas、Matplotlib、Rasterio、Folium 的 GIS Notebook，最稳妥的方式是先导出 HTML：
jupyter nbconvert --to html your_notebook.ipynb然后用浏览器打开生成的 HTML 文件，选择打印，目标打印机选择“另存为 PDF”。
这样做的好处是：
- HTML 对中文字体的兼容性通常比 LaTeX 更好。
- Matplotlib 静态图、表格和代码输出更容易保留原样。
- Folium 这类 WebGIS 地图在 HTML 中更容易显示。
- 排查问题更直观，可以先看 HTML 是否正常。
步骤四：把 GIS 图表显式保存为静态图片
如果你的 Notebook 中有 GeoPandas 绘图，建议不要只依赖单元格显示结果，而是显式保存图片。
import geopandas as gpd
import matplotlib.pyplot as plt
gdf = gpd.read_file("data/city_boundary.shp")
fig, ax = plt.subplots(figsize=(8, 6))
gdf.plot(ax=ax, edgecolor="black", facecolor="#d9f0d3")
ax.set_title("研究区边界图")
ax.set_axis_off()
plt.tight_layout()
fig.savefig("outputs/city_boundary_map.png", dpi=300, bbox_inches="tight")
plt.show()对于论文、课程报告或正式汇报，建议地图图片使用 300 dpi。对于包含大量栅格的图，如果文件太大，可以先使用 150 到 200 dpi 测试。
步骤五：处理 Matplotlib 中文字体
如果 GIS 图表中包含中文标题、图例或标注，可以在 Notebook 开头设置字体：
import matplotlib.pyplot as plt
plt.rcParams["font.sans-serif"] = ["SimHei", "Microsoft YaHei", "Arial Unicode MS"]
plt.rcParams["axes.unicode_minus"] = False不同系统的字体名称不同。Windows 常见字体包括 SimHei 和 Microsoft YaHei；macOS 可尝试 Arial Unicode MS；Linux 服务器建议安装 Noto Sans CJK。
如果导出后的 PDF 中文仍然乱码，建议先确认图表是否已经被保存为 PNG。如果中文文字已经嵌入图片，浏览器打印 PDF 时通常不会再丢失中文。
步骤六：Folium 地图先保存为 HTML，再截图或嵌入
Folium 地图属于 WebGIS 地图，底层依赖 Leaflet 和网页渲染。直接走 LaTeX 导出时，很容易变成空白。
推荐做法是先保存地图 HTML：
import folium
m = folium.Map(location=[31.23, 121.47], zoom_start=10)
folium.Marker([31.23, 121.47], popup="上海中心点").add_to(m)
m.save("outputs/folium_map.html")然后用浏览器打开该 HTML，确认底图和标记正常显示。最终报告中可以使用截图，也可以把 Notebook 导出为 HTML 后再打印 PDF。
如果你的报告必须离线查看，注意在线瓦片底图可能无法加载。此时应提前截图，或使用本地瓦片、静态地图图片。
步骤七：如果必须使用 LaTeX 导出 PDF，安装完整依赖
如果你需要通过 LaTeX 获得更正式的 PDF 排版，需要安装 Pandoc 和 TeX 发行版。
Windows 用户通常可以安装 MiKTeX 或 TeX Live；macOS 用户可安装 MacTeX；Linux 用户可安装 TeX Live。
安装后检查命令：
pandoc --version
xelatex --version再执行：
jupyter nbconvert --to pdf your_notebook.ipynb如果 Notebook 中有中文，建议优先使用 XeLaTeX，因为它对 Unicode 和系统字体支持更好。
步骤八：清理输出单元，降低导出失败概率
GIS Notebook 中的输出单元可能包含大量 GeoDataFrame 表格、影像数组、长日志或交互式控件。导出前建议做一次清理。
- 删除不必要的大表格输出。
- 避免直接显示大型 NumPy 数组。
- 把地图结果保存为图片，只保留必要展示。
- 确认所有文件路径使用相对项目路径或绝对路径。
- 重新运行全部单元格，确保 Notebook 从头到尾可复现。
常见坑：Jupyter Notebook 导出 PDF 报错修复
报错一：Pandoc was not found
含义是 nbconvert 找不到 Pandoc。解决方法是安装 Pandoc，并确保命令行可以识别。
pandoc --version如果命令不可用，说明 Pandoc 没有安装，或者安装后没有加入系统 PATH。安装完成后重启终端、Jupyter Lab 或 Jupyter Notebook 服务。
报错二：xelatex not found on PATH
这说明系统没有安装 XeLaTeX，或者 TeX 的可执行文件路径没有加入 PATH。
解决步骤：
- 安装 TeX Live、MiKTeX 或 MacTeX。
- 重启命令行窗口。
- 执行
xelatex --version检查是否可用。 - 再执行
jupyter nbconvert --to pdf your_notebook.ipynb。
报错三：LaTeX Error: File ctex.sty not found
这是中文 LaTeX 宏包缺失。对于中文 GIS 报告，ctex 很常见。如果使用 TeX Live，需要安装相关中文语言包；如果使用 MiKTeX，可以让它自动安装缺失包。
如果你只是想快速得到 PDF，不建议继续纠结 LaTeX 包。更高效的方法是导出 HTML，再浏览器打印为 PDF。
报错四：导出的 PDF 中地图空白
地图空白通常出现在 Folium、Leaflet、ipyleaflet 或在线底图场景中。原因是 PDF 导出过程没有执行网页交互逻辑，或没有访问外网瓦片。
修复建议：
- 先将地图导出为 HTML，确认浏览器中是否正常。
- 需要 PDF 时，把地图截图为 PNG 后插入 Notebook。
- 检查网络是否能访问底图瓦片服务。
- 避免在最终 PDF 中依赖动态 JavaScript 地图。
报错五：中文显示为方框或乱码
这通常是字体问题。请先在 Matplotlib 中设置中文字体，并把图表保存成图片。如果仍然乱码，检查系统是否真正安装了对应字体。
import matplotlib.font_manager as fm
for font in fm.fontManager.ttflist:
if "Hei" in font.name or "YaHei" in font.name or "Noto" in font.name:
print(font.name)如果输出为空，说明 Python 没有找到可用中文字体。此时需要安装字体，或者改用系统已有字体。
报错六：PDF 文件巨大或导出卡死
这在遥感影像、地形图、栅格分类图中很常见。原因通常是图片分辨率过高，或者 Notebook 中保留了大量中间结果。
可按以下方式处理：
- 把超大图缩放后再导出。
- 保存图片时先尝试
dpi=150或dpi=200。 - 避免在 Notebook 中直接输出完整栅格数组。
- 导出前清空不必要输出。
- 如果是制图成果，优先用 QGIS 或 ArcGIS Pro 专门出图。
方法比较：哪种 GIS 图表转换 PDF 方式最适合你
| 方法 | 适合场景 | 优点 | 限制 |
|---|---|---|---|
| Notebook 直接导出 PDF via LaTeX | 公式多、排版正式、需要自动化批量报告 | 结构规范，适合技术报告模板 | 依赖 Pandoc、XeLaTeX、字体和 LaTeX 包，中文配置较麻烦 |
| 先导出 HTML，再浏览器打印 PDF | GIS 作业、项目汇报、包含地图和中文图表 | 兼容性好，排查直观，对 WebGIS 地图更友好 | 排版精细度不如 LaTeX，打印样式需要人工检查 |
| 图表先保存为 PNG 或 SVG，再整合报告 | 专题地图、遥感图、正式制图成果 | 图面稳定，可控制分辨率和字体 | 流程多一步，不适合频繁修改 |
| QGIS 或 ArcGIS Pro 专门出图，再插入报告 | 需要标准制图、比例尺、指北针、图例和版式 | 制图质量最高，符号化和版式控制强 | 不如 Notebook 自动化，数据分析过程需要另行记录 |
对于大多数 GIS 学生和初级 GIS 工程师，推荐采用“Notebook 分析过程 + 静态地图图片 + HTML 打印 PDF”的组合。它兼顾可复现、中文兼容和实际交付效率。
检查清单：导出前逐项确认
在点击导出 PDF 之前，建议按下面的清单检查一次。很多问题不需要等报错后再修。
- 环境检查：当前 Notebook 内核是否就是安装 nbconvert 的 Python 环境。
- 依赖检查：如果使用 LaTeX 路径，是否能执行
pandoc --version和xelatex --version。 - 字体检查：Matplotlib 是否设置了可用中文字体。
- 地图检查：Folium、Leaflet、ipyleaflet 地图是否已经保存为 HTML 或截图。
- 图片检查：所有地图图片是否能在文件夹中直接打开。
- 路径检查：图片和数据路径是否相对于 Notebook 文件位置正确。
- 大小检查：栅格图、DEM 图、遥感图是否过大。
- 输出检查：是否清理了无关日志、大数组和过长表格。
- 复现检查：是否从头运行全部单元格且没有报错。
- 最终检查：先导出 HTML，确认页面正常后再打印 PDF。
FAQ：Jupyter Notebook 导出 PDF 与 GIS 图表常见问题
Jupyter Notebook 导出 PDF 失败，最快的解决办法是什么？
最快办法是不要先走 LaTeX。先执行 jupyter nbconvert --to html your_notebook.ipynb，导出 HTML 后用浏览器打印为 PDF。对于包含 GIS 图表、中文标注和 WebGIS 地图的 Notebook，这通常比直接导出 PDF 更稳定。
为什么 Notebook 里 Folium 地图能显示，PDF 里却是空白？
Folium 地图依赖 HTML、JavaScript 和瓦片服务。LaTeX 导出 PDF 时不会像浏览器一样完整渲染交互式地图，所以容易空白。建议将 Folium 地图保存为 HTML，再截图成 PNG，或直接使用 HTML 打印 PDF。
GeoPandas 绘制的地图导出 PDF 后中文乱码怎么办？
先在 Matplotlib 中设置中文字体，例如 SimHei、Microsoft YaHei 或 Noto Sans CJK。然后使用 fig.savefig() 把地图保存成 PNG。只要图片中的中文显示正常，再导入 PDF 时就不容易乱码。
是否必须安装 TeX Live 才能导出 PDF？
不是。只有使用“PDF via LaTeX”路径时才需要 TeX Live、MiKTeX 或 MacTeX。如果你选择先导出 HTML 再浏览器打印 PDF，通常不需要安装完整 LaTeX 环境。
GIS 图表应该保存为 PNG、SVG 还是 PDF？
如果是普通报告和课程作业，PNG 最稳妥；如果是矢量边界、线划图和需要后期排版的图，SVG 更清晰；如果是正式论文插图，也可以把 Matplotlib 图直接保存为 PDF。包含遥感影像和栅格底图时，PNG 通常更合适。
为什么导出的 PDF 文件特别大？
通常是因为 Notebook 中包含高分辨率栅格图、遥感影像或过多输出。可以降低图片 dpi，裁剪研究区范围，清理无关输出，并避免直接输出大型数组。
ArcGIS Pro 或 QGIS 的地图能不能放进 Notebook 再导出 PDF？
可以，但建议先在 ArcGIS Pro 或 QGIS 中完成标准制图，导出为 PNG、SVG 或 PDF，再插入 Notebook。Notebook 更适合展示分析过程和代码，专业版式制图仍然建议交给 GIS 桌面软件完成。
结论：GIS Notebook 转 PDF 的最佳实践
Jupyter Notebook 导出 PDF 失败时，不要只盯着“导出按钮”。对 GIS 场景来说，真正需要检查的是导出链路、中文字体、WebGIS 地图、图片路径和栅格图大小。
如果你只是要提交 GIS 作业、项目分析记录或技术汇报，推荐采用“图表静态化、导出 HTML、浏览器打印 PDF”的流程。它对 GeoPandas 图表、Matplotlib 中文标注、Folium 地图截图和栅格结果图都更稳定。
如果你需要严格排版、批量生成正式报告，再考虑配置 Pandoc、XeLaTeX 和中文 LaTeX 环境。无论选择哪条路线，先保证 Notebook 从头到尾可复现，并把关键 GIS 图表保存为独立图片，才是避免 PDF 导出失败的核心。