VS Code Jupyter 内核启动超时解决方案

🛠️ VS Code Jupyter 内核启动超时问题报告

1. 问题现象描述 (Problem Description)

在 Windows 环境下，使用 VS Code 的 Jupyter 插件运行 .ipynb 文件或启动交互式窗口时，系统卡死并弹出以下错误提示：

“由于等待端口使用超时，无法启动内核 'venv (3.13.x) (Python 3.13.x)'。查看 Jupyter log 了解更多详细信息。”

2. 根本原因分析 (Root Cause Analysis)

1. Python 3.13 底层架构不兼容：Python 3.13 对底层的 asyncio 事件循环和安全套接字进行了重大重构。VS Code 的 Jupyter 插件目前在处理 Python 3.13 的底层 TCP/ZMQ 端口握手机制时存在兼容性硬伤，导致无法正常建立本地通信管道。
2. 多虚拟环境冲突/污染：项目根目录下同时存在 .venv 和 venv 两个环境。Jupyter 内核依赖包（ipykernel）装在 venv 中，而 VS Code 默认优先识别并缓存了未完整配置的 .venv，在切换环境和清理缓存时导致底层端口被死锁。

---

3. 应急临时方案 (Workarounds)

如果当前有紧急项目任务，可以采用以下两种方案完全绕过 VS Code 插件的通信 Bug，恢复代码运行：

💡 方案一：转为普通的 Python 终端交互（无需 Jupyter 组件）

将代码脱离 .ipynb 格式，直接在标准的 Python 环境中运行。

• 操作步骤：

  1. 在项目中新建一个标准的 .py 文本文件（例如 test.py）。
  2. 将原先的测试代码复制到该 .py 文件中。
  3. 选中代码行，按下键盘 Shift + Enter（或右键选择“在终端中运行选定文本”）。

• 优点：直接在 Windows Terminal/PowerShell 运行，完全不经过 Jupyter 的 TCP 端口层，100% 免疫超时错误。

🌐 方案二：启动原生的浏览器版 Jupyter Notebook（保留完整交互）

Python 3.13 本身运行 Jupyter 是没有问题的，出问题的是 VS Code 的连接插件。直接使用浏览器运行可以保留所有的格子和图表交互。

• 操作步骤：

  1. 在 VS Code 终端中激活包含依赖的虚拟环境：venv\Scripts\Activate.ps1。
  2. 终端中直接输入并运行命令：jupyter notebook。
  3. 此时系统会自动弹窗或在浏览器中打开 Jupyter 网页端。
  4. 在浏览器中直接点开你的 .ipynb 文件进行开发。

• 优点：完美保留 .ipynb 的可视化、代码格分块运行以及画图功能，内核可实现秒级启动。

---

4. 长远及根本解决方案 (Permanent Fixes)

为了在 VS Code 内部恢复原本顺畅的 .ipynb 笔记本开发体验，建议后续执行以下彻底修复：

🔨 步骤一：环境大清洗与版本降级（最推荐）

鉴于 Python 3.13 过于激进且生态未完全适配，降级到工业界目前最成熟、兼容性最好的 Python 3.12 是最省心的做法。

1. 彻底清理旧环境：在文件管理器中，直接物理删除项目根目录下的 venv 和 .venv 两个文件夹。

2. 安装稳定版 Python：前往 Python 官网下载并安装 Python 3.12.x。

3. 彻底清除 VS Code 缓存：

   • 关闭 VS Code，按 Win + R 键输入 %APPDATA%\Code\User，直接删除 workspaceStorage 文件夹（重置窗口缓存）。
   • 前往本地用户目录（C:\Users\你的用户名），删除隐藏的 .jupyter 和 .ipython 文件夹。

🔨 步骤二：规范重建单一虚拟环境

重新打开项目，确保只保留一个干净、规范的虚拟环境。

1. 在 VS Code 终端中基于 Python 3.12 创建新环境：

   python -m venv .venv
   

2. 激活新环境：

   .venv\Scripts\Activate.ps1
   

3. 重新安装所需的 Jupyter 核心组件与项目依赖：

   pip install --upgrade ipykernel jupyter pandas numpy
   

4. 重新打开 .ipynb 文件，在右上角将内核精准绑定到这个全新的 (.venv) 环境，即可彻底解决端口超时 Bug。