★ FEATURED ARTICLE 1. 先想清楚为什么是 Miniconda而不是 Anaconda 或裸 Python1.1 一个常见的翻车现场我见过太多人装 Python 环境的流程是这样的官网下个安装包一路下一步装完打开终端敲pip install然后过两个月回头看发现 base 环境里堆了三四十个包numpy 从 1.x 升到 2.x某个老项目突然跑不起来了torch 和 tensorflow 互相打架最后只能重装系统盘。这不是夸张这是我身边真实发生过不只一次的事。问题的根源不在 Python 本身而在于很多人从第一天起就没把环境隔离当成一件必须做的事。裸装 Python 的问题是全局只有一套 site-packages所有项目的依赖都往一个池子里扔Anaconda 的问题是它一上来就给你塞了几百个包、几个 G 的空间base 环境臃肿得像个杂物间你根本不知道哪些包是项目要的、哪些是发行版自带的。Miniconda 站的位置刚好在中间它只给你 conda 这个包管理器加一个最精简的 Python 解释器剩下的全靠你自己按需创建环境。听起来像多了几步麻烦但这几步恰恰是把环境这件事从一开始就管住的关键。我个人的判断标准很朴素——如果你需要跑超过两个不同依赖的项目就该用 conda 系如果你还要在 Windows 上装带编译扩展的包比如科学计算、深度学习那一套那 Miniconda 基本是最省心的选择。1.2 conda 和 pip 到底该怎么分工这是新手最容易糊涂的一点。简单说conda 管的是整个环境里的二进制包pip 管的是PyPI 上的纯 Python 包。conda 的优势在于它能处理非 Python 的依赖比如某个库底层依赖的 C 编译库、CUDA 运行时、MKL 数学库这些都是 pip 装不动的conda 能连包带依赖一起给你摆平。pip 的优势是包全PyPI 上什么冷门库都有conda 的官方频道不一定收。所以我的实操原则是优先 conda 装conda 找不到或者版本太旧再用 pip 补。顺序反了容易出事——先用 pip 装了个包后来又用 conda 装依赖它的东西conda 可能会把 pip 装的那份覆盖掉环境就变得很难解释。真的混用了也要记住一条在同一个环境里尽量把 conda 的操作做完最后再用 pip 收尾。场景推荐工具原因科学计算栈numpy/scipy/pandasconda自带优化过的二进制省去编译深度学习框架torch 等conda能一并处理 CUDA 相关依赖冷门纯 Python 库pipconda 频道收录不全需要指定精确小版本两者皆可看哪个有装前先conda search确认从 GitHub 源码装pip-e模式conda 不擅长处理本地源码这个表我建议贴在显示器边上真能少走不少弯路。1.3 安装前必须先确认的两件事第一件是磁盘空间。Miniconda 本体装完大概 500MB 左右但每个虚拟环境少则几百 MB、多则两三个 G装了深度学习框架之后你会看到这个数字所以别把它装在一个只剩两个 G 的盘里。我一般会单独留一个目录比如D:\dev\miniconda3或者~/dev/miniconda3把所有环境集中在一个地方将来清理、备份、迁移都方便。第二件是路径里绝对不能有中文和空格。这条是老生常谈但每年还是有人栽在上面。conda 在创建环境时会往路径里写大量脚本文件一旦路径含空格或中文某些包的编译脚本、shell 激活脚本就会解析失败报出来的错误往往莫名其妙比如The system cannot find the path specified或者某个.bat无法执行排查半天最后发现是路径问题。安装目录名、你的 Windows 用户名、项目文件夹名这三处都要检查。2. 装 MinicondaWindows 和 macOS 的分步操作2.1 Windows 上的安装细节与那个容易点错的选项到 Miniconda 的官方下载页选对应系统、对应架构现在基本都是 64 位的安装包。Windows 上给的是.exe大小一百来兆。下载完双击一路 Next中途有两个地方需要停下来看一眼。第一个是Install for: Just Me / All Users。选 Just Me安装路径会在你的用户目录下不需要管理员权限后面用起来最省事选 All Users 会装到C:\ProgramData下多用户共用但某些操作需要提权。个人开发机我建议 Just Me。第二个是安装向导最后那页的两个勾选框。第一个是Add Miniconda3 to my PATH environment variable官方建议不要勾原因很简单勾了之后 conda 的 base 环境会永久性混进系统 PATH你打开任何终端都默认在那个环境里容易和系统里其他软件自带的 Python 冲突。第二个是Register Miniconda3 as my default Python这个可以勾问题不大。正确做法是不勾 PATH然后用开始菜单里那个 Anaconda Prompt (Miniconda3) 作为专用入口——这个快捷方式启动时会自动帮你初始化 conda不污染系统环境。安装完成后从开始菜单打开 Anaconda Prompt敲conda --version能打出类似conda 24.x.x的字样就说明装好了。如果提示不是内部或外部命令八成是你从普通的 cmd 或 PowerShell 打开的换那个专用快捷方式再试。2.2 macOS 上的安装与 shell 初始化的坑macOS 上给的是.pkg安装包双击按提示走默认会装到~/miniconda3。装完之后一定要做 shell 初始化这一步很多人漏掉结果终端里怎么敲 conda 都没反应。现在的 macOS 默认 shell 是 zsh所以~/miniconda3/bin/conda init zsh如果你还在用 bash就把zsh换成bash。这个命令做的事是在你的~/.zshrc里追加一段 conda 初始化脚本。执行完必须关掉终端重开或者手动source ~/.zshrc否则不生效。注意如果你的 Mac 是 Apple 芯片装之前先确认下载的是 arm64 版本的安装包。装错了 x86 版本conda 也能跑但会走 Rosetta 转译装某些带编译扩展的包会明显变慢甚至装不上。Linux 上没有图形界面直接跑安装脚本bash Miniconda3-latest-Linux-x86_64.sh一路回车看协议最后问是否 conda init 选 yes。装完同样重开终端。2.3 装完马上要做的三件配置第一件关掉 base 环境的自动激活。默认情况下你每开一个终端前面都会多一个(base)这意味着你所有的随手操作都在 base 环境里做时间长了 base 就被污染了。执行conda config --set auto_activate_base false之后再开终端就是干净的需要哪个环境再手动 activate。这个习惯我强烈建议从第一天就养成我见过太多人 base 环境被搞坏之后不得不重装 Miniconda。第二件配国内镜像源如果你在下载速度上确实有困扰。conda 默认走的是境外服务器装大包时经常卡住或者断。镜像源配置内容是环境相关的各家镜像站给的命令会变正常做法是到镜像站官方说明页照着抄那几行conda config --add channels和conda config --set show_channel_urls yes。配置完之后conda config --show channels可以确认顺序镜像要放在前面才有意义。第三件验证下载配置是否真的生效。随便建个小环境试试conda create -n testenv python3.11看下载速度正常不正常。如果某个包一直卡在 Solving environment 半天不动那多半是源的问题或者 conda 版本太老可以考虑conda update -n base conda升一下本体。3. 创建虚拟环境命名、版本与依赖落地的实战做法3.1 环境命名与目录集中管理conda create -n 环境名 python版本是基本语法但环境名怎么起是有讲究的。我的习惯是项目名 主要依赖的大版本比如cv-torch2、nlp-py311、web-django5。这么起名有两个好处一是以后conda env list一眼能看出每个环境是干嘛的二是同时存在多个版本时不会搞混。不要用test1、env、myenv这种名字三个月后你自己都认不出来那是干什么的。环境默认存放在 Miniconda 安装目录的envs下面。如果你想让环境放在别处比如 C 盘吃紧想放 D 盘可以在~/.condarc里加一行envs_dirs指定首选路径envs_dirs: - D:\dev\conda-envs - ~/miniconda3/envs写成列表的意思是有多个候选conda 会优先用第一个可写的。这种集中管理的思路在环境变多之后特别有用——清理、备份都只是对一个目录操作。创建环境的命令本身很简单但有几个参数值得记住conda create -n cv-torch2 python3.11 numpy pandas -ypython3.11是指定解释器版本尽量写具体别只写python否则 conda 会拉最新的将来复现时可能对不上。后面可以直接跟要装的包conda 会在创建时一次性解决依赖比先建环境再一个个装效率高得多。-y是跳过确认脚本化时有用手动操作可加可不加。另外还有--clone参数值得一提。当你需要一个当前环境的副本做实验时怕把好好的环境搞坏conda create -n cv-torch2-exp --clone cv-torch2比重新装一遍依赖快得多尤其在包很多的时候差距明显。3.2 用 environment.yml 把环境存下来在同一个项目里反复建环境的场景下手动一条条敲conda install是低效且不可复现的。正确做法是从项目一开始就用environment.yml管理依赖。一份典型的文件长这样name: cv-torch2 channels: - defaults dependencies: - python3.11 - numpy1.26 - pandas - matplotlib - pip - pip: - some-pypi-only-package0.4.1注意pip:这一段是嵌套写法它表示用 pip 装的包这样 conda 在构建环境时会先装完 conda 那部分再用 pip 补齐。用这个文件一步建环境conda env create -f environment.yml反过来如果你已经用手动方式建好了一个环境想把它导出成文件conda env export --no-builds environment.yml这里加--no-builds是我个人的强烈建议。默认导出的内容里每个包都带一个 build 字符串比如numpy-1.26.4-py311h1234567_0后面那一串它和具体的操作系统、架构强绑定你把文件发给用不同系统的同事大概率装不上。去掉 build 字符串之后conda 会自己挑当前平台合适的版本兼容性大幅提升。一个实操细节conda env export导出的内容会把你环境里所有包都列出来包括你随手装上、根本没在用的那些。干净的做法是手动维护一份精简的依赖清单只写项目真正需要的顶层依赖让 conda 自己去解传递依赖。这份手工清单才是真正值得提交到代码仓库的东西。3.3 环境创建完成后必须验证的几件事建完环境不要直接开始写代码先做一轮验证能省掉后面大量为什么跑不起来的困惑。先激活conda activate cv-torch2注意 Windows 上如果你用的是老的 cmd可能conda activate不认需要先用conda init cmd.exe初始化一次并重开窗口。PowerShell 同理conda init powershell。激活之后看解释器路径对不对where python # Windows which python # macOS / Linux输出里应该包含.conda或者envs\cv-torch2这样的路径。如果打出来的是系统自带那个 Python说明激活没生效多半是 shell 没初始化好。然后验证版本和关键库python --version python -c import numpy; print(numpy.__version__)最后看一眼环境列表确认新环境确实存在conda env list带星号*的那个是你当前激活的环境。这个命令以后你会天天用值得记熟。4. 让 VS Code 认出你的 conda 环境4.1 装什么扩展、哪个才是必须的VS Code 里和 Python 相关的扩展有好几个装的次序会影响体验。必须装的是官方那个 Python 扩展作者是 Microsoft它负责语言服务、调试、运行、环境发现。装了它之后会自动带上一个 Pylance提供类型推断和代码跳转不用单独装。如果你经常写 Jupyter Notebook再补一个 Jupyter 扩展。有一个常见的困惑是装了 Python 扩展之后右下角/状态栏没有显示当前解释器版本。这是因为新版 VS Code 把解释器选择器移到了别的位置通常是编辑器右上角的那个按钮或者按CtrlShiftP输入Python: Select Interpreter直接调出来。我一般直接记这个命令面板路径比找按钮快。4.2 解释器没有被自动识别怎么办正常情况下 VS Code 会自动扫描常见安装路径把你的 conda 环境列出来。但如果你安装时选了自定义目录比如装到了 D 盘它可能扫不到。这时候要手动把路径告诉它。在 VS Code 的设置里搜python.defaultInterpreterPath填入你目标环境里解释器的完整路径。比如 Windows 下是D:\dev\conda-envs\cv-torch2\python.exemacOS 下是/Users/你的用户名/miniconda3/envs/cv-torch2/bin/python另一种更省事的办法是在项目根目录建一个.vscode/settings.json把解释器路径写进去这样这个配置只对这个项目生效不会影响你其他项目{ python.defaultInterpreterPath: D:\\dev\\conda-envs\\cv-torch2\\python.exe, python.terminal.activateEnvironment: true }注意 JSON 里的反斜杠要写成双反斜杠这是 JSON 的转义规则写单斜杠会解析失败。第二行那句activateEnvironment的意思是在 VS Code 内置终端里打开新终端时自动激活当前选中的 conda 环境这个配上之后体验提升非常明显不用每次手动敲conda activate。4.3 内置终端的双激活陷阱这是我最想强调的一个坑因为它太隐蔽了。你在 VS Code 里可能同时遇到两件事一是你手动在终端里conda activate了某个环境二是 VS Code 的 Python 扩展根据defaultInterpreterPath又自动激活了一次。两个来源不一致时就会出现编辑器里提示的库版本和终端里 import 出来的版本对不上的诡异现象。排查这个问题的办法很简单在出错的那个终端里直接跑python -c import sys; print(sys.executable)看它指向哪。如果和你编辑器状态栏显示的解释器路径不一致那就是激活冲突。修复方案是二选一别让两个机制同时管要么在 settings 里把python.terminal.activateEnvironment关掉、全靠手动 activate要么把它开着、并且保证defaultInterpreterPath指向的就是你要用的那个环境然后终端里不要再手动切换。还有一个 Windows 特有的情况PowerShell 默认的执行策略可能禁止运行 conda 的激活脚本报错大意是无法加载文件因为在此系统上禁止运行脚本。这不是 conda 的问题是 PowerShell 的安全策略。解决办法是以管理员身份开一次 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重开终端。4.4 用 launch.json 固定调试时的解释器当你需要打断点调试时光选好解释器可能还不够因为 VS Code 的调试器会单独读launch.json的配置。一个稳妥的写法是把解释器路径直接写进去避免它自己猜{ version: 0.2.0, configurations: [ { name: Python: Current File, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, python: D:\\dev\\conda-envs\\cv-torch2\\python.exe, justMyCode: true } ] }console选integratedTerminal而不是internalConsole是因为很多库比如带进度条的、需要交互输入的在内置控制台里表现异常用集成终端能看到真实的终端输出出问题好排查。justMyCode设为 true 表示调试时只单步进入你自己的代码不跳进标准库和第三方库里这是默认推荐值。5. 那些踩过才知道疼的细节5.1 激活失败的一串排查链路conda activate不生效是最常见的求助点。我把完整排查链路列一下按这个顺序试基本都能定位第一步确认 conda 本身可用conda --version如果不认识这个命令说明 shell 没初始化。Windows 用conda init powershell或conda init cmd.exemacOS/Linux 用conda init zsh或conda init bash。执行完必须重开终端窗口这是最多人漏掉的一步。第二步如果你把整个 Miniconda 目录搬过位置比如从 C 盘挪到 D 盘那所有环境里的绝对路径都失效了conda activate会指向不存在的路径。这种情况得修envs目录里的路径记录或者干脆按environment.yml重建环境——重建通常比修更快这也是我强调用 yml 管理依赖的现实理由。第三步确认 shell 的配置文件里那行 conda 初始化代码没被其他东西覆盖。比如有的用户装完 conda 之后又装了别的命令行工具它会在.zshrc末尾追加自己的初始化把 conda 那一段挤到前面去执行依赖 conda 的命令就失败了。用cat ~/.zshrc看一眼顺序conda 那段应该靠后一点。第四步Windows 上如果从资源管理器直接在某文件夹里在此处打开终端有时候拿到的是一份没加载用户配置的环境。这种情况换从开始菜单启动专用终端或者手动 cd 过去。5.2 环境名拼错和conda clean的空间回收conda activate cv-troch2拼错一个字母conda 会直接报EnvironmentNameNotFound这个错误提示其实挺清楚的但新手常以为是自己环境没建成功。养成conda env list先看一眼的习惯比猜快得多。另一个值得早点知道的命令是conda clean。conda 的包缓存策略很大方你每装一次包下载的压缩包和解压出来的副本都会留着环境建多了之后pkgs目录能吃掉好几个 G。定期清理conda clean --all执行时会列出要删的东西让你确认。我一般一个月跑一次尤其在做完大版本升级之后。注意这个操作只是删缓存不会删掉你正在用的环境放心跑。5.3 环境版本回退与别再重装的兜底某天你更新了一个包代码跑挂了想回到之前的状态——这时候如果你没留environment.yml就只能靠运气。所以我在每个项目的根目录都放一份 yml并且每次做出能跑通的改动之后就更新它。这个习惯救过我很多次。如果只是想单独回退某个包conda install 包名旧版本号就行。conda 会自动把冲突的依赖一并调整。真正麻烦的是跨 Python 大版本的回退比如环境建在 3.12但某个库只支持到 3.11这种情况下改环境里的 Python 版本很折腾更省事的做法是新建一个 3.11 的环境把代码和依赖清单搬过去。这也印证了前面说的命名习惯的价值——cv-py311和cv-py312两个环境并存谁是谁一目了然。5.4 几个我反复见到的疑问第一个我能不能把所有项目都放在 base 环境里技术上可以实践上不要。base 环境一旦被某个项目的依赖搞坏修复成本远高于重建而重建意味着你要重装所有东西。base 只用来放 conda 自己需要的少数几个包这是我的原则。第二个虚拟环境会占用很多硬盘吗会。一个只装 numpy 和 pandas 的环境大概三五百兆装了深度学习框架的能到三四个 G。所以要定期用conda env list回头看把废弃的环境conda env remove -n 环境名删掉别留着当纪念品。第三个VS Code 里显示的库版本和我 import 出来的不一样。回到 4.3 那节跑sys.executable看路径九成是解释器没选对或者激活冲突。第四个能不能直接复制环境文件夹来达到复制的效果不建议。环境里有大量写死了绝对路径的脚本和配置直接复制到别的路径很多包会找不到自己的依赖。用--clone参数或者 yml 重建才是正路。把这几件事从头到尾走一遍其实也就半小时的事但它决定了你后面几个月的开发体验顺不顺。我自己是在被全局环境坑过两次之后才彻底转向一项目一环境 yml 管依赖这套做法的切换过去之后再没因为环境问题浪费过一整天。
阅读完成 · 觉得有帮助？
