Anaconda+VSCode+Jupyter Notebook 安装配置与虚拟环境实战指南

现在入坑还不晚Anaconda VSCode Jupyter Notebook 安装及使用全记录我在帮不少朋友配 Python 环境时发现一个现象很多人不是不会写代码而是被“环境”卡住了。Anaconda、VSCode、Jupyter Notebook 这三样东西单独拆开看都不难但装到一起、配合起来用坑是真的不少。尤其当你装完 Jupyter Notebook 却打不开浏览器、写完单元格点运行没反应、导入包报 DLL 错误时那感觉比写不出代码还憋屈。这篇文章我想把一套完整的 Anaconda VSCode Jupyter Notebook 安装和使用过程讲清楚包括我踩过的坑、换源加速的技巧、虚拟环境的隔离逻辑以及最后那份“问题速查清单”。不管你是刚入门的 Python 新手还是换了新电脑想重新配环境的老手照着这篇文章走一遍基本不会再发怵。1. 搭建前的整体思路为什么要用这一套组合1.1 三个工具的分工先搞清楚这三个东西分别干什么后面遇到问题才不会被绕晕。Anaconda 是一个 Python 发行版它的核心价值不只是“帮你装 Python”而是带着一堆常用的科学计算包并且原生提供环境管理能力。VSCode 是编辑器负责写代码、调试代码、装各种插件。Jupyter Notebook 是一种交互式笔记本代码可以分块执行结果直接显示在页面里特别适合数据探索和分析。这三者的关系可以用一句话概括Anaconda 提供 Python 解释器和独立环境VSCode 是编辑和调试的前端Jupyter Notebook 则是交互式执行容器。解释器是引擎VSCode 是方向盘Notebook 是仪表盘。很多人配完发现代码运行不了多半是“引擎挂错了”也就是 VSCode 或 Jupyter 连到了一个不是你预期那套环境上。1.2 安装前的准备工作版本选择和下载渠道我建议无论你是 Windows 还是 macOS都下载 Anaconda 官网的 Individual Edition 最新版Python 3.9 或 Python 3.10 系列即可。也别盲目追求最新版本有些第三方包还没来得及适配最新 Python 小版本装上去全是编译报错纯浪费生命。下载渠道我要多说一句Anaconda 官网的服务器在海外国内下载速度经常慢到怀疑人生。速度慢的时候用清华大学开源软件镜像站下载 Anaconda 安装包速度快得多版本也全。VSCode 从官网下载就好这个服务器一般都不慢。Jupyter Notebook 不需要单独去找下载包Anaconda 默认自带后面在环境里用 conda 安装或 pip 安装都行。记住这一点接下来的路会顺很多。2. Anaconda 安装与国内镜像配置2.1 安装 Anaconda 的完整步骤Anaconda 的安装过程本身不复杂但有几个选项容易忽略。Windows 下双击安装包后到了 Advanced Installation Options 这一步我建议勾选 Register Anaconda as my default Python 3.9。当然这个选项在几乎所有版本里默认都不勾选但你仍然需要留意。因为它决定你能否直接在命令行里全局识别 conda 和 python。如果你不想勾选系统级注册也可以勾选了以后所有命令都在 Anaconda Prompt 里用效果一样。安装路径默认在 C 盘用户目录下比如 C:\Users\你的用户名\anaconda3。没事别把它改成带中文或带空格的路径后面装包的阶段经常因为这个出幺蛾子。macOS 用户在安装完图形化安装包后还需要在终端里初始化 conda通常安装包最后会提醒你跑conda init照做就行。装完后先验证一下环境是否正常。打开终端Windows 用户打开 Anaconda PromptmacOS 和 Linux 用户打开终端依次输入conda --version python --version正常情况下会输出 conda 的版本号和 Python 版本号。如果提示找不到命令大概率是环境变量的问题。Windows 用户需要手动把C:\Users\你的用户名\anaconda3和C:\Users\你的用户名\anaconda3\Scripts加入系统环境变量 PathmacOS 和 Linux 用户一般写入~/.bashrc或~/.zshrc加上export PATH/Users/你的用户名/anaconda3/bin:$PATH即可。注意环境变量修改后要新开一个终端窗口才会生效不用反复重启电脑。实测很多“装完 conda 还是找不到”的报错都是因为没开新终端。2.2 配置国内镜像源与更换加速原理Anaconda 默认的软件源在国外你用 conda 装包的时候经常会出现进度条卡住、网络中断、下载速度几 KB 的情况。解决方案很直接把 conda 的下载源指向清华或阿里云的镜像站。以清华源为例在终端里执行下面几条命令conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --set show_channel_urls yes如果想优先级更高还可以把 conda-forge 源加进去不过不建议全量替换因为 conda 在解析依赖时如果所有源都走镜像站偶尔会碰到包缺失的问题。基础包走清华源就够了。同样pip 也可以换到清华的 PyPI 镜像方式是在用户目录下新建或修改pip.iniWindows或~/.pip/pip.confLinux/macOS写入[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple很多人在装 PyTorch 或其他大包时网速很慢换了镜像源后立刻就有一种从拨号上网切到宽带的感觉。注意如果你的 conda 源配置写错了想恢复默认源直接在用户目录下找到.condarc文件删掉即可我经常这么干。2.3 创建虚拟环境把每个项目隔离开Anaconda 安装后自带的 base 环境是默认环境。我强烈建议不要直接在 base 环境里装太多东西而是为每个项目单独创建虚拟环境。虚拟环境说白了就是一个独立的 Python 目录你在里面装什么包都不会影响其他环境也不会污染 base。创建环境的方式很简单conda create -n datascience python3.9这条命令会创建一个叫 datascience 的环境Python 版本指定为 3.9。创建完成后激活环境conda activate datascience激活后命令行前面会显示(datascience)代表当前已经在虚拟环境里。在这个环境里安装的所有包都会被隔离在对应的目录下。如果某个项目的包依赖冲突了直接删掉环境重新创建就行一点都不心疼conda remove -n datascience --all我的习惯是每个项目建一个环境环境命名按项目类型走比如爬虫项目就叫 spider机器学习项目就叫 ml。这样后期想找环境、删环境都一目了然。你在装 Jupyter Notebook 时也要注意它默认是装在 base 或者你当前激活的环境里后面要用哪个环境跑代码最好在那个环境里也装一份对应的 ipykernel。3. VSCode 安装、汉化与 Python 插件配置3.1 安装 VSCode 与汉化设置VSCode 的安装相对省心官网下载对应系统安装包双击安装一路 Next 即可。安装时有个选项叫“添加到 PATH”一定勾选上。没勾的话你以后在终端里敲code .是没反应的虽然不影响打开 VSCode 本身但少了高效入口挺可惜。装完 VSCode 后的第一件事我一般先做两件汉化和安装 Python 插件。汉化打开左侧扩展商店搜索“Chinese (Simplified)”安装微软官方的中文语言包然后按提示重启窗口就变成中文了。你也可以在语言设置里显式配置locale为zh-cn不过插件方式更省事。第三件事是安装几个核心插件Python、Pylance、Jupyter。Python 和 Pylance 是微软官方出品负责代码高亮、语法检查和智能提示Jupyter 插件负责让 VSCode 能直接打开和编辑 .ipynb 文件。很多人以为装完 Anaconda 就能在 VSCode 里跑 Jupyter Notebook实际上不装 Jupyter 插件的话VSCode 只能把 .ipynb 当普通 JSON 文件打开完全没法用。3.2 Python 解释器与内核选择VSCode 里的 Python 解释器选择是几乎所有新手都会踩坑的地方。你在 VSCode 底部状态栏能看到一个显示 Python 版本号的按钮点击后会弹出可用解释器列表。这里会列出 base 环境、你创建的 datascience 环境以及系统里其他 Python 安装路径。关键来了你必须选中你刚创建的那个虚拟环境。如果选了 base 或系统 Python你在这个项目里导入的包可能全部找不到。为什么因为每个虚拟环境有自己的 site-packages 目录你在 datascience 环境里装了 pandas跑到 base 环境里用自然就报 ModuleNotFoundError。选择解释器之后记得打开一个 Python 文件输入import sys; print(sys.executable)运行一下看看当前实际用的 Python 路径是否指向你选的环境目录。这是最简单的验证方式。如果输出路径不对说明 VSCode 的任务关联还没切换到位需要重新选择解释器或者重启 VSCode 窗口。3.3 踩坑解释器选错导致模块导不进来关于解释器选错这个问题我再多写两句因为这是我替别人排查最多的问题。现象往往是这样的你在 VSCode 里写了一个脚本import requests然后按 F5 或点运行按钮VSCode 报了ModuleNotFoundError: No module named requests但你在终端里明明用 conda 激活环境后可以正常导入。问题的根源在于 VSCode 的运行按钮默认调用的 Python 解释器不一定是你在终端里激活的那个。终端里的 conda activate 只影响当前终端进程的环境变量VSCode 的运行按钮却由右下角解释器决定。所以就算你在终端里激活了 datascienceVSCode 里没选中 datascience照样导不进包。解决办法有两个一是在 VSCode 命令面板里输入Python: Select Interpreter手动选对环境二是创建项目时在.vscode/settings.json里显式指定{ python.defaultInterpreterPath: C:/Users/你的用户名/anaconda3/envs/datascience/python.exe }这两种方法我推荐第二种因为项目级的配置是固化的换电脑、换同事后只要打开项目就知道用哪个环境。当然路径要用正斜杠。Windows 上如果路径写反斜杠很容易被 JSON 解析成转义符非常坑。4. Jupyter Notebook 安装与在 VSCode 中使用4.1 安装 Jupyter Notebook 与浏览器打开Anaconda 自带 Jupyter Notebook装完 Anaconda 后你可以在开始菜单或终端里直接启动它。在终端或 Anaconda Prompt中输入jupyter notebook命令敲下去正常情况下会自动打开默认浏览器并进入一个以文件列表为首页的页面。这个页面默认路径是你启动命令时所在的目录。所以我建议你专门建一个工作目录比如D:\projects\notebooks在里面启动 Jupyter这样文件管理起来非常干净。如果你之前没用 Anaconda而是用的裸 Python那在安装 Jupyter 时我可以分享一个真实经验。裸 Python 环境下执行pip install jupyter大概率能安装成功但依赖关系会导致某些扩展组件版本不匹配出现“notebook 页面能打开但内核连接失败”的情况此时用 conda 安装同版本依赖的匹配率会更高conda install jupyter notebook这条命令比pip install jupyter更稳妥因为 conda 会在安装前帮你解析依赖冲突。4.2 VSCode 中运行 Notebook 的两种方式在 VSCode 里使用 Notebook主要有两种方式我平时会结合着用。第一种是直接创建 .ipynb 文件。在 VSCode 里按 CtrlShiftP输入Create: New Jupyter Notebook就会生成一个新笔记本。这种方式适合交互式探索单元格写完直接运行结果直接显示在下方。要注意通过界面右上角的“Select Kernel”选择解释器和刚才选择 Python 解释器是同一个逻辑选错环境就会报找不到包。第二种方式是把 .py 文件当作“脚本输出”混合用。VSCode 支持在普通 Python 文件里用# %%分割单元格然后点击“Run Cell”逐段执行。这种模式的优点是代码可以批量运行也能导出成 .py 脚本比 .ipynb 更适合做长期维护的代码。很多老一辈 Python 开发者转用 VSCode 后就特别喜欢这个模式因为它不用离开编辑器就能体验 Notebook 的交互快感。我的建议是做探索性分析用 .ipynb写正式脚本用# %%模式。两者共用同一个内核环境选择规则也一致理解这一点就不会被各种“连接内核失败”的提示搞晕。4.3 代码自动补全与 Markdown 目录语法Jupyter Notebook 在浏览器里敲代码时默认的补全能力是比较弱的经常要按 Tab 才出来。VSCode 里因为集成了 Pylance补全能力会强很多。如果你坚持用网页版 Jupyter建议装一下jupyterlab-lsp和python-lsp-server在 JupyterLab 中体验会比较接近现代补全效果。当然起步阶段我更推荐直接在 VSCode 里用 Notebook补全体验完全不是一个档次。关于 Markdown 目录这个是我每次写分析报告都会用到的功能。Jupyter Notebook 的 Markdown 单元格支持#、##、###标题语法和普通 Markdown 一模一样。但网页版的 Notebook 侧边栏目录需要额外插件比如jupyter_contrib_nbextensions里的 Table of Contents 扩展。安装方式conda install -c conda-forge jupyter_contrib_nbextensions jupyter contrib nbextension install --user装完在 Notebook 主页勾选 Table of Contents 即可。如果你在 VSCode 里用 .ipynb那么自带的大纲窗口就是目录不需要额外配置。目录结构在长文档里真的很重要比如我那份 100 多行的数据清洗报告没有目录翻起来都快崩溃。5. 常见问题与排查实录5.1 Jupyter Notebook 打不开或服务器无响应Jupyter Notebook 安装后在终端输入jupyter notebook报错或页面不能访问是很典型的问题。先说最简单的端口被占用。Jupyter 默认监听 8888 端口如果你之前开过另一个 Jupyter 实例再次启动时会提示端口已被占用。这时候启动命令后面加上--port8889或直接使用--port0让系统自动分配端口即可。再有一种是启动后终端显示一堆日志但浏览器没有自动弹出。这种情况一般不是安装问题而是浏览器没有被默认调用。你只需要手动打开浏览器在地址栏输入http://localhost:8888/tree就能访问。注意别输错成httpsJupyter 默认是http多打一个 s 会直接连接失败。还有一种是服务确实启动了但日志里有[WinError 10061] 由于目标计算机积极拒绝之类的信息这通常是防火墙拦住了端口。在 Windows 防火墙里把 Anaconda 或 Python 加入允许列表基本能解决。macOS 用户如果遇到类似情况检查系统隐私设置里的本地网络权限。5.2 单元格执行没有任何反应这个问题的卦象是你点了运行单元格左侧的In [ ]没有任何变化也不变In [1]也不报错。第一次遇到时我也懵了后来排查下来通常有两个原因。第一个原因是内核没连上。打开 Jupyter 页面后右上角如果显示“Kernel: Disconnected”或者空白说明内核没挂载好。解决方式是点击“Kernel”菜单里的“Restart Clear Output”或者“Change Kernel”重新选择正确的 Python 环境。在 VSCode 里面同理通过“Select Kernel”切换内核。第二个原因是等待时间很长但没有报错。有的包在首次导入时要加载依赖比如import torch就可能要等好几秒甚至十几秒你以为是卡住了其实是在加载。我见过不少朋友点完运行就去泡咖啡回来发现代码其实已经跑完了。要确认是不是在运行看单元格左侧的*符号In [*]表示运行中等它变成In [1]、In [2]之类的数字才算跑完。还有一个常见坑是 Python 代码最后一行是不带输出的表达式比如2 3这种Notebook 会自动显示最后一行结果但如果你把它赋值给了变量比如a 2 3就不显示。这不是运行没反应是 Notebook 的显示规则。5.3 DLL load failed while importing rpds如果你在运行 Jupyter 时碰到类似ImportError: DLL load failed while importing rpds这属于典型的三方包版本冲突问题。rpds 是一个 Python 轮子包往往被某些依赖库间接引用。出现这个错误的根源一般是 conda 或 pip 安装的包版本与实际 Python 架构不匹配尤其是 Windows 上面最明显。我先说简单方案在报错环境中重装这个包用 pip 强制重装指定版本pip uninstall rpds -y pip install rpds0.18.0如果重装后仍然报 DLL 错误就用pip install --force-reinstall rpds彻底重装。如果还不行我一般建议直接用 conda 重建环境因为有些 DLL 冲突是底层 VC 运行库版本不对引起的在 Windows 上光重装 Python 包解决不了深层的 ABI 兼容问题。重建环境后装同样的包往往能避开这个坑。为了避免这种问题我安装包的原则是能用 conda 装的就用 conda 装只有在 conda 源里没有时才用 pip。原因在于 conda 对依赖的 ABI 校验比 pip 严格得多在 Windows 上这一点会少很多 DLL 崩溃。但也要注意conda 和 pip 混用安装同一类包会导致“包管理日记混乱”虽然大多数时候能跑但版本回溯时会很痛。5.4 激活环境时出现 Warning创建并激活环境时有时候会出现这样的提示WARNING: This Python interpreter is in a conda environment, but the environment has not been activated.这个问题绝大多数情况不是错误而是一个提醒。它的含义是当前终端里运行的 Python 来自某个 conda 环境但你没有用conda activate激活那个环境。比如你在 VSCode 的终端里直接运行了代码而 VSCode 的解释器是 datascience 环境但终端 shell 里的 PATH 被系统 Python 或 base 环境占着。真正的解决方式不是在 VSCode 里反复切换解释器而是让终端和解释器保持同一环境。在 VSCode 里命令面板搜索Terminal: Select Default Profile选择 PowerShell 或 Command Prompt并确保已安装 Python 插件。VSCode 在打开 Python 项目时会自动根据解释器在终端里激活对应 conda 环境但这个功能依赖 Python 插件正常加载。如果一直出现这个 Warning就先看看左下角解释器是不是已经选中了目标环境然后重启 VSCode 终端让插件有时间把环境注入进去。注意如果是在 Windows 的普通 CMD 里手动操作先执行conda init cmd.exe或conda init powershell然后重新打开终端conda activate 命令才会被识别。这一步不做的话即使环境变量配好了conda 也可能会因为activate命令找不到而报错。最后的配置检查清单按照我自己的习惯每次配完环境最终会做一个三步检查。第一步在终端里运行conda env list确认虚拟环境都在。第二步在 VSCode 里新建一个 Python 文件输出sys.executable确认解释器指向目标环境。第三步在 Notebook 里运行一段最小代码比如import numpy as np; print(np.__version__)确认内核连接正常。这三步要是都过了后面再来回折腾的概率就很低了。如果哪一步不过回到对应的章节再排查一遍问题的范围已经缩得很小了。我平时帮很多朋友配环境发现百分之八十的问题都集中在解释器选错和内核没连上这两个点上希望你们看完这篇文章后遇到类似的问题能够更快定位别再被环境折腾掉一个下午。