企业官网建设流程全解析

搞数据分析、做算法实验、写教学课件，我几乎天天都在打开Jupyter Notebook。它对数据科学的意义，就像 Word 对文员一样——不是花哨，而是刚需。但就是因为太常用，很多人在最开始的安装环节就被卡住了，而且卡住的方式五花八门：有安装到一半报subprocess-exited-with-error的，有装完打不开的，有打开之后侧边怎么都调不出标题总览的。

这篇教程就是冲着这些坑来的。我会从零开始，把Jupyter Notebook的安装、启动、配置、排障完整走一遍，尽量做到保姆级。新手可以按步骤照做，老手也可以直接跳到第 3 节和第 5 节看报错处理——那几段是我把这两年给同事、学员解决问题时最常遇到的情况整理出来的，基本覆盖了安装和使用阶段 80% 以上的问题。

1. 安装前先搞懂这三件事，后面能少走很多弯路

1.1 Jupyter Notebook到底是什么

一句话版本：Jupyter Notebook是一个基于 Web 浏览器的交互式开发环境，你可以在网页里直接写代码、运行代码、看结果，还能把 Markdown 说明文字、图片、公式和图表混排在同一份文档里。

它的名字也很有意思：Ju来自 Julia，Py来自 Python，R来自 R，意思是它一开始就奔着多语言支持去的。不过绝大多数人用它来写 Python，数据分析、机器学习、教学演示、论文复现，这套工具几乎是行业默认标准。

很多人容易把它和JupyterLab搞混。简单说，JupyterLab是新一代的界面，更像一个 IDE，可以多标签页操作、拖拽文件、并排预览。而Jupyter Notebook是经典的单文档界面。我用下来最大的感受是：如果你只是写 Python 脚本、做数据探索，经典版完全够用；但如果你要同时开好几个 .ipynb 来回对比，JupyterLab会更顺手。本教程的核心是经典版 Notebook，但第 4 节我会把两种界面下如何调出标题总览都讲一遍。

1.2 三个核心概念：内核、服务器、前端页面

这个必须说清楚。很多人装完Jupyter Notebook后遇到“打不开”“运行不了代码”“内核一直转圈”这类问题，本质上就是没搞懂这三个组件之间的关系。

内核（Kernel）：真正执行代码的 Python 进程。你点击“运行”按钮，代码不是在你的浏览器里跑的，而是被发送到服务器，再由服务器交给内核去执行，最后把结果显示在页面上。

服务器（Notebook Server）：一个在本机后台运行的进程，负责管理内核、保存文件、提供 Web 服务。你启动jupyter notebook之后，命令行窗口会显示一些日志，那个进程就是服务器。如果你不小心把那个黑窗口关掉了，浏览器里的页面就会断连。

前端页面（Client）：就是浏览器里那个可交互的页面。它负责把代码展示给你，收集你的操作，再把结果渲染出来。

这三者全部就绪，才能真正跑起来一个 Notebook。所以排查问题的时候，顺序一般是：浏览器页面能不能打开 → Server 有没有报错 → Kernel 有没有启动。这个思路我在第 5 节会反复用到。

1.3 安装方案怎么选：Anaconda、pip还是VS Code

聊安装之前，必须先回答一个终极问题：到底用哪种方式装？

我把主流方案放一张表里，你可以对着自己的情况选：

我的建议非常明确：如果你是第一次接触 Jupyter Notebook，或者你连 Python 环境都还没配好，直接用 Anaconda。别听别人说“Anaconda 太臃肿”就犹豫——臃肿是事实，但对新手来说，它能帮你把 90% 的环境问题焊死。等以后你熟练了，觉得 Anaconda 太重、启动太慢，再自己折腾 pip 方案完全来得及。

2. 保姆级安装：两个方案从零跑通

2.1 方案一：Anaconda一键安装，新手最省心

整个 Anaconda 安装过程其实就是“下一步下一步”，但有几个关键点我必须提前提醒，因为这些位置最容易踩坑。

第一步，去官网下载安装包。地址是https://www.anaconda.com/download，页面会自动检测你的操作系统，选对版本下载就行。注意认准 Python 3.x 版本那个 Installer，不要下载到旧版本。下载慢的话可以用镜像站，这个后面再细说。

第二步，双击安装包开始安装。这一步有三个地方要仔细看：

安装路径不能有中文、不能有空格，不要装在系统盘 C 盘根目录的 Program Files 下面。我见过太多人因为默认路径里带了空格，后面装包怎么装怎么报错。建议直接装到D:\Anaconda这种干净路径。说起来有点玄，但这类环境类工具对路径字符真的很敏感，很多时候报错看着是包的问题，一排查根因其实是路径乱了。

第三步，安装到下面这个界面时，有一个选项是问你要不要添加到 PATH。Anaconda 官方默认不推荐勾选，但如果你以后想在 CMD 或 PowerShell 里直接敲conda或jupyter命令，不勾选会比较麻烦。我的做法是：新手不勾选，老老实实用 Anaconda Prompt 干活；如果你确定自己需要全局命令，可以勾上，但勾选后很可能和系统原本的 Python 产生路径冲突。两者选一个，别纠结。

第四步，安装完成后，打开开始菜单，找到Anaconda Prompt，这是 Anaconda 自带的命令行环境，所有命令都建议在这里敲。

输入以下命令验证一下：

conda --version

如果输出了类似conda 24.x.x的版本号，就说明装好了。接着启动 Notebook 非常直接：

jupyter notebook

命令执行后，默认浏览器会自动打开一个页面，地址通常是http://localhost:8888/tree。看到这个页面，你的Jupyter Notebook就正式跑起来了。想新建文件的话，点右上角的New，选择 Python 3 就新建了一个 notebook。

装 Anaconda 的时候，它默认会装好jupyter和notebook这两个核心包，所以理论上不用再额外操作。如果哪天你发现启动时报找不到模块，可以补装一下：

conda install notebook

这条命令用的是 conda 的包管理器，它最大的好处是会帮你检查依赖关系，一般不会出现 pip 那种依赖打架的问题。

2.2 方案二：pip最小安装，轻量也够用

如果你电脑上已经有 Python 环境，而且不想为了 Notebook 专门装一个 5GB 的 Anaconda，那用 pip 来装是更优雅的选择。

先确认自己的 Python 和 pip 可用：

python --version pip --version

然后安装 Notebook 本体：

pip install notebook

安装完成后，在同一命令行窗口直接执行：

python -m notebook

注意我在这里用的是python -m notebook，而不是直接敲jupyter notebook。加-m的意思是让 Python 解释器去运行 notebook 模块，好处是可以避免一些 PATH 配置问题。如果你安装时遇到过jupyter: command not found，用这个方式能救急。

如果你的机器上同时有 Python 2 和 Python 3，或者装了多个 Python 版本，那更要用这种方式，并且最好配合虚拟环境使用：

python -m venv myenv myenv\Scripts\activate # Windows source myenv/bin/activate # macOS / Linux pip install notebook python -m notebook

用虚拟环境的含义是给当前项目建一个独立的 Python 房间，所有依赖都装在这个房间里，互不污染。这个习惯值得从第一天就养成。

pip 方案在安装时最常见的报错就是subprocess-exited-with-error，这个我留到第 3 节专门讲，因为它涉及的原因比较多，值得单独开一章。

2.3 目录安装：在指定文件夹下启动Notebook

“目录安装”这个说法其实不太准确，它想表达的意思通常是：我不想每次打开 Jupyter 都默认跑到用户主目录，我想在项目文件夹里直接启动它。这个需求太常见了，我给三种方式。

第一种，先切目录，再启动。在命令行里先手动切到目标目录：

cd D:\my_projects\data_analysis jupyter notebook

每次启动前都要切一次，虽然不麻烦，但容易忘。而且如果忘了，打开页面后看到一堆不属于当前项目的旧文件，还得找半天。

第二种，直接用参数指定目录。不需要先 cd，直接：

jupyter notebook --notebook-dir=D:\my_projects\data_analysis

这个方式适合偶尔指定目录的人，写起来稍微长一点，但一次到位。

第三种，改配置文件，一劳永逸。先执行一次初始化配置：

jupyter notebook --generate-config

这样会在用户目录下的.jupyter文件夹里生成一个jupyter_notebook_config.py文件。用文本编辑器打开它，找到这一行：

# c.ServerApp.notebook_dir = ''

把它改成：

c.ServerApp.notebook_dir = 'D:/my_projects/data_analysis'

注意旧版本里这行配置叫c.NotebookApp.notebook_dir，如果你是老版本，改那个名字。改完保存，以后每次执行jupyter notebook，都会默认打开这个目录。

这里有个小细节：配置里目录路径要用正斜杠/，Windows 下反斜杠容易触发转义问题。我吃过一次亏，写的是D:\my_projects，结果启动时直接报错找不到路径，改成D:/my_projects就好了。

2.4 装完怎么确认没问题

很多新手装完就急着写代码，结果写到一半才发现环境有问题。我建议装完后按下面这组命令快速体检一遍：

conda list | grep notebook # 查看 notebook 包版本 # 或者 pip show notebook jupyter --version # 查看 Jupyter 相关组件版本 jupyter notebook list # 查看当前正在运行的 notebook 服务器

jupyter --version会输出一长串信息，包括jupyter_core、notebook、ipython等组件的版本号，看到这些就说明装得是完整的。jupyter notebook list则是检查当前有没有已经在跑的服务器，如果你之前启动过 Notebook 但浏览器关掉了，可以用它找回来。

还有个非常实用的验证方法：新建一个 Notebook，选 Python 3 内核，然后在第一个单元格里输入：

import sys print(sys.executable)

运行后如果能看到一个 Python 可执行文件的路径，说明内核已经正确连接上。这个方法能在后续排障时帮你快速判断，代码跑不动到底是因为内核连不上，还是因为代码本身的问题。

3. 高频报错subprocess-exited-with-error：原因和解决办法

3.1 先弄懂这个报错是怎么冒出来的

这个报错在搜索引擎里常年霸榜，我在帮别人排查问题时也遇到得最多。它的典型现场是这样的：你执行pip install notebook，前面下载都正常，中间突然出现一堆红字，最后一行写着：

error: subprocess-exited-with-error

有时候下面还会跟着：

× Building wheel for pyzmq (pyproject.toml) ... error

先别急着崩溃，我来解释一下它到底是什么。pip在安装包的时候，存在两种方式：一种是直接下载编译好的 wheel 文件，装完就能用，快且省事；另一种是源文件分发，需要 pip 在本地执行一段 Python 脚本来构建、编译，最终生成 wheel。

subprocess-exited-with-error就是在第二种情况下出现的：pip 调用了一个子进程去构建包，这个子进程执行到一半退出了，而且退出码不是 0，于是 pip 把整个安装过程标记为失败。换句话说，这个报错并不是某一个包坏了，而是构建过程失败，而且是“某一类原因”导致的构建失败。

最常见的高发区是pyzmq、cffi、greenlet、cryptography这几个带 C 扩展的包。它们在构建阶段需要调用系统的 C/C++ 编译器，一旦编译环境不完整，立刻就报subprocess-exited-with-error。

3.2 按顺序排查：5个检查点

遇到这个报错，我建议不要乱试，按下面这个顺序逐个排查，90% 的情况能解决。

检查点一：pip 版本太老。这是最容易被忽略的一个原因。老版本 pip 在构建现代打包规范时经常出问题。先升级：

pip install --upgrade pip setuptools wheel

升级完重新执行安装命令，有很大概率就好了。

检查点二：Python 版本不兼容。新版 notebook（7.x 系列）对 Python 版本有要求，太老或太新都不行。目前 3.9 到 3.12 是安全区间。如果你用的是 3.8 以下，或者刚发布的 3.13，很可能因为依赖包还没有对应的兼容版本而构建失败。判断方法很简单，执行python --version，然后去 PyPI 页面看这个包要求的 Python 版本。

检查点三：缺少编译环境。这个在 Windows 上最典型。构建那几个 C 扩展包需要微软的 C++ 编译器。很多人的电脑上根本没有装，或者只装了运行库没有编译工具链。解决办法是到 Visual Studio 官网下载Microsoft C++ Build Tools，安装时勾选“使用 C++ 的桌面开发”这一项。装完之后重启命令行，再重试一次。

检查点四：网络问题导致源码包下载不完整。这种情况在下载进度条走到 100% 后突然报错时尤其可疑。解决方式很简单，换国内镜像源：

pip install notebook -i https://pypi.tuna.tsinghua.edu.cn/simple

如果已经下载了一半的缓存坏了，可以先清理缓存再重装：

pip cache purge

检查点五：权限不足。在 Linux 或 macOS 上，如果你安装到系统 Python 环境，没有写权限就会失败。这时加--user参数安装到用户目录：

pip install --user notebook

或者直接用虚拟环境，能从根本上绕开权限问题。

3.3 两个最有效的兜底方案

上面 5 个检查点如果都没解决，还有两个兜底方案，几乎能应付剩余所有情况。

第一个，放弃 pip，改用 conda。如果你是 Anaconda 用户，直接用：

conda install notebook

conda 的包管理器不依赖 pip 那套源码构建流程，它主要直接下载预编译的二进制包。也就是说，不需要本地编译器，依赖冲突也少得多。很多时候 pip 装不了的包，conda 一条命令就装好了，这也是我坚持推荐新手用 Anaconda 的原因之一。

第二个，指定安装 wheel 包。有的包在官方 PyPI 上只有源码包，但在第三方源上有编译好的 wheel。你可以让 pip 只装 wheel：

pip install notebook --only-binary :all:

如果这样成功，说明问题确实在源码编译环节。但有些包没有 wheel 版本，这个命令会直接报错找不到匹配版本，这时候还是回头去看 3.2 里的编译环境检查点。

注意：subprocess-exited-with-error报错信息里通常会带有具体是哪个包构建失败。不要只看最后一行，往上面滚动，找“ERROR: Failed building wheel for xxx”或者“× Building wheel for xxx ... error”这两行，那个包名才是重点。网上搜的时候带上包名，能搜到更精准的解决方案。

4. 装完别急着写代码：先做这几个配置

4.1 侧边显示标题总览，长文档救星

很多人打开 Notebook 写了十几个单元格之后，就发现自己迷失了——找不到之前的分析到哪了，不知道这个单元格在整篇文章里属于哪一节。热词里那个“jupyter notebook侧边如何显示标题总览”问的就是这个功能。

在**新版 Notebook（7.x）**里，查看方式很简单：打开一个 .ipynb 文件后，点击工具栏上的左侧栏图标（一个侧边面板的图标），会弹出一个侧边栏，里面有文件列表、内核信息、运行状态等。其中有一个叫Outline（大纲）的标签页，点击之后，你只要在单元格里用了 Markdown 格式并且写了标题（比如# 一级标题、## 二级标题），它就会自动解析成一个可点击的层级目录，点一下就能跳转到对应位置。

这个功能的前提是：标题必须写在 Markdown 单元格里，并且用的是标准 Markdown 的#语法。如果你把标题写在代码单元格里，或只是加粗的普通文字，它不会出现在大纲里。

在JupyterLab里也一样，点击左侧边栏的目录图标（一个带行号的列表图标），或者右键空白处选择“Show Table of Contents”，就能看到同样的标题总览。新版 Notebook 7 和 JupyterLab 的这部分体验已经非常接近了。

4.2 给Notebook装一个可折叠目录

如果你还在用经典版 Jupyter Notebook 5.x / 6.x，那上面说的内置大纲可能没有，这时候可以在页面顶部加一个可折叠的自定义目录（TOC）。最常用的方案是安装jupyter_contrib_nbextensions扩展包。

先安装，再启用：

pip install jupyter_contrib_nbextensions jupyter contrib nbextension install --user

然后启动 notebook，页面上会多出一个Nbextensions标签页，勾选Table of Contents (2)这个扩展，刷新页面后，每个 notebook 顶部就会多出一个目录按钮，可以自动扫描 Markdown 标题并生成带链接的目录。

注意：jupyter_contrib_nbextensions对新版 Notebook 7 支持不好，如果你装完发现 Nbextensions 页面不显示，多半是这个原因。这时候别再死磕扩展了，直接用 4.1 里的内置 Outline，效果是一样的。我见过有人为了装这个扩展折腾一下午，最后发现新版根本不需要它——先检查自己的版本，再决定用哪个方案。

4.3 设置默认启动目录和自动保存

每个项目的启动路径如果都用--notebook-dir指定，久了会嫌麻烦。前面 2.3 我提过修改配置文件的方法，这里把它讲完整。

执行：

jupyter notebook --generate-config

这个命令会生成配置文件，路径在用户目录的.jupyter文件夹下。用文本编辑器打开，把这一行：

# c.ServerApp.notebook_dir = ''

改写成：

c.ServerApp.notebook_dir = 'D:/work'

保存后，每次启动就默认打开D:/work目录。

顺手还可以设置自动保存时间。默认情况下 Notebook 会定期自动保存，但间隔频率可以调。打开配置文件，找到：

# c.ServerApp.autosave_interval = 120

如果你想每 30 秒保存一次，就改成：

c.ServerApp.autosave_interval = 30

这个功能对写长文、跑长时间实验的人特别重要。有一次我跑了一上午的模型，结果笔记本突然卡死没保存，数据全丢了，从那以后我养成了把自动保存间隔调短的习惯。

4.4 页面美化和其他可选配置

如果你觉得默认的白底页面太刺眼，可以装主题插件：

pip install jupyterthemes jt -t oceans16 # 换成深色主题 jt -r # 恢复默认

这类主题工具早期版本非常火，但它对 Notebook 7 的支持也存在兼容问题。我的建议是：先别急着美化，等确认核心功能稳定了再折腾。主题这东西不影响功能，但一旦和扩展冲突，排查起来极其痛苦。

另外推荐一个我刚提到的检查手段：在 Notebook 里输入%who或%timeit这类魔法命令，能快速确认 IPython 内核是否正常。如果你连魔法命令都无法运行，说明内核可能坏了，往下看第 5 节。

5. 使用中的常见问题与排障手册

5.1 Jupyter打不开怎么办

打不开分三种情况，症状不一样，原因也完全不同。

情况一：启动后终端一直卡住，没有任何日志输出。这很可能是端口被占用了。jupyter notebook默认监听 8888 端口，如果你之前启动过没关干净，端口就被占了。解决办法是杀掉旧进程，或者换端口启动：

jupyter notebook --port=8889

杀进程的方式，Windows 上打开任务管理器找到 Python 进程结束，或者用：

netstat -ano | findstr :8888 taskkill /PID 这里填PID /F

macOS/Linux 上用：

lsof -i :8888 kill -9 这里填PID

情况二：浏览器打开了，但页面一直空白或者转圈。这种情况服务器可能已经启动成功，但浏览器没有正确连接。先在命令行窗口里看有没有输出一个 URL，形如http://localhost:8888/tree?token=xxxx，手动复制到浏览器地址栏访问。如果还不行，试试用127.0.0.1替换localhost，有时代理设置会影响 localhost 的解析。

情况三：双击图标闪退。这种情况我看得最多的原因是环境变量 PATH 没配好。比如你装了 Anaconda 但没有勾选添加到 PATH，然后又直接在普通 CMD 里敲jupyter，自然就闪退了。解决方式：不要双击图标，打开Anaconda Prompt再执行jupyter notebook，让 Anaconda 自己的环境变量生效。

5.2 Kernel一直转圈或报错

你写好了代码，点击运行，但单元格下方的In [*]一直不变成In [1]，或者一直显示“Connecting to kernel”，这多半是内核问题而不是代码问题。

首先尝试“重启内核”：在菜单栏选Kernel -> Restart Kernel。这个操作会杀掉当前内核进程，重新启动一个新的。它能解决很多内存占用过高、内核状态错乱的问题，相当于电脑死机后的重启。

如果重启内核还不行，看命令行窗口。启动jupyter notebook的那个终端窗口会打印内核的错误日志。常见的错误有几类：

• ModuleNotFoundError: No module named 'ipykernel'：说明当前 Python 环境没有安装 ipykernel，补装一下：

pip install ipykernel

• Kernel died或者kernel_....py相关报错：检查 Python 版本和 notebook 版本是否兼容，必要时新建一个 conda 环境重新配置。

如果内核列表里乱七八糟，可以查看当前有哪些内核注册：

jupyter kernelspec list

卸载掉一个损坏的内核：

jupyter kernelspec uninstall 内核名

以后再重新绑定。这个操作不伤数据，只是清理掉内核的注册信息。

5.3 .ipynb文件打不开怎么办

.ipynb文件本质上是一个 JSON 文件，里面按单元格存储了所有的代码、输出结果和元数据。这个特性让它在出问题时很容易急救。

如果双击一个.ipynb文件毫无反应，或者打开后报语法错误，你可以先用普通的文本编辑器（比如 VS Code、Notepad++，甚至系统自带的记事本）打开这个文件。如果内容是纯文本格式的 JSON 结构，说明文件本身没坏。

这时候比较快的方式是直接在命令行里启动 Notebook，然后通过 Web 界面的上传入口把文件传上去。如果还是不显示，那可能是文件里某个单元格的 output 数据格式损坏。急救手法：把文件复制一份备份，然后用 VS Code 打开原文件，整体结构中有"outputs"字段的部分，把里面的内容清空，保存后再用 Notebook 打开。这个操作会丢掉之前运行过的输出结果，但代码和 Markdown 都保留着。

这种“输出数据损坏”的情况虽然不算多，但我确实遇到过两次。一次是断电导致文件写到一半，一次是第三方插件改坏了 JSON 结构。提前把.ipynb当普通文件备份，比什么都保险。

5.4 内核管理：被忽略但很核心的操作

排障排到后面，你会发现 90% 的“运行不了”问题都绕不开一个东西：内核（Kernel）。如果在你的工作里经常要切换不同 Python 版本，或者需要在 conda 环境和虚拟环境之间来回跳，内核注册这个技能就特别关键。

常见的需求是：我建了一个新环境，想在这个环境里运行 Notebook。做法是：

conda create -n myenv python=3.11 -y conda activate myenv pip install ipykernel python -m ipykernel install --user --name myenv --display-name "Python (myenv)"

然后刷新 Notebook 页面，点击右上角New，就会多出Python (myenv)这个内核选项。

反过来，如果你要把某个内核从列表里移除：

jupyter kernelspec remove myenv

这个操作只是解除注册，并不会删除你的 Python 环境，所以可以放心做。

提示：换内核不代表换代码文件，ipynb文件本身不绑定内核，你可以在同一个文件里随意切换内核来运行，只是切换后最好重启一次内核，避免内存里还残留上一个内核的状态。

最后再分享一个我自己的使用习惯

装了这么多年 Jupyter，最大的体会是：大多数人装不好，不是操作能力不行，而是环境概念没建立起来。只要你理解了“前端页面 + 服务器 + 内核”这三个角色的分工，再遇到问题就不慌了。我现在排查问题时永远按这个顺序走：先看服务器日志，再查内核状态，最后才看代码。

我个人建议新手装完后，不要急着安装各种美化插件和扩展包，先把 4.1 的标题总览、4.3 的默认目录配置好，跑通几个完整的分析小项目，再考虑折腾主题和增强功能。工具是拿来用的，不是拿来伺候的。

最后留一个小技巧：写长文档的时候，单元格类型切到 Markdown，用#、##、###写好标题层级。这一步不仅能让你在侧边栏看到清晰的标题总览，还能在用 Outline 快速跳转时省下大量滚动时间。这个习惯，我在所有数据项目里都保持到现在，建议你也从第一天就养成。