企业官网建设流程全解析

JupyterLab 使用与开发全指南：安装、运行、扩展与架构解析

【免费下载链接】jupyterlabJupyterLab computational environment.项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlab

JupyterLab 是 Project Jupyter 推出的下一代交互式计算环境，在经典 Jupyter Notebook 的记事本、终端、文本编辑器、文件浏览器与富文本输出等基础上，提供了更加灵活、可扩展的统一用户界面。本文以仓库根目录 README.md 为骨架，结合仓库内服务端实现（jupyterlab/labapp.py、pyproject.toml）与前端包结构（packages/application/package.json），系统讲解 JupyterLab 的安装、启动、运行模式、扩展机制与开发参与方式，帮助读者快速上手并理解其内部运行原理。

JupyterLab 是什么

按 README 的定义，JupyterLab 是"一个基于 Jupyter Notebook 与 Jupyter 架构的可扩展、支持交互与可复现计算的运行环境"，是 Project Jupyter 的下一代用户界面。它把经典 Jupyter Notebook 中大家熟悉的积木块——记事本（Notebook）、终端（Terminal）、文本编辑器（Text Editor）、文件浏览器（File Browser）、富输出（Rich Outputs）等——整合进一个灵活而强大的统一界面中。

与经典 Notebook 单文档的单页模型不同，JupyterLab 采用多文档、多面板的 IDE 式布局：你可以并排打开多个笔记本、终端与文件，拖拽调整面板位置，并将多个文档组织成可保存、可分享的"工作区（Workspace）"。前端核心包 packages/application 中可以看到，整个界面建立在 Lumino（@lumino/application、@lumino/widgets、@lumino/commands、@lumino/signaling）插件化应用框架之上，并由@jupyterlab/docregistry、@jupyterlab/rendermime、@jupyterlab/services等模块提供文档注册、渲染与内核服务通信能力。

安装 JupyterLab

使用 conda / mamba / pip 一键安装

README 提供了三种最主流的安装方式，任选其一即可：

# 使用 conda conda install -c conda-forge jupyterlab # 使用 mamba mamba install -c conda-forge jupyterlab # 使用 pip pip install jupyterlab

conda-forge渠道的预编译包通常能避免编译依赖，适合科学计算环境；pip 方式则与现有 Python 虚拟环境无缝集成。从 pyproject.toml 的打包配置看，JupyterLab 4.x 要求 Python >= 3.10，依赖的核心组件包括jupyter_server>=2.19.0,<3、jupyterlab_server>=2.28.0,<3、notebook_shim>=0.2、tornado>=6.2.0以及jupyter-lsp>=2.0.0等，安装后会自动注册为 Jupyter Server 的服务器扩展。

关于pip install --user的 PATH 问题

README 特别提醒：如果使用pip install --user安装，必须把用户级bin目录加入PATH环境变量，才能直接运行jupyter lab。在类 Unix 系统（FreeBSD、GNU/Linux、macOS）上执行：

export PATH="$HOME/.local/bin:$PATH"

如果遇到 "Command 'jupyter' not found" 错误，一般就是 PATH 未配置正确。此时可以不修改 PATH，直接使用完整路径启动：

~/.local/bin/jupyter lab

使用旧版本 Jupyter Notebook（< 5.3）时

README 指出：当搭配的 Jupyter Notebook 版本早于 5.3 时，安装 JupyterLab 后还需手动启用其服务器扩展：

jupyter serverextension enable --py jupyterlab --sys-prefix

如果使用新版 Jupyter Notebook / Jupyter Server，则无需手动操作。仓库中的 jupyter-config/jupyter_server_config.d/jupyterlab.json 与 jupyter-config/jupyter_notebook_config.d/jupyterlab.json 展示了安装包自带的两份配置：前者在ServerApp.jpserver_extensions中声明"jupyterlab": true，后者在NotebookApp.nbserver_extensions中声明同样的开关，分别保证 JupyterLab 服务器扩展被 Jupyter Server 与旧版 Notebook 自动加载。

启动 JupyterLab

安装完成后，在终端执行：

jupyter lab

JupyterLab 会自动在浏览器中打开。若要查看更多启动选项，可查看 jupyterlab/labapp.py 中LabApp的examples字段，它给出了几种常见用法：

jupyter lab # 启动 JupyterLab jupyter lab --dev-mode # 开发模式启动（无扩展，需 pip install -e . 源码安装） jupyter lab --core-mode # 核心模式启动（无第三方扩展） jupyter lab --app-dir=~/myjupyterlabapp # 以指定应用目录（特定扩展组合）启动 jupyter lab --certfile=mycert.pem # 使用 SSL/TLS 证书启动

三种运行模式

LabApp的description与initialize_templates方法把 JupyterLab 归纳为三种运行模式，理解它们有助于排查资源路径问题：

• 核心模式（Core mode，--core-mode）：直接使用已安装的jupyterlabPython 包内自带的 JavaScript 静态资源，不加载任何第三方扩展。这是稳定版在没有安装扩展时的默认行为。实现上（见 jupyterlab/labapp.py）会把static_paths/template_paths指向包内的static目录，并清空labextensions_path。
• 开发模式（Dev mode，--dev-mode）：使用仓库dev_mode目录中未发布的本地 JavaScript 包，页面顶部会出现红色条纹提示。仅当 JupyterLab 以pip install -e .方式安装时可用，适合前端源码开发。
• 应用模式（App mode）：JupyterLab 允许用户创建多个携带不同扩展组合的"应用"，通过--app-dir指定应用目录；默认应用目录可通过jupyter lab path查询。

与之配套的子命令在LabApp.subcommands中注册（jupyterlab/labapp.py）：

jupyter lab build # 构建应用（staging 目录编译后输出到 static） jupyter lab clean # 清理应用目录（staging/extensions/settings/static） jupyter lab path # 打印应用、用户设置、工作区等目录路径 jupyter lab workspace # 工作区导出/导入/列出（子命令 export/import/list） jupyter lab licenses # 查看应用使用的前端包许可证

其中jupyter lab build支持--dev-build、--minimize、--app-dir、--debug-log-path等参数。LabBuildApp（jupyterlab/labapp.py）中的两个关键开关值得注意：

• dev_build：控制使用 dev 构建还是更精简的 production 构建。默认绝大多数用户为False（production），但一旦安装了来自本地文件的 labextensions，默认会切换为True；显式设置False可强制在所有场景下使用 production 构建。
• minimize：控制 Rspack 构建时是否压缩 JS bundle，有助于提升 JupyterLab 整体性能；在低内存环境构建失败时，关闭压缩往往能解决问题。

若需对全部构建关闭这两个选项，可在任意 Jupyter 配置目录下新建jupyter_config.py并写入：

c.LabBuildApp.minimize = False c.LabBuildApp.dev_build = False

配置文件目录列表可用jupyter --paths查看。

应用相关目录与路径

通过jupyter lab path（LabPathApp，见 jupyterlab/labapp.py）可打印三类路径，它们也分别支持环境变量覆盖：

• 应用目录（Application directory）：默认由JUPYTERLAB_DIR环境变量配置；
• 用户设置目录（User Settings directory）：默认由JUPYTERLAB_SETTINGS_DIR配置，否则回退到默认 Jupyter 配置目录下的/lab/user-settings；
• 工作区目录（Workspaces directory）：默认由JUPYTERLAB_WORKSPACES_DIR配置，否则回退到默认配置目录下的/lab/workspaces。

支持的浏览器

README 明确列出当前已知可正常工作的最新版浏览器：

• Firefox
• Chrome
• Safari

新版 Chromium 内核浏览器一般也能获得良好支持。若在浏览器中遇到渲染异常，优先检查浏览器是否升级到最新版本，以及前端静态资源（static目录）是否与当前 JupyterLab 版本匹配。

扩展机制：让 JupyterLab 无限扩展

JupyterLab 的扩展性是其核心设计目标之一。README 说明其扩展分为两类：

• 预构建扩展（Prebuilt extensions）：可通过 PyPI、conda 等包管理器分发，安装后无需额外构建步骤，开箱即用。
• 源码扩展（Source extensions）：直接通过 npm 安装（可搜索jupyterlab-extension关键词的 npm 包），但需要额外的构建步骤。

从 Python 侧看，pyproject.toml 声明了扩展管理器的入口点：

[project.entry-points."jupyterlab.extension_manager_v1"] readonly = "jupyterlab.extensions:get_readonly_manager" pypi = "jupyterlab.extensions:get_pypi_manager"

LabApp.extension_manager配置项（默认值为"pypi"，见 jupyterlab/labapp.py）用于选择扩展管理器工厂："readonly"提供无安装能力的只读管理器，"pypi"则基于 PyPI 与 pip 安装扩展。在 jupyterlab/labapp.py 的initialize_handlers中可以看到，非核心模式启动时会实例化所选管理器，并将扩展元数据注入前端page_config["extensionManager"]；若所选管理器初始化失败，会回退到ReadOnlyExtensionManager（实现在 jupyterlab/extensions/readonly.py），同时支持通过LabServerApp.blocked_extensions_uris/allowed_extensions_uris配置扩展黑/白名单列表（详见 jupyterlab/extensions/manager.py 中扩展兼容性检查与消息映射的实现）。前端扩展管理器 UI 位于 packages/extensionmanager 与 packages/extensionmanager-extension。

命令行层面还提供扩展管理工具jupyter labextension（入口在 jupyterlab/labextensions.py，对应 pyproject.toml 的[project.scripts]），支持安装、卸载、禁用、启用、列表等操作；应用模式下的扩展安装会触发jupyter lab build重新构建静态资源。

从源码开发与贡献

为 JupyterLab 开发扩展

要开始开发扩展，README 指引读者阅读开发者文档与 API 文档。就本仓库而言，前端部分是一个大型 TypeScript monorepo：packages/目录下按功能拆分为application、notebook、apputils、services、ui-components、rendermime等数十个独立 npm 包，每个包都维护独立的package.json（如 packages/application/package.json 声明了依赖@lumino/application、@jupyterlab/services等），并统一通过仓库根目录的 package.json 与 lerna.json 组织版本与发布。示例项目位于 examples/，覆盖 app、cell、console、filebrowser、notebook、terminal 等典型扩展场景，每个示例均包含main.py、package.json与rspack.config.js，是上手编写前端扩展的最佳参照。

参与 JupyterLab 本体开发

从 git 源码安装的说明见 CONTRIBUTING.md。开发者可从源码构建，仓库提供的开发相关脚本与工具包括：

• binder/environment.yml：Binder 在线试用环境配置；
• buildutils/：版本号管理、包创建/删除、依赖更新、发布等一揽子工程化脚本；
• galata/：基于 Playwright 的端到端测试框架（含jupyterlab/test大量 UI 回归测试用例）；
• scripts/：CI 安装脚本（ci_install.sh）、flake 测试分析、i18n 检查等辅助脚本。

JupyterLab 遵循 Jupyter 社区指南（Jupyter Community Guides），开发者应同时阅读 docs/ 下的用户与开发者文档。

每周开发会议

社区每周三太平洋时间上午 9:00 召开视频会议，任何人都可以旁听或参与讨论（会议记录归档于 Jupyter Frontends 团队 compass）。

版本维护现状与升级建议

README 中有一条重要公告：JupyterLab 3 已于 2024 年 5 月 15 日到达维护期终点，关键问题的修复仅回溯支持至 2024 年 12 月 31 日。仍在使用 JupyterLab 3 的用户应尽快升级到 JupyterLab 4。从本仓库看，前端包版本号（如@jupyterlab/application的4.7.0-alpha.1）与 Python 包jupyterlab（jupyterlab/_version.py）共同推进到 4.x 系列，pyproject.toml中Framework :: Jupyter :: JupyterLab :: 4的分类器也印证了当前主线为 4.x。

获取帮助与反馈

• 提问交流：推荐在 Jupyter Discourse 论坛的 JupyterLab 板块提问，公开问答可以沉淀为对他人有用的资料。
• 提交 Bug：请先阅读问题报告指南，再使用 Bug 模板新建 issue；已解决的问题在闲置一段时间后会被 lock bot 锁定，如仍需讨论请新开 issue 并引用原 issue。
• 功能建议：欢迎使用功能请求模板提交新特性建议，帮助项目对更多用户更有用。

许可证与版权模式

JupyterLab 采用共享版权（shared copyright）模式，所有贡献者保留各自贡献的版权，全部代码以修订版 BSD 许可证授权，详见仓库 LICENSE。JupyterLab 是 Project Jupyter 的一部分，由开放社区开发，维护团队受 Jupyter Frontends Council 治理，决策型贡献者与代码贡献者分别可见于团队名录与贡献者图谱。

总结

从pip install jupyterlab到jupyter lab，再到通过--core-mode/--dev-mode/--app-dir切换运行形态、借助 prebuilt 扩展与 npm 源码扩展搭建个性化环境，JupyterLab 提供了一条从"拿来即用"到"深度定制"的完整路径。理解 jupyterlab/labapp.py 中的三种运行模式与构建/清理/路径等子命令、pyproject.toml 中的扩展管理器入口点，以及packages/下的前端模块化结构，将帮助你更高效地使用、排查和扩展这套计算环境。

【免费下载链接】jupyterlabJupyterLab computational environment.项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlab