故障排除#

无法从内核访问文件#

JupyterLite 允许您从内核中访问文件浏览器中显示的文件。

但是，在某些情况下，您可能会看到以下错误

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

a screenshot showing an error while trying to access a local file from the kernel

这似乎发生在内核完全准备好之前执行代码时。请参阅问题 #1371。如果这种情况经常发生，请尝试等到内核指示器准备就绪后再开始执行代码。

JupyterLite 使用Service Worker 允许从内核访问文件。但在某些情况下，Service Worker 可能无法注册，这会在开发工具控制台中显示错误

image

要解决此问题，您可以尝试以下操作

  • 使用不同的浏览器。目前我们支持最新的 Chrome 和 Firefox 版本。但已知 Firefox 私密窗口不支持 Service Worker。

  • 清除浏览器缓存。这有助于清除可能仍然注册的旧版本 Service Worker，例如在 JupyterLite 版本更新之后。

有关更多信息，请参阅内容 文档。

清除浏览器数据#

默认情况下，JupyterLite 将文件浏览器和用户设置的内容存储在浏览器的本地存储中。

如果您想清除所有文件和设置，您可以通过以下选项使用 清除浏览器数据 命令

  • 打开命令面板 (Ctrl + Shift + C 或 Cmd + Shift + C) 并搜索 清除浏览器数据。

  • 点击菜单项：帮助 > 清除浏览器数据。

  • 右键点击文件浏览器并选择 清除浏览器数据。

警告

清除浏览器数据将永久删除存储在您浏览器中的数据。此操作无法撤消。

软件包与 WebAssembly 内核的兼容性#

JupyterLite 使用 WebAssembly 在浏览器中运行 Python 内核，这与在服务器上运行的常规 JupyterLab 设置不同。这意味着并非所有在标准 Python 环境中工作的 Python 软件包都能在 JupyterLite 中工作。

JupyterLite 中可用的两个主要 Python 内核是

  • Pyodide：一个用于浏览器的 Python 分发版，包含大量编译为 WebAssembly 的软件包。

  • Xeus Python：一个利用 emscripten-forge 获取软件包的 Python 内核，emscripten-forge 是一个为 WebAssembly 量身定制的 conda 软件包分发版。

测试软件包兼容性#

要检查软件包是否与这些内核兼容，您可以直接在浏览器中进行测试

对于 Pyodide 内核

  • 尝试 Pyodide REPL

  • 使用以下命令安装软件包：%pip install mypackage

对于 Xeus Python 内核

  • 尝试 Xeus Python REPL

  • 使用以下命令安装软件包：%mamba install mypackage 或 %pip install mypackage

测试安装

安装软件包后，通过尝试导入它来测试它是否工作

import mypackage
# Try using some basic functionality to ensure it works correctly

如果导入成功且没有错误，则该软件包可能与 WebAssembly 环境兼容。

常见限制#

使用基于 WebAssembly 的内核时，您可能会遇到软件包的限制，这些软件包

  • 需要未编译为 WebAssembly 的原生 C 扩展

  • 依赖于浏览器环境中不可用的系统库

  • 使用 WebAssembly 不支持的线程或多进程功能

  • 以与浏览器沙盒不兼容的方式访问文件系统

如果某个软件包无法工作，请考虑寻找纯 Python 替代方案或专门为 WebAssembly 环境编译的软件包。否则请联系相应项目的维护者

访问内核日志#

如果您使用的内核将日志报告到日志控制台，您可以通过以下选项打开日志控制台来查看这些日志

  • 打开命令面板 (Ctrl + Shift + C 或 Cmd + Shift + C) 并搜索 显示日志控制台。

  • 点击菜单项：视图 > 显示日志控制台。

  • 点击笔记本工具栏中的工具栏项。

笔记本工具栏中的内核状态项也将显示内核的状态。如果内核繁忙，它将显示一个旋转器。如果内核空闲，它将显示一个勾号。如果内核报告 严重 错误，它将显示一个红叉。点击内核状态项将打开日志控制台。

a screenshot showing the kernel status notebook toolbar item and the log console in JupyterLite

注意

如果您只想保留内核状态项（显示旋转器和 ✅ 的那个），并禁用默认提供的内核执行指示器，请将以下内容放入您的 jupyter-lite.json 文件中

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "disabledExtensions": [
      "@jupyterlab/notebook-extension:execution-indicator"
    ]
  }
}