Jupyter Notebook运行代码无反应？GIS空间分析环境排查与修复详解（附：内核配置表）

wowwwai GIS研习社 · 工具流程与项目排障

如果你正在搜索“Jupyter Notebook运行代码无反应？GIS空间分析环境排查与修复详解（附：内核配置表）”，大概率遇到的是：单元格左侧一直显示 In [*]、点击运行没有输出、GeoPandas 或 ArcPy 代码卡住、地图可视化不显示，甚至 Notebook 页面看起来正常但内核已经失联。本文按 GIS 空间分析常见环境来排查，重点解决 Jupyter Notebook运行代码无反应、Jupyter内核无响应、GIS Python环境配置混乱、GeoPandas运行卡住、ArcPy Notebook无法执行等问题。

引言：GIS空间分析中为什么更容易遇到 Jupyter Notebook运行代码无反应

普通 Python 示例通常只依赖少量库，而 GIS 空间分析环境经常同时涉及 geopandas、shapely、fiona、pyproj、rasterio、gdal、arcpy、folium、ipyleaflet 等库。这些库背后还依赖 GEOS、PROJ、GDAL 等底层组件。

因此，Jupyter Notebook运行代码无反应并不一定是 Notebook 本身坏了。更常见的原因是内核选错、Conda 环境冲突、GIS 库二进制依赖不匹配、某段空间分析代码正在执行超大数据，或者地图渲染组件没有正确加载。

背景：先判断是真的卡死，还是 GIS 代码执行时间太长

很多同学看到 In [*] 就认为 Jupyter Notebook运行代码无反应，但在 GIS 场景里，部分操作本来就很耗时。例如读取几十万条面要素、做缓冲区叠加、重投影大栅格、对全量 GeoJSON 做空间连接，都可能让 Notebook 长时间没有输出。

建议先用一个最小测试单元判断内核是否还能工作：

print("kernel is alive")
1 + 1

如果这个单元也一直不返回，优先排查 Jupyter内核无响应或环境配置问题。如果这个单元能运行，而 GIS 代码无输出，则重点排查数据规模、空间索引、坐标系、文件路径和具体库的执行状态。

原理：Jupyter Notebook运行代码无反应的常见机制

Jupyter Notebook 的代码并不是在网页里直接执行。浏览器只是前端界面，真正执行代码的是后端 Python Kernel，也就是内核。你在单元格里点击运行后，请求会经过 Jupyter Server，再发送给当前选中的 Python 内核。

在 GIS Python环境中，内核还要加载大量本地动态库。例如 GeoPandas 需要调用 Shapely、Fiona、PyProj；Rasterio 和部分矢量读写依赖 GDAL；ArcPy 则依赖 ArcGIS Pro 自带的 Python 环境。任何一个环节不匹配，都可能导致内核启动慢、导入库时卡住、运行空间分析时无响应。

可以把问题分成五类：

• 前端问题：Notebook 页面假死、浏览器插件干扰、输出太大导致页面渲染卡顿。
• 内核问题：Python Kernel 未启动、内核崩溃、内核与 Notebook 连接断开。
• 环境问题：Conda 环境选错、包版本冲突、GDAL/PROJ/GEOS 依赖不一致。
• 代码问题：死循环、大数据全量计算、空间索引缺失、一次性输出过多对象。
• GIS软件集成问题：ArcPy 没在 ArcGIS Pro 对应环境中运行，或 QGIS/PyQGIS 环境变量未配置。

步骤：按顺序排查并修复 Jupyter Notebook运行代码无反应

步骤1：确认 Notebook 内核是否还活着

先不要急着重装环境。新建一个单元格，运行：

import sys
print(sys.executable)
print(sys.version)
print("ok")

如果没有任何输出，并且左侧一直是 In [*]，可以在菜单中选择重启内核，然后再次运行。若重启后仍无反应，关闭当前 Notebook 页面，回到启动 Jupyter 的终端，查看是否有错误日志。

重点观察这些信息：

• 是否出现 KernelRestarter、kernel died、DeadKernelError。
• 是否出现 DLL load failed、ImportError、ModuleNotFoundError。
• 是否在导入 geopandas、fiona、rasterio、arcpy 时停止。

步骤2：确认 Notebook 使用的是正确的 GIS Python环境

GIS 初学者最常见的问题是：在终端里安装了库，但 Notebook 选择的是另一个 Python 内核。此时看起来像 Jupyter Notebook运行代码无反应，实际是内核环境不一致或依赖加载失败。

在 Notebook 中运行：

import sys
print(sys.executable)

再在命令行中运行：

where python

如果你使用 macOS 或 Linux，则运行：

which python

两边路径应当指向同一个预期环境。例如 Conda 环境通常类似：

C:Users你的用户名miniconda3envsgispython.exe

如果路径不一致，需要把正确环境注册成 Jupyter 内核：

conda activate gis
python -m pip install ipykernel
python -m ipykernel install --user --name gis --display-name "Python GIS"

然后重新打开 Notebook，在内核列表里选择 Python GIS。

步骤3：用最小导入测试定位 GIS 库冲突

不要一上来运行完整空间分析脚本。建议按库逐个导入，定位到底是哪一个库导致无反应。

import pandas as pd
print("pandas ok")

import geopandas as gpd
print("geopandas ok")

import shapely
print("shapely ok")

import pyproj
print("pyproj ok")

import fiona
print("fiona ok")

如果卡在 import geopandas 或 import fiona，通常与 GDAL、Fiona、Shapely、PyProj 的二进制依赖有关。建议优先使用同一个渠道安装，不要混用过多来源。

Conda 环境中较稳妥的安装方式是：

conda create -n gis python=3.11
conda activate gis
conda install -c conda-forge geopandas rasterio jupyterlab ipykernel
python -m ipykernel install --user --name gis --display-name "Python GIS"

如果你已经在同一个环境里多次混用 pip install gdal、conda install 和不同渠道的包，修复成本可能比重建环境更高。GIS 环境建议尽量用 Conda Forge 保持依赖一致。

步骤4：检查是否是空间数据太大导致“看起来无反应”

有些代码不是坏了，而是真的在处理大量空间数据。比如：

gdf = gpd.read_file("large_buildings.geojson")
result = gpd.overlay(gdf, zones, how="intersection")

如果 large_buildings.geojson 很大，或者要素几何非常复杂，Notebook 可能长时间不输出。建议先检查数据量：

import geopandas as gpd

gdf = gpd.read_file("data.gpkg", rows=5)
print(gdf.head())
print(gdf.crs)

对于大数据，优先采用以下策略：

• 先用 rows=5 或小范围样本测试流程。
• 优先使用 GeoPackage、Parquet 等格式，少用超大 GeoJSON 直接分析。
• 在空间连接、裁剪、叠加前确认是否建立空间索引。
• 先统一坐标系，避免投影转换在循环中重复执行。
• 不要在 Notebook 中直接输出完整 GeoDataFrame。

步骤5：排查 GeoPandas运行卡住的典型代码

GeoPandas运行卡住常见于空间连接、叠加分析、缓冲区计算和坐标转换。可以加入分段输出，确认卡在哪一步：

import geopandas as gpd

print("reading data")
points = gpd.read_file("points.gpkg")

print("reading polygons")
polygons = gpd.read_file("polygons.gpkg")

print("checking crs")
print(points.crs, polygons.crs)

print("reprojecting")
polygons = polygons.to_crs(points.crs)

print("spatial join")
joined = gpd.sjoin(points, polygons, predicate="within")

print("done")
joined.head()

如果卡在 sjoin，检查是否安装空间索引相关依赖。在较新的 GeoPandas 环境中通常会使用 Shapely 的空间索引能力，但环境混乱时仍可能出现性能异常。可以先确认版本：

import geopandas as gpd
import shapely

print(gpd.__version__)
print(shapely.__version__)

步骤6：ArcPy Notebook无法执行时，优先检查内核来源

ArcPy 不是普通 pip 包，通常随 ArcGIS Pro 一起安装。ArcPy Notebook无法执行时，不要在普通 Conda 环境里直接 pip install arcpy。正确思路是使用 ArcGIS Pro 自带或克隆的 Python 环境。

在 Notebook 中测试：

import sys
print(sys.executable)

import arcpy
print(arcpy.GetInstallInfo())

如果 import arcpy 报错或卡住，检查当前内核是否来自 ArcGIS Pro 的 Python 环境。通常需要在 ArcGIS Pro 的 Python Command Prompt 中注册内核：

python -m pip install ipykernel
python -m ipykernel install --user --name arcgispro-py3 --display-name "ArcGIS Pro Python"

然后在 Jupyter Notebook 中选择 ArcGIS Pro Python 内核。若公司电脑有权限限制，还要确认 ArcGIS Pro 许可、安装路径和用户目录写入权限。

步骤7：清理过大的输出，避免前端页面卡死

有时内核已经执行完，但 Notebook 前端因为输出太大而卡住。GIS 中常见触发方式包括：直接显示几十万行属性表、输出超长 GeoJSON、在循环里反复打印要素对象、生成过大的交互式地图。

建议避免：

print(gdf)
gdf.to_json()

改成：

print(gdf.shape)
print(gdf.columns)
gdf.head()

如果 Notebook 已经因为输出过大打不开，可以用文本编辑器或命令行清理输出，也可以在 JupyterLab 中尝试打开后选择清除所有输出。

步骤8：检查 Jupyter 服务端与浏览器状态

如果所有 Notebook 都无反应，可能是 Jupyter Server 本身异常。关闭浏览器标签页并不等于关闭服务端。建议回到启动 Jupyter 的终端，按 Ctrl+C 停止服务，再重新启动：

jupyter notebook

或使用：

jupyter lab

如果浏览器页面异常，可以尝试：

• 强制刷新页面。
• 换用无痕窗口。
• 临时关闭浏览器插件。
• 复制 Notebook 文件到新目录再打开。
• 检查端口是否被代理、杀毒软件或公司安全软件拦截。

常见坑：这些操作最容易把 GIS Notebook 环境搞乱

• 在 base 环境里安装所有 GIS 库：base 环境越复杂，越容易出现依赖冲突。建议为 GIS 项目单独建环境。
• Conda 和 pip 随意混用：不是不能混用，而是 GDAL、Rasterio、Fiona 这类库尽量统一来源。
• Notebook 内核和终端环境不是同一个：终端能运行，不代表 Notebook 能运行。
• 直接处理超大 GeoJSON：GeoJSON 适合交换，不一定适合大规模分析。
• 忽略坐标系：空间连接、缓冲区、面积计算前不检查 CRS，可能既慢又错。
• 一次性显示完整地图或完整属性表：输出太大可能导致前端假死。
• 在普通环境里调用 ArcPy：ArcPy 应使用 ArcGIS Pro 对应 Python 环境。

方法比较：不同修复方式适合什么情况

现象	优先判断	推荐处理	适用场景
所有单元格都显示 In [*]	Jupyter内核无响应	重启内核，查看终端日志，重新选择内核	Notebook 突然失联或内核崩溃
普通代码能跑，导入 GeoPandas 卡住	GIS Python环境依赖冲突	用 Conda Forge 重建干净环境	GDAL、Fiona、Shapely、PyProj 版本混乱
读取文件后长期无输出	数据量或格式问题	先读样本，换 GeoPackage 或 Parquet，减少字段和范围	超大 GeoJSON、复杂面数据、大栅格
空间连接或叠加特别慢	空间索引、坐标系、几何复杂度	检查 CRS，简化几何，分块处理，确认空间索引	GeoPandas 空间分析性能问题
ArcPy 导入失败或无反应	内核不是 ArcGIS Pro Python	使用 ArcGIS Pro Python 注册 ipykernel	ArcPy Notebook无法执行
运行完成但页面卡死	输出过大或前端渲染过重	清除输出，避免打印完整数据，限制地图图层数量	大表格、大 GeoJSON、交互式 WebGIS 地图

检查清单：GIS空间分析内核配置表

检查项	命令或位置	正常结果	异常处理
当前 Python 路径	import sys; print(sys.executable)	指向预期 Conda 或 ArcGIS Pro 环境	重新选择内核或注册 ipykernel
Jupyter 内核列表	jupyter kernelspec list	包含你的 GIS 环境名称	在目标环境中安装并注册 ipykernel
GeoPandas 是否可导入	import geopandas as gpd	快速返回无报错	检查 GDAL、Fiona、Shapely、PyProj 依赖
ArcPy 是否可导入	import arcpy	在 ArcGIS Pro Python 内核中正常导入	切换到 ArcGIS Pro 环境，不要使用普通 Python
空间数据规模	gdf.shape	数据量与机器配置匹配	抽样、分块、换格式、减少字段
坐标系	gdf.crs	参与分析的数据 CRS 一致	使用 to_crs 统一坐标系
输出大小	gdf.head()	只预览少量记录	避免直接打印完整 GeoDataFrame 或 GeoJSON

FAQ：Jupyter Notebook运行代码无反应常见问题

Q1：为什么单元格一直是 In [*]，但没有任何报错？

这通常表示内核正在执行、卡住或已经失联。先运行最小测试代码 print("ok")。如果也无输出，就是 Jupyter内核无响应；如果能输出，则说明具体 GIS 代码耗时或阻塞。

Q2：为什么终端里能导入 GeoPandas，Notebook 里却无反应？

最常见原因是 Notebook 使用的内核不是你在终端中激活的环境。用 sys.executable 对比路径，并把正确的 GIS Python环境注册为 Jupyter 内核。

Q3：GeoPandas运行卡住一定是包安装坏了吗？

不一定。GeoPandas运行卡住可能是环境冲突，也可能是数据太大、几何过复杂、空间索引不可用、坐标系转换耗时。建议先用小样本和分段打印定位。

Q4：ArcPy Notebook无法执行，应该重装 Jupyter 吗？

通常不需要先重装 Jupyter。ArcPy Notebook无法执行的核心是内核必须来自 ArcGIS Pro 对应 Python 环境。先在 ArcGIS Pro Python 环境中注册 ipykernel，再在 Notebook 里选择该内核。

Q5：我应该用 Jupyter Notebook 还是 JupyterLab 做 GIS 分析？

两者都可以。Notebook 更简单，JupyterLab 文件管理和多标签体验更好。真正影响稳定性的不是界面，而是内核、Python 环境、GIS 库依赖和数据规模。

Q6：重启内核会不会丢失数据？

会丢失当前内存中的变量和中间结果，但不会删除磁盘上的 Notebook 文件和数据文件。长流程 GIS 分析建议把关键结果及时写入 GeoPackage、Parquet、CSV 或数据库。

Q7：为什么交互式地图不显示，看起来像代码无反应？

如果使用 Folium、ipyleaflet 或其他 WebGIS 组件，可能是前端扩展、浏览器安全策略、地图瓦片网络或输出体积导致显示异常。先保存为 HTML 或减少图层数量测试。

结论：先定位内核，再定位环境，最后优化 GIS 数据流程

Jupyter Notebook运行代码无反应不要一开始就重装软件。更稳妥的顺序是：先用最小代码确认 Jupyter内核无响应还是单段 GIS 代码耗时；再核对 Notebook 使用的 GIS Python环境；然后逐个导入 GeoPandas、Rasterio、ArcPy 等库定位依赖问题；最后检查数据规模、空间索引、坐标系和输出量。

对于 GIS 学习和项目实践，建议为每类工作流建立独立环境：一个 GeoPandas 环境、一个 Rasterio/GDAL 栅格环境、一个 ArcGIS Pro ArcPy 环境。环境清晰之后，Jupyter Notebook 才能稳定地服务于空间分析，而不是变成排错现场。