Jupyter Notebook v7 实战指南：服务器启动、Notebook 文档结构、单元格模型与完整使用工作流

Jupyter Notebook v7 实战指南：服务器启动、Notebook 文档结构、单元格模型与完整使用工作流

【免费下载链接】notebook Jupyter Interactive Notebook 项目地址: https://gitcode.com/GitHub_Trending/no/notebook

导读

本文以本仓库（Jupyter Notebook 7.x 分支）的官方用户指南 docs/source/notebook.md 为核心脉络，系统讲解 Jupyter Notebook 的完整使用方式：从命令行启动服务器、Dashboard 文件管理，到 Notebook 文档的内部结构（代码单元格、Markdown 单元格、Raw 单元格），再到搜索、绘图、内核安装与文档信任等进阶操作。文中所有实操步骤均结合本仓库的 Python 服务端实现（notebook/app.py）、前端应用入口（packages/application/src/app.ts）与测试用例（tests/test_app.py）进行源码级印证，读者学完即可独立完成 Jupyter Notebook 的安装、启动与日常创作。

一、Jupyter Notebook 是什么：一个应用与一种文档的结合

Jupyter Notebook 是 Project Jupyter 生态下的笔记本创作应用，建立在「计算型笔记本格式（computational notebook format）」之上，为代码原型、数据探索可视化与观点分享提供了快速、交互式的新方式。它把基于控制台的交互式计算推向了质的变革：不再只是"跑一个脚本"，而是通过基于 Web 的应用，完整捕获开发、记录、执行代码以及沟通结果的整个计算过程。

从架构上看，Jupyter Notebook 由两大组件构成：

在本仓库中，这两部分分别有清晰的实现：Web 应用由 Python 侧的 Tornado 处理器（notebook/app.py 中的 TreeHandler、NotebookHandler 等）与 TypeScript 前端应用（packages/application/src/app.ts 中的 NotebookApp，其 name = 'Jupyter Notebook'）共同构成；文档格式则由 .ipynb JSON 文件承载（可参考 binder/example.ipynb 查看真实示例）。

1.1 Web 应用的主要特性

• 浏览器内代码编辑：支持自动语法高亮、缩进、Tab 补全与内省（introspection）。
• 浏览器内执行代码：计算结果的输出会附加到生成它的代码旁边。
• 富媒体结果展示：计算结果可用 HTML、LaTeX、PNG、SVG 等多种富媒体形式呈现，例如 matplotlib 渲染的高质量插图可内联显示。
• Markdown 富文本编辑：用 Markdown 标记语言撰写代码旁注，不受纯文本限制。
• LaTeX 数学公式：在 Markdown 单元格中直接使用 LaTeX 书写数学符号，由 MathJax 在浏览器内原生渲染。

1.2 Notebook 文档：完整的计算记录

Notebook 文档保存了交互会话的输入与输出，以及伴随代码的附加文字（不参与执行）。因此，一份 notebook 文件可以视为一次会话的完整计算记录——可执行代码与解释性文字、数学公式和结果的富媒体表示交织在一起。这些文档本质上是 JSON 文件，以 .ipynb 扩展名保存。由于 JSON 是纯文本格式，它们可以被纳入版本控制并与同事共享。

此外，.ipynb 文档可以通过 nbconvert 命令导出为一系列静态格式，包括 HTML（例如用于博客文章）、reStructuredText、LaTeX、PDF 和幻灯片（slideshow）。本仓库的 docs/source/examples/Notebook/ 目录下存放了 Notebook Basics.ipynb、Running Code.ipynb、Working With Markdown Cells.ipynb、Typesetting Equations.ipynb 等官方示例笔记本，可用于对照学习各主题。

1.3 隐私说明

由于 Jupyter 运行在浏览器中，有人会担心敏感数据的使用。但按照标准安装流程，Jupyter 实际运行在你自己的计算机上。如果地址栏的 URL 以 http://localhost: 或 http://127.0.0.1: 开头，那就是你的计算机充当服务器。Jupyter 不会把数据发送到任何其他地方——而且由于它是开源的，任何人都可以核实这一点。若使用远程 Jupyter（如公司或大学托管的服务器）处理敏感数据，请先与 IT 或数据保护部门沟通。Jupyter 还致力于确保浏览器中的其他页面或同机其他用户无法访问你的 notebook 服务器，这依赖于服务器内置的安全机制。

二、启动 Notebook 服务器

在命令行中启动 notebook 服务器非常简单：

jupyter notebook

执行后，控制台会打印 notebook 服务器的相关信息，并自动在浏览器中打开 Web 应用的 URL（默认是 http://127.0.0.1:8888）。这一入口行为的后端实现在 notebook/app.py 中：JupyterNotebookApp 类继承自 LabServerApp 与 NotebookConfigShimMixin，其 default_url 被设置为 /tree（第 251 行），并通过 initialize_handlers() 注册了 /tree(.*)、/notebooks(.*)、/edit(.*)、/consoles/(.*)、/terminals/(.*) 等页面处理器（第 350-355 行）。jupyter notebook 命令实际对应 JupyterNotebookApp.launch_instance（第 363 行 main = launch_new_instance = JupyterNotebookApp.launch_instance）。

2.1 Dashboard：文件入口

Web 应用的落地页（landing page）称为 dashboard，它显示 notebook 目录中当前可用的笔记本。默认情况下，该目录是启动 notebook 服务器的目录。

在 dashboard 上你可以：

• 通过 New Notebook 按钮创建新的笔记本；
• 点击文件名打开已有笔记本；
• 拖放 .ipynb 笔记本和标准 .py Python 源代码文件到笔记本列表区域。

从源码看，dashboard 由 TreeHandler 提供（notebook/app.py 第 133-170 行）：若路径是目录，则渲染 tree.html 模板；若路径是 notebook 文件，则重定向到 /notebooks/…；若是其他文件则重定向到 /files/…；不存在的路径返回 404。这些跳转逻辑在 tests/test_app.py 的 test_tree_handler 中均有对应断言（例如访问 tree/notebook1.ipynb 会重定向到 /a%40b/notebooks/notebook1.ipynb，访问 tree/foo.txt 会重定向到 /a%40b/files/foo.txt）。

2.2 直接从命令行打开指定笔记本

启动服务器时也可以绕过 dashboard，直接打开某个笔记本：

jupyter notebook my_notebook.ipynb

如果未给出扩展名，则默认假定为 .ipynb。而在已打开的笔记本内部，可通过菜单 File | Open… 在新浏览器标签页中打开 dashboard，从而打开或创建其他笔记本。

2.3 多服务器与端口

可以同时启动多个 notebook 服务器，以便在不同目录中工作。默认情况下，第一个服务器使用 8888 端口，后续服务器会在其附近搜索可用端口。也可以使用 –port 选项手动指定端口：

jupyter notebook –port 9999

说明：–port 等命令行选项由底层 jupyter_server 的 flags 机制解析，JupyterNotebookApp.flags 在 serverapp.flags 基础上扩展了 custom-css、expose-app-in-browser 等本应用专属选项（见 notebook/app.py 第 271-280 行），test_notebook_app_flags_are_isolated 测试验证了这一隔离关系。

三、创建新的 Notebook 文档

新笔记本可以随时创建，有两种入口：

新笔记本会在同一目录中创建，并在新的浏览器标签页中打开，同时反映为 dashboard 笔记本列表中的新条目。Dashboard 相关按钮的界面截图可参见 dashboard_files_tab_btns.png 与 dashboard_files_tab_new.png。

四、打开 Notebook：内核与会话的生命周期

一个已打开的笔记本恰好连接一个交互会话，即一个内核（kernel）。内核负责执行用户发送的代码并回传结果。

关键特性在于：内核在浏览器窗口关闭后仍然存活。从 dashboard 重新打开同一笔记本时，Web 应用会重新连接到同一内核。在 dashboard 中，有活跃内核的笔记本旁边会显示 Shutdown（关闭）按钮，而没有活跃内核的笔记本则在相应位置显示 Delete（删除）按钮。

其他客户端也可以连接到同一个内核。每当内核启动时，notebook 服务器会在终端打印类似这样的消息：

[JupyterNotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373

这一长串字符是内核的 ID，足以获取连接内核所需的信息。如果笔记本使用 IPython 内核，还可以在笔记本内运行 %connect_info 魔法命令查看连接信息，它会打印相同的 ID 及其他细节。

例如，可以在命令行手动启动一个连接到同一个内核的 Qt 控制台，只需传入 ID 的一部分：

$ jupyter qtconsole –existing 87f7d2c0

不带 ID 时，–existing 会连接到最近启动的内核。使用 IPython 内核时，也可以在笔记本中运行 %qtconsole 魔法命令，直接打开连接到同一内核的 Qt 控制台。

延伸：本仓库的 UI 测试目录 ui-tests/test/ 提供了 console.spec.ts、notebook.spec.ts、filebrowser.spec.ts 等 Playwright 端到端测试，以及 ui-tests/test/notebooks/ 下 simple.ipynb、empty.ipynb 等真实测试笔记本，可帮助理解内核会话在真实浏览器场景中的行为。

五、Notebook 用户界面

创建新笔记本文档后，你会看到四个基本元素：笔记本名称（notebook name）、菜单栏（menu bar）、工具栏（toolbar） 和一个空的代码单元格（code cell）。

• 笔记本名称：显示在页面顶部、Jupyter logo 旁边，对应 .ipynb 文件名。点击名称会弹出对话框允许重命名。因此，在浏览器中把笔记本从 "Untitled0" 重命名为 "My first notebook"，就会把 Untitled0.ipynb 文件重命名为 My first notebook.ipynb。
• 菜单栏：提供各种用于操纵笔记本工作方式的选项。
• 工具栏：通过点击图标快速执行笔记本中最常用的操作。
• 代码单元格：默认的单元格类型，其含义见下一节。

前端页面由 Jinja2 模板渲染，例如 app/templates/notebooks_template.html 会注入 page_config（含 baseUrl、wsUrl、notebookPage 等信息），并支持通过 custom/custom.css 加载自定义样式；模板中的脚本还会在加载时从 URL 中移除 token（parsedUrl.searchParams.delete('token')）。页面的 appVersion、baseUrl、token、terminalsAvailable 等配置由 notebook/app.py 的 NotebookBaseHandler.get_page_config()（第 56-130 行）统一生成。

六、Notebook 文档的结构：单元格（Cell）

笔记本由一序列单元格（cells）组成。单元格是一个多行文本输入框，其内容可以通过 Shift-Enter 执行，也可以点击工具栏的 "Play" 按钮，或通过菜单 Cell → Run 执行。单元格的执行行为由单元格类型决定，共分为三种：代码单元格（code cells）、**Markdown 单元格（markdown cells）**和 Raw 单元格（raw cells）。

每个单元格最初都是代码单元格，但可以通过工具栏的下拉菜单（初始显示 "Code"）或键盘快捷键更改其类型。

对单元格结构与 JSON 格式的进一步说明，可参考仓库中的真实文档：docs/source/examples/Notebook/Notebook Basics.ipynb（Notebook 基础）、Running Code.ipynb（运行代码）、Working With Markdown Cells.ipynb（Markdown 单元格）以及 Typesetting Equations.ipynb（数学排版）。

6.1 代码单元格（Code cells）

代码单元格允许编辑和编写新代码，具备完整的语法高亮与 Tab 补全。使用的编程语言取决于内核，默认内核（IPython）运行 Python 代码。

当代码单元格被执行时，其中的代码被发送到与笔记本关联的内核；计算返回的结果随后以单元格**输出（output）的形式显示在笔记本中。输出不限于文本，还包括 matplotlib 图形、HTML 表格（如 pandas 数据分析包所用）等多种形式，这得益于 IPython 的富显示（rich display）**能力。

6.2 Markdown 单元格（Markdown cells）

可以用富文本以"文学化编程"的方式记录计算过程：把描述性文字与代码交替排列。在 IPython 中，这是通过 Markdown 语言标记文本实现的，对应单元格称为 Markdown 单元格。Markdown 提供了一种简单的文本标记方式，可指定文本中哪些部分需要强调（斜体）、加粗、形成列表等。

标题（heading）可用于为文档提供结构：Markdown 标题由 1 到 6 个 # 号加一个空格和章节标题组成。Markdown 标题会被转换为笔记本章节的可点击链接，在导出为其他文档格式（如 PDF）时也用作结构提示。

当 Markdown 单元格被执行时，Markdown 代码会转换为对应的格式化富文本。Markdown 允许在其中嵌入任意 HTML 代码用于排版。

数学公式也可以在 Markdown 单元格中直接书写，使用标准 LaTeX 记号：$…$ 表示行内数学，$$…$$ 表示独立成块的数学。单元格执行时，LaTeX 部分会在 HTML 输出中自动渲染为高质量排版的方程，这得益于 MathJax 对 LaTeX 功能的广泛支持。

LaTeX 与 AMS-LaTeX（amsmath 包）定义的标准数学环境同样可用，例如 \\begin{equation}…\\end{equation} 和 \\begin{align}…\\end{align}。还可以使用标准方法定义新的 LaTeX 宏，例如 \\newcommand，只需将其放在 Markdown 单元格的数学分隔符之间，这些定义在 IPython 会话的其余部分都会生效。

6.3 Raw 单元格（Raw cells）

Raw 单元格提供了一个可以直接书写输出的地方。Raw 单元格不会被笔记本求值。当通过 nbconvert 处理时，Raw 单元格会原样到达目标格式。例如，你可以在 Raw 单元格中键入完整的 LaTeX，它只有在 nbconvert 转换为 LaTeX 之后才会被渲染。

七、基本工作流

笔记本中的常规工作流与标准 IPython 会话非常相似，区别在于：你可以多次原地编辑单元格直到获得满意结果，而不必像以前那样使用 %run 魔法命令重跑独立的脚本。

通常，你会把计算问题分块处理：把相关的想法组织进单元格，待前一部分正确工作后再继续推进。这比把计算拆成必须一起执行的脚本要方便得多，尤其是当某些部分需要很长时间运行时。

中断计算：使用菜单 Kernel → Interrupt，或键盘快捷键 i, i（连续按两次 i）。

重启整个计算过程：使用菜单 Kernel → Restart，或快捷键 0, 0。

笔记本可以下载为 .ipynb 文件，或使用菜单 File → Download as 转换为多种其他格式。

源码视角：中断与重启是对内核进程的操作。从 notebook/app.py 可见，前端通过 /notebooks(.*) 处理器进入笔记本页面，而内核会话的管理则由底层 jupyter_server 与 jupyter_client 负责（notebook/app.py 中导入了 jupyter_client.utils 与 jupyter_server 的 handler/extension 基础设施）。binder/example.ipynb 还演示了 notebook 文档中内嵌图片附件（attachments 字段）与 Markdown 单元格的实际组合方式，是理解文档格式的良好样例。

八、键盘快捷键

笔记本中的所有操作都可以用鼠标完成，但最常见操作也提供了键盘快捷键。最核心的快捷键如下：

完整的快捷键列表可通过菜单 Help → Keyboard Shortcuts 查看。

提示：本仓库的 UI 测试 ui-tests/test/ 中的 menus.spec.ts、layout.spec.ts 等用例（含 opened-menu-edit-*.png、opened-menu-file-new-*.png 等快照）覆盖了菜单结构的真实渲染结果，可用于理解菜单布局。

九、在笔记本内搜索

Jupyter Notebook 内置了高级搜索插件，用于在笔记本或其他文档内查找文本，默认使用 Ctrl-F（macOS 为 Cmd+F）快捷键。

浏览器自带的 find 功能会给出意外结果，因为它（默认情况下）无法访问文档的完整内容；不过你仍然可以从浏览器菜单使用浏览器查找功能，也可以在**高级设置编辑器（Advanced Settings Editor）**中禁用内置搜索快捷键。

另一种替代方案是禁用窗口化笔记本渲染（windowed notebook rendering），将完整文档内容暴露给浏览器，但代价是牺牲性能。

十、绘图（Plotting）

Jupyter Notebook 的一个主要特性是能够显示运行代码单元格输出的图形。IPython 内核被设计为与 matplotlib 绘图库无缝协作以提供此功能。特定的绘图库集成是内核的特性（而非应用本身的特性）。

十一、安装内核（Installing kernels）

• Python 内核的安装方法参见 IPython 官方安装说明（即 ipython 包自带的 pip install / 发行版包管理器安装流程）。
• 其他语言内核：Jupyter 社区维护了覆盖多种语言的内核清单，它们通常附带如何让内核在笔记本中可用的说明。安装好内核后，dashboard 的 New 菜单与笔记本内的 Kernel → Change Kernel 中即可选择对应语言。

十二、信任笔记本（Trusting Notebooks）

为防止不受信任的代码在打开笔记本时代表用户执行，Jupyter 会为每个受信任的笔记本存储一个签名。notebook 服务器在笔记本打开时验证此签名；如果找不到匹配的签名，JavaScript 和 HTML 输出将不会显示，直到通过重新执行单元格重新生成它们。

你自己完整执行过的任何笔记本都会被视为可信的，其 HTML 和 JavaScript 输出会在加载时显示。

如果你需要在不重新执行的情况下查看 HTML 或 JavaScript 输出，并且确信笔记本没有恶意内容，可以在命令行告诉 Jupyter 信任它：

$ jupyter trust mynotebook.ipynb

源码佐证：信任机制在前端有对应实现。仓库中的 packages/notebook-extension/src/trusted.tsx 即负责笔记本的"受信任"状态呈现与相关 UI；底层签名的生成与校验则依赖 nbformat 与 jupyter_server 的安全基础设施，最终输出行为取决于执行 jupyter trust 时写入的签名是否与服务器持有的密钥匹配。

十三、浏览器兼容性

Jupyter Notebook 旨在支持以下浏览器的最新版本：

• Chrome
• Safari
• Firefox

较新版本的 Opera 与 Edge 也可能正常工作，但如果出现问题，请使用受支持的浏览器之一。

已知问题：使用 Safari 配合 HTTPS 与不受信任的证书时无法正常工作（WebSocket 会连接失败）。

十四、结语：从文档到运行的完整链路

回顾全文，Jupyter Notebook 的每次使用都贯穿一条清晰的链路：命令行 jupyter notebook 启动服务器 → TreeHandler 渲染 dashboard → 打开/创建 .ipynb 文档 → 浏览器中的 NotebookApp 前端与内核建立会话 → 三种单元格协作完成计算与记录 → 通过 nbconvert 导出或 jupyter trust 提升信任。这一链路中的每个环节都可以在本仓库中找到对应实现：Python 侧见 notebook/app.py 与 tests/test_app.py，前端侧见 packages/application/src/app.ts 与 app/templates/ 下的模板，文档示例见 docs/source/examples/Notebook/。对照这些资源阅读本文，即可将操作经验与实现原理一一对应起来。

【免费下载链接】notebook Jupyter Interactive Notebook 项目地址: https://gitcode.com/GitHub_Trending/no/notebook

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考