VSCode如何搭建Jupyter Notebook数据分析环境

VSCode中Jupyter Notebook跑不起来，90%以上因内核未注册或未连上：需先选对Python解释器，再在该环境安装ipykernel并执行python -m ipykernel install --user --name myproject --display-name "Python (myproject)"，最后重启VS Code窗口。

遇到VSCode跑不起来Jupyter Notebook的情况，先别急着怀疑插件。十有八九，问题出在内核上——要么是内核根本没注册到当前的Python环境里，要么就是VS Code压根没连上它。总结下来，选错解释器、漏装ipykernel、注册命令少了--user参数，或者路径里带了空格，这四类原因几乎包揽了九成以上的失败案例。

Python 解释器选错，Notebook 就压根启动不了

这里有个关键点：VS Code不会跨环境去寻找jupyter或ipykernel。它只认你当前选中的那个解释器里到底装了些什么。所以，即便你在系统全局环境里用pip install jupyter装好了，只要VS Code当前选中的是./venv/bin/python这个虚拟环境，而这个环境里恰恰没有ipykernel，那么右上角的内核选择器要么显示“Python 3 (una vailable)”，要么干脆就是一片空白。

• 按下Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（Mac），调出命令面板，输入并执行Python: Select Interpreter。
• 从弹出的列表里，准确找到并选中目标环境的路径。比如Linux/macOS下的./venv/bin/python，或者Windows下的.\.venv\Scripts\python.exe。
• 如果列表里压根看不到你的环境，别瞎猜。最直接的办法是：先在终端里激活那个环境，然后运行python -m pip list | grep ipykernel（macOS/Linux）或者python -m pip list | findstr ipykernel（Windows），确认ipykernel是否已经安装到位。

ipykernel 没装或注册失败，内核就“不可用”

光安装jupyter是不够的，真正让Python环境变成一个能与Notebook通信的内核，靠的是ipykernel。这里有两个操作要点：首先，注册命令必须在目标环境中执行；其次，--user这个参数绝对不能省。少了它，内核文件可能会被写入系统级目录，而VS Code很可能没有读取权限。

• 在已经激活的目标环境终端里，运行：python -m pip install ipykernel（注意：如果用的是pip管理的环境，就别混用conda install ipykernel）。
• 接着运行注册命令：python -m ipykernel install --user --name myproject --display-name "Python (myproject)"。记住，--name后面跟的内核名称不能包含空格或中文，而--display-name才是你在VS Code下拉菜单里看到的那个友好名称。
• 怎么验证注册成功了呢？运行jupyter kernelspec list，如果输出列表里出现了类似myproject /home/xxx/.local/share/jupyter/kernels/myproject这样的条目，那就对了。
• 完成注册后，必须彻底重启VS Code窗口（不是点击“重载窗口”），否则新注册的内核不会出现在选择列表里。

右上角内核选择器里找不到名字，或点了没反应

遇到这种情况，通常不是VS Code没扫描到，而是它只认固定路径下的内核定义文件。这个路径在Linux/macOS下是~/.local/share/jupyter/kernels/，在Windows下是%USERPROFILE%\AppData\Roaming\jupyter\kernels\。如果注册时漏了--user，或者--name里不小心包含了空格，都可能导致VS Code解析失败。

• 检查一下工作区设置：打开settings.json，看看里面是不是误配了"jupyter.jupyterServerType": "remote"，或者填了remoteJupyterServerUri。这会让VS Code强制进入远程模式，从而直接忽略本地内核。
• 尝试关闭设置项Jupyter: Enable Remote，同时启用Jupyter: Local Kernel Specs Only（直接在设置里搜索这两项即可）。
• 如果之前注册过同名的内核，最好先清理掉：运行jupyter kernelspec remove myproject，然后重新执行安装注册流程。
• 最后，确保ms-toolsai.jupyter和ms-python.python这两个扩展都已经启用。缺少任何一个，Notebook都无法成功绑定内核。

Shift+Enter 没反应，或报 ModuleNotFoundError

这通常不是快捷键失灵了，而是当前单元格实际运行的Python解释器，和你心里想的那个不是同一个。真正起作用的执行环境，要看VS Code左上角显示的内核名称，比如Python 3.11.5 ('myproject': venv)。

• 在单元格里运行import sys; print(sys.executable)，确认打印出的路径是否指向你选中的那个解释器（例如./venv/bin/python）。
• 如果路径不一致，那基本就是内核绑定错位了。可能的原因包括：你在base环境注册了内核，却想在子环境里使用；或者内核配置文件kernel.json里的argv[0]指向了错误的python可执行文件。
• 手动检查一下内核配置文件。路径通常是~/.local/share/jupyter/kernels/myproject/kernel.json（Linux/macOS）或Windows下的对应位置，确认argv数组的第一项是正确的Python解释器路径。
• 避免在全局环境安装ipykernel：注册命令一定要在目标环境中执行，而不是在base环境装完，再切换到子环境去用。

说到底，真正卡住人的，往往不是“怎么打开notebook”这个第一步，而是内核启动时，sys.executable指向的路径和你选中的解释器路径对不上号。这个细节极其容易被忽略，但它恰恰是绝大多数ModuleNotFoundError和“点了没反应”问题的根源所在。