解决 uv run jupyter notebook 启动时打开错误应用的问题

最近在使用 uv 管理 Python 项目时，执行 uv run jupyter notebook 遇到了一个奇怪的问题：Jupyter 没有像往常一样打开浏览器，而是启动了一个其他应用（比如某个编辑器或下载器），或者弹出一个“如何打开此链接”的对话框。这到底是怎么回事？又该如何解决呢？本文将为你详细剖析原因并提供三种有效的解决方法。

原因分析

这个问题的根源并不在于 uv，而是 Jupyter 的自动打开浏览器机制与操作系统的默认程序设置发生了冲突。

当你在终端中运行 jupyter notebook 时，Jupyter 会在本地启动一个服务器，并尝试自动打开你的默认 Web 浏览器来访问该服务器（通常是 http://localhost:8888）。操作系统在收到“打开一个网址”的请求时，会查询当前哪个程序被设置为处理 http:// 和 https:// 协议的默认程序。如果这个默认程序被错误地设置成了其他应用（例如代码编辑器、下载工具等），那么操作系统就会启动那个应用，而不是浏览器，从而导致了上述现象。

这种情况通常在以下场景中出现：

系统更新或重置后，默认应用设置被重置。
安装了某些会“劫持”协议关联的软件（如某些下载工具、编辑器）。
用户手动将某个应用设为 HTTP 协议的默认处理程序。

解决方案

针对这个问题，我提供了三种解决方案，你可以根据自己的情况选择最适合的一种。

方案一：使用 `--no-browser` 参数（最快捷）

这是最简单直接的方法。在启动 Jupyter 时加上 --no-browser 参数，Jupyter 就不会尝试打开任何程序，只会在终端中输出访问链接，你可以手动复制链接到浏览器中打开。

uv run jupyter notebook --no-browser

如果你使用的是 JupyterLab：

uv run jupyter lab --no-browser

启动后，终端会显示类似下面的信息：

    To access the notebook, open this file in a browser:
        file:///.../.../nbserver-xxx-open.html
    Or copy and paste one of these URLs:
        http://localhost:8888/?token=xxxxxxxxxxxxxxxx

直接复制 http://localhost:8888/... 链接到你喜欢的浏览器地址栏即可。

优点：无需修改任何配置，立即生效。
缺点：每次启动都需要手动输入参数或复制链接。

方案二：检查和修复系统默认浏览器设置（根本解决）

如果你希望 Jupyter 能像往常一样自动打开浏览器，那就需要检查并修复操作系统的默认应用设置，确保 http:// 和 https:// 协议关联到正确的浏览器。

Windows 10/11

打开设置 > 应用 > 默认应用。
在“Web 浏览器”中，选择你常用的浏览器（如 Chrome、Edge、Firefox 等）。
向下滚动，点击 按协议指定默认应用。
找到 HTTP 和 HTTPS 协议，分别确保它们关联的是同一个浏览器。

macOS

打开 系统设置（或系统偏好设置）。
点击 桌面与程序坞（或通用）。
找到 默认网页浏览器 选项，选择你喜欢的浏览器。
更彻底的方法：在 Finder 中选中一个 .html 文件，右键选择 显示简介，在“打开方式”中选择浏览器并点击“全部更改”。这有助于确保文件关联和协议关联一致。

Linux (以 Ubuntu/GNOME 为例)

打开设置 > 应用程序 > 默认应用程序。
在网页或 Internet 类别中，选择你想要的浏览器。
也可以使用命令行工具 xdg-open 来测试和设置默认程序：
- 测试 xdg-open http://localhost 实际打开的是什么。
- 如果不对，可以用 xdg-settings set default-web-browser <浏览器.desktop> 来修改。例如：
```
xdg-settings set default-web-browser google-chrome.desktop
```

完成以上设置后，再次运行 uv run jupyter notebook，应该就能正常打开浏览器了。

优点：从根本上修复了协议关联问题，不仅解决 Jupyter，也解决其他依赖浏览器打开的应用。
缺点：需要根据操作系统进行几步设置，稍微有些繁琐。

方案三：修改 Jupyter 配置文件，永久禁用自动打开浏览器

如果你希望一劳永逸地禁止 Jupyter 自动打开浏览器（类似方案一的效果），可以通过修改 Jupyter 的配置文件来实现。

生成配置文件（如果还没有生成过）：
```
jupyter notebook --generate-config
```
这会在你的用户目录下生成一个配置文件，路径通常为：
- Linux/macOS: ~/.jupyter/jupyter_notebook_config.py
- Windows: C:\Users\你的用户名\.jupyter\jupyter_notebook_config.py
编辑配置文件，找到下面这行（可能被注释掉）：
```
# c.ServerApp.open_browser = True
```
将其改为：
```
c.ServerApp.open_browser = False
```
确保去掉前面的 # 注释符号。
保存文件。之后每次启动 Jupyter 都不会尝试打开浏览器，只会在终端输出访问链接。

优点：一次修改，永久生效。
缺点：需要手动编辑配置文件，且之后永远需要手动复制链接。

总结

遇到 uv run jupyter notebook 启动后打开错误应用的问题，不用慌张，这通常是操作系统协议关联错乱导致的。你可以：

临时使用 --no-browser 参数快速开始工作；
永久修复系统默认浏览器设置，一劳永逸；
或修改 Jupyter 配置，让 Jupyter 不再尝试打开浏览器。