JupyterLite 版本迁移指南：从旧版本平滑升级到新版本

JupyterLite 版本迁移指南：从旧版本平滑升级到新版本

jupyterlite Wasm powered Jupyter running in the browser 💡 项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlite

前言

JupyterLite 作为一个基于浏览器的轻量级 Jupyter 环境，随着版本的迭代会引入新功能和改进，同时也可能带来一些不兼容的变化。本文将为开发者和管理员提供详细的迁移指南，帮助您了解从旧版本升级到新版本时需要注意的关键变化和必要的调整步骤。

从 0.5.0 升级到 0.6.0

重要变更概述

0.6.0 版本基于 JupyterLab 4.4 和 Jupyter Notebook 7.4 构建，包含了一些架构上的重大变化：

1. 插件系统统一化
2. 存储机制改进
3. API 重构

扩展兼容性

由于底层框架升级，您现有的扩展可能需要更新才能兼容新版本。建议检查以下方面：

• 扩展是否支持 JupyterLab 4.4
• 扩展是否依赖已移除的 API
• 扩展是否需要重新打包

内容管理变更

文件索引依赖

现在构建时如果指定了内容目录但未安装 jupyter-server 依赖，构建将直接失败而不是仅显示警告。这有助于及早发现问题。

解决方案：

pip install jupyter-server

浏览器存储隔离

旧版本中所有 JupyterLite 实例共享相同的浏览器存储空间，现在改为基于部署路径隔离存储：

• 旧存储键：JupyterLite Storage
• 新存储键：JupyterLite Storage - /your-deploy-path

如需保持旧行为，可在配置中添加：

{
  "jupyter-config-data": {
    "contentsStorageName": "JupyterLite Storage"
  }
}

设置存储变更

与内容存储类似，用户设置现在也基于部署路径隔离。如需恢复旧行为：

{
  "jupyter-config-data": {
    "settingsStorageName": "JupyterLite Storage"
  }
}

API 架构重构

插件系统统一

旧版本区分常规插件和服务器插件，现在全部统一为 JupyterFrontEndPlugin。

迁移自定义内核示例：

// 旧版
const kernel: JupyterLiteServerPlugin<void> = {
  id: 'my-kernel:plugin',
  activate: (app: JupyterLiteServer) => { /*...*/ }
}

// 新版
const kernel: JupyterFrontEndPlugin<void> = {
  id: 'my-kernel:plugin',
  activate: (app: JupyterFrontEnd) => { /*...*/ }
}

服务工作者变更

服务工作者管理已移至 @jupyterlite/application-extension 包。如需禁用：

{
  "disabledExtensions": ["@jupyterlite/application-extension:service-worker-manager"]
}

通信协议也从 /api/drive.v1 变更为 /sw-api.v1。

废弃和移除的包

• @jupyterlite/licenses 包已完全移除
• @jupyterlite/server-extension 包功能迁移到 @jupyterlite/services-extension
• @jupyterlite/translation 包功能由 JupyterLab 原生支持

从 0.4.0 升级到 0.5.0

框架升级

基于 JupyterLab 4.3 和 Notebook 7.3，建议检查扩展兼容性。

Python 要求变更

jupyterlite-core 现在需要 Python 3.9+，不再支持 3.8。

内核接口变更

IKernel 接口新增 changed 信号，用于通知内核状态变化。

从 0.3.0 升级到 0.4.0

文件访问改进

引入 SharedArrayBuffer 实现更可靠的文件访问机制，需配置 COOP/COEP 头：

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

内容管理 API 变更

IEmscriptenNodeOps 接口现在支持更多节点类型，驱动请求类型系统也更精确。

从 0.2.0 升级到 0.3.0

服务工作者缓存

默认禁用缓存以避免常见问题，如需启用：

{
  "jupyter-config-data": {
    "enableServiceWorkerCache": true
  }
}

从 0.1.0 升级到 0.2.0

框架升级

迁移到 JupyterLab 4 和 Notebook 7，需确保扩展兼容新版本。

元包变更

不再默认包含 Pyodide 内核，需显式安装：

pip install jupyterlite-pyodide-kernel

最佳实践建议

1. 测试环境先行：先在测试环境验证升级效果
2. 逐步升级：建议按版本顺序逐步升级而非跨版本
3. 备份配置：升级前备份所有自定义配置
4. 监控日志：升级后密切关注控制台日志
5. 用户通知：提前告知用户可能的存储变更

通过遵循本指南，您应该能够顺利完成 JupyterLite 的版本升级，同时最小化对现有用户和工作流程的影响。

jupyterlite Wasm powered Jupyter running in the browser 💡 项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlite