JupyterLite常见问题排查指南

JupyterLite常见问题排查指南

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

文件访问问题

在JupyterLite中，用户可能会遇到从内核访问文件浏览器中显示的文件时出现错误的情况。典型错误如下：

FileNotFoundError: [Errno 44] No such file or directory: 'data/iris.csv'

问题原因

这种情况通常发生在内核尚未完全准备就绪时就执行代码的情况下。JupyterLite使用Service Worker技术来实现从内核访问文件的功能，但在某些情况下Service Worker可能无法正确注册。

解决方案

1. 等待内核准备就绪：在执行代码前，确保内核状态指示器显示为就绪状态
2. 更换浏览器：目前推荐使用最新版的Chrome或Firefox。注意Firefox隐私窗口不支持Service Worker
3. 清除浏览器缓存：这有助于清除可能残留的旧版Service Worker注册信息

浏览器数据清理

JupyterLite默认将文件浏览器内容和用户设置存储在浏览器的本地存储中。如需清理这些数据，可通过以下方式：

1. 使用快捷键打开命令面板(Ctrl+Shift+C或Cmd+Shift+C)，搜索"Clear Browser Data"
2. 通过菜单项："Help > Clear Browser Data"
3. 右键点击文件浏览器，选择"Clear Browser Data"

重要警告：此操作将永久删除浏览器中存储的所有数据，且无法恢复。

WebAssembly内核的包兼容性

JupyterLite在浏览器中使用WebAssembly运行Python内核，这与传统的服务器端JupyterLab环境有显著差异。目前支持两种主要Python内核：

内核类型

1. Pyodide内核：

   • 专为浏览器设计的Python发行版
   • 包含大量预编译为WebAssembly的包
   • 安装新包命令：%pip install mypackage

2. Xeus Python内核：

   • 基于emscripten-forge的包分发系统
   • 安装新包命令：%mamba install mypackage或%pip install mypackage

兼容性测试方法

安装包后，可通过以下代码测试兼容性：

import mypackage
# 尝试使用基本功能确保正常工作

常见限制

WebAssembly环境下可能不兼容的包类型：

• 需要原生C扩展但未编译为WebAssembly的包
• 依赖浏览器环境中不可用的系统库的包
• 使用WebAssembly不支持的线程或多进程功能的包
• 访问文件系统方式与浏览器沙箱不兼容的包

遇到不兼容的包时，建议寻找纯Python替代方案或专为WebAssembly环境编译的包版本。

内核日志访问

JupyterLite提供了多种查看内核日志的方式：

1. 使用快捷键打开命令面板，搜索"Show Log Console"
2. 通过菜单项："View > Show Log Console"
3. 点击笔记本工具栏中的日志控制台图标

日志级别配置

默认显示"warning"及以上级别的日志。如需查看更详细的日志：

1. 通过"Settings > Settings Editor"搜索"Log Console"
2. 或在配置文件中设置默认日志级别：

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "@jupyterlab/logconsole-extension:plugin": {
      "defaultLogLevel": "info"
    }
  }
}

可用日志级别包括：

• critical：仅关键错误
• error：错误和关键消息
• warning：警告及以上（默认）
• info：信息及以上
• debug：包括调试信息的所有消息

内核状态指示

笔记本工具栏中的内核状态图标会显示当前状态：

• 忙碌状态：显示旋转图标
• 空闲状态：显示对勾图标
• 严重错误：显示红色叉图标

点击状态图标可直接打开日志控制台查看详细信息。

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