vscode运行jupyter notebook的核心卡点是ipykernel注册、环境绑定及远程模式干扰。需安装microsoft官方jupyter扩展（ms-toolsai.jupyter）并启用python扩展，重启后测试命令；内核为空则检查ipykernel是否安装并用--user参数注册；卡在“connecting to kernel…”须关闭jupyter: enable remote并启用local kernel specs only；modulenotfounderror需确认所选内核与解释器一致。
VSCode 能跑 Jupyter Notebook，但不是装完扩展就自动好使——核心卡点永远在 ipykernel 是否注册、是否绑定对环境、是否被远程模式干扰。其他都是表象。
打不开 .ipynb 文件或只显示 JSON 源码
这说明 ms-toolsai.jupyter 扩展根本没加载，和 Python 环境无关。
- 必须安装 Microsoft 官方 Jupyter 扩展（ID：
ms-toolsai.jupyter），仅装 Python 扩展不够 - 安装后务必重启 VS Code，或按
Ctrl+Shift+P输入Jupyter: Select Interpreter测试命令是否存在；若提示Command 'Jupyter: Select Interpreter' not found，说明扩展静默失败，需重装 - 检查扩展面板里 Python 扩展是否也已启用——新版 Jupyter 扩展依赖它提供解释器桥接，两者缺一不可
右上角内核选择器为空或显示 “Python 3 (unavailable)”
VS Code 找到了 Python 解释器路径，但该环境里没有可通信的内核进程。90% 是漏了 ipykernel 或注册失败。
- 先在目标环境终端中运行：
python -m pip list | grep ipykernel（macOS/Linux）或python -m pip list | findstr ipykernel（Windows）；无输出就立刻执行python -m pip install ipykernel - 注册命令必须带
--user：python -m ipykernel install --user --name myenv --display-name "Python (myenv)"；不加--user可能写入系统级目录，VS Code 无权读取 -
--name不能含空格或特殊字符，否则注册会静默失败；--display-name才是下拉菜单里看到的名字 - 注册后别忘了点右上角内核选择器旁的刷新按钮，或执行
Developer: Reload Window
单元格运行卡在 “Connecting to kernel…”
VS Code 正在尝试连接远程 Jupyter Server，而非本地内核。这是默认行为被误触发的典型表现。
- 打开设置（
Ctrl+,），搜索jupyter: enable remote，关闭Jupyter: Enable Remote - 同时启用
Jupyter: Local Kernel Specs Only，强制只读取本地注册的 kernel - 检查工作区设置（
.vscode/settings.json）里有没有"jupyter.jupyterServerType": "remote"或"jupyter.remoteJupyterServerUri"，有就删掉 - 禁用所有非官方 Jupyter 类扩展（如第三方 kernel 管理器）
选对了内核却报 ModuleNotFoundError
这不是包没装，是当前 Notebook 绑定的内核和你期望的环境不一致。VSCode 左上角显示的内核名称（比如 Python 3.11.5 ('base': conda)）才是真实执行环境，跟当前打开的 .py 文件或文件夹无关。
- 点击右上角内核名称，从下拉列表中手动选中你实际想用的环境（带
--user或具体 env 名的那个） - 如果目标环境没出现在列表里，说明它没注册内核：进该环境，运行
python -m ipykernel install --user --name project-env --display-name "Python (project-env)" - 运行单元格前，先执行
import sys; print(sys.executable)，确认路径是否与你选中的 interpreter 一致；如果不一致，说明 kernel 没绑定对 —— 删除~/.local/share/jupyter/kernels/（Linux/macOS）或%USERPROFILE%\AppData\Roaming\jupyter\kernels\（Windows）下旧的 kernel 目录，重新注册
真正容易被忽略的是：VSCode 不会自动把 .venv 映射为 Notebook 内核，必须显式注册；而且注册命令要进虚拟环境执行，--name 最好用项目名，避免多个 .venv 冲突；注册一次后只要路径不变，后续打开同项目就可复用，不用每次重装。
