境配置指南：conda/pip分工與VS Code避坑)
1. 先想清楚為什么是 Miniconda而不是 Anaconda 或裸 Python1.1 一個常見的翻車現(xiàn)場我見過太多人裝 Python 環(huán)境的流程是這樣的官網(wǎng)下個安裝包一路下一步裝完打開終端敲pip install然后過兩個月回頭看發(fā)現(xiàn) base 環(huán)境里堆了三四十個包numpy 從 1.x 升到 2.x某個老項目突然跑不起來了torch 和 tensorflow 互相打架最后只能重裝系統(tǒng)盤。這不是夸張這是我身邊真實發(fā)生過不只一次的事。問題的根源不在 Python 本身而在于很多人從第一天起就沒把環(huán)境隔離當成一件必須做的事。裸裝 Python 的問題是全局只有一套 site-packages所有項目的依賴都往一個池子里扔Anaconda 的問題是它一上來就給你塞了幾百個包、幾個 G 的空間base 環(huán)境臃腫得像個雜物間你根本不知道哪些包是項目要的、哪些是發(fā)行版自帶的。Miniconda 站的位置剛好在中間它只給你 conda 這個包管理器加一個最精簡的 Python 解釋器剩下的全靠你自己按需創(chuàng)建環(huán)境。聽起來像多了幾步麻煩但這幾步恰恰是把環(huán)境這件事從一開始就管住的關(guān)鍵。我個人的判斷標準很樸素——如果你需要跑超過兩個不同依賴的項目就該用 conda 系如果你還要在 Windows 上裝帶編譯擴展的包比如科學(xué)計算、深度學(xué)習那一套那 Miniconda 基本是最省心的選擇。1.2 conda 和 pip 到底該怎么分工這是新手最容易糊涂的一點。簡單說conda 管的是整個環(huán)境里的二進制包pip 管的是PyPI 上的純 Python 包。conda 的優(yōu)勢在于它能處理非 Python 的依賴比如某個庫底層依賴的 C 編譯庫、CUDA 運行時、MKL 數(shù)學(xué)庫這些都是 pip 裝不動的conda 能連包帶依賴一起給你擺平。pip 的優(yōu)勢是包全PyPI 上什么冷門庫都有conda 的官方頻道不一定收。所以我的實操原則是優(yōu)先 conda 裝conda 找不到或者版本太舊再用 pip 補。順序反了容易出事——先用 pip 裝了個包后來又用 conda 裝依賴它的東西conda 可能會把 pip 裝的那份覆蓋掉環(huán)境就變得很難解釋。真的混用了也要記住一條在同一個環(huán)境里盡量把 conda 的操作做完最后再用 pip 收尾。場景推薦工具原因科學(xué)計算棧numpy/scipy/pandasconda自帶優(yōu)化過的二進制省去編譯深度學(xué)習框架torch 等conda能一并處理 CUDA 相關(guān)依賴冷門純 Python 庫pipconda 頻道收錄不全需要指定精確小版本兩者皆可看哪個有裝前先conda search確認從 GitHub 源碼裝pip-e模式conda 不擅長處理本地源碼這個表我建議貼在顯示器邊上真能少走不少彎路。1.3 安裝前必須先確認的兩件事第一件是磁盤空間。Miniconda 本體裝完大概 500MB 左右但每個虛擬環(huán)境少則幾百 MB、多則兩三個 G裝了深度學(xué)習框架之后你會看到這個數(shù)字所以別把它裝在一個只剩兩個 G 的盤里。我一般會單獨留一個目錄比如D:\dev\miniconda3或者~/dev/miniconda3把所有環(huán)境集中在一個地方將來清理、備份、遷移都方便。第二件是路徑里絕對不能有中文和空格。這條是老生常談但每年還是有人栽在上面。conda 在創(chuàng)建環(huán)境時會往路徑里寫大量腳本文件一旦路徑含空格或中文某些包的編譯腳本、shell 激活腳本就會解析失敗報出來的錯誤往往莫名其妙比如The system cannot find the path specified或者某個.bat無法執(zhí)行排查半天最后發(fā)現(xiàn)是路徑問題。安裝目錄名、你的 Windows 用戶名、項目文件夾名這三處都要檢查。2. 裝 MinicondaWindows 和 macOS 的分步操作2.1 Windows 上的安裝細節(jié)與那個容易點錯的選項到 Miniconda 的官方下載頁選對應(yīng)系統(tǒng)、對應(yīng)架構(gòu)現(xiàn)在基本都是 64 位的安裝包。Windows 上給的是.exe大小一百來兆。下載完雙擊一路 Next中途有兩個地方需要停下來看一眼。第一個是Install for: Just Me / All Users。選 Just Me安裝路徑會在你的用戶目錄下不需要管理員權(quán)限后面用起來最省事選 All Users 會裝到C:\ProgramData下多用戶共用但某些操作需要提權(quán)。個人開發(fā)機我建議 Just Me。第二個是安裝向?qū)ё詈竽琼摰膬蓚€勾選框。第一個是Add Miniconda3 to my PATH environment variable官方建議不要勾原因很簡單勾了之后 conda 的 base 環(huán)境會永久性混進系統(tǒng) PATH你打開任何終端都默認在那個環(huán)境里容易和系統(tǒng)里其他軟件自帶的 Python 沖突。第二個是Register Miniconda3 as my default Python這個可以勾問題不大。正確做法是不勾 PATH然后用開始菜單里那個 Anaconda Prompt (Miniconda3) 作為專用入口——這個快捷方式啟動時會自動幫你初始化 conda不污染系統(tǒng)環(huán)境。安裝完成后從開始菜單打開 Anaconda Prompt敲conda --version能打出類似conda 24.x.x的字樣就說明裝好了。如果提示不是內(nèi)部或外部命令八成是你從普通的 cmd 或 PowerShell 打開的換那個專用快捷方式再試。2.2 macOS 上的安裝與 shell 初始化的坑macOS 上給的是.pkg安裝包雙擊按提示走默認會裝到~/miniconda3。裝完之后一定要做 shell 初始化這一步很多人漏掉結(jié)果終端里怎么敲 conda 都沒反應(yīng)?，F(xiàn)在的 macOS 默認 shell 是 zsh所以~/miniconda3/bin/conda init zsh如果你還在用 bash就把zsh換成bash。這個命令做的事是在你的~/.zshrc里追加一段 conda 初始化腳本。執(zhí)行完必須關(guān)掉終端重開或者手動source ~/.zshrc否則不生效。注意如果你的 Mac 是 Apple 芯片裝之前先確認下載的是 arm64 版本的安裝包。裝錯了 x86 版本conda 也能跑但會走 Rosetta 轉(zhuǎn)譯裝某些帶編譯擴展的包會明顯變慢甚至裝不上。Linux 上沒有圖形界面直接跑安裝腳本bash Miniconda3-latest-Linux-x86_64.sh一路回車看協(xié)議最后問是否 conda init 選 yes。裝完同樣重開終端。2.3 裝完馬上要做的三件配置第一件關(guān)掉 base 環(huán)境的自動激活。默認情況下你每開一個終端前面都會多一個(base)這意味著你所有的隨手操作都在 base 環(huán)境里做時間長了 base 就被污染了。執(zhí)行conda config --set auto_activate_base false之后再開終端就是干凈的需要哪個環(huán)境再手動 activate。這個習慣我強烈建議從第一天就養(yǎng)成我見過太多人 base 環(huán)境被搞壞之后不得不重裝 Miniconda。第二件配國內(nèi)鏡像源如果你在下載速度上確實有困擾。conda 默認走的是境外服務(wù)器裝大包時經(jīng)?？ㄗ』蛘邤?。鏡像源配置內(nèi)容是環(huán)境相關(guān)的各家鏡像站給的命令會變正常做法是到鏡像站官方說明頁照著抄那幾行conda config --add channels和conda config --set show_channel_urls yes。配置完之后conda config --show channels可以確認順序鏡像要放在前面才有意義。第三件驗證下載配置是否真的生效。隨便建個小環(huán)境試試conda create -n testenv python3.11看下載速度正常不正常。如果某個包一直卡在 Solving environment 半天不動那多半是源的問題或者 conda 版本太老可以考慮conda update -n base conda升一下本體。3. 創(chuàng)建虛擬環(huán)境命名、版本與依賴落地的實戰(zhàn)做法3.1 環(huán)境命名與目錄集中管理conda create -n 環(huán)境名 python版本是基本語法但環(huán)境名怎么起是有講究的。我的習慣是項目名 主要依賴的大版本比如cv-torch2、nlp-py311、web-django5。這么起名有兩個好處一是以后conda env list一眼能看出每個環(huán)境是干嘛的二是同時存在多個版本時不會搞混。不要用test1、env、myenv這種名字三個月后你自己都認不出來那是干什么的。環(huán)境默認存放在 Miniconda 安裝目錄的envs下面。如果你想讓環(huán)境放在別處比如 C 盤吃緊想放 D 盤可以在~/.condarc里加一行envs_dirs指定首選路徑envs_dirs: - D:\dev\conda-envs - ~/miniconda3/envs寫成列表的意思是有多個候選conda 會優(yōu)先用第一個可寫的。這種集中管理的思路在環(huán)境變多之后特別有用——清理、備份都只是對一個目錄操作。創(chuàng)建環(huán)境的命令本身很簡單但有幾個參數(shù)值得記住conda create -n cv-torch2 python3.11 numpy pandas -ypython3.11是指定解釋器版本盡量寫具體別只寫python否則 conda 會拉最新的將來復(fù)現(xiàn)時可能對不上。后面可以直接跟要裝的包conda 會在創(chuàng)建時一次性解決依賴比先建環(huán)境再一個個裝效率高得多。-y是跳過確認腳本化時有用手動操作可加可不加。另外還有--clone參數(shù)值得一提。當你需要一個當前環(huán)境的副本做實驗時怕把好好的環(huán)境搞壞conda create -n cv-torch2-exp --clone cv-torch2比重新裝一遍依賴快得多尤其在包很多的時候差距明顯。3.2 用 environment.yml 把環(huán)境存下來在同一個項目里反復(fù)建環(huán)境的場景下手動一條條敲conda install是低效且不可復(fù)現(xiàn)的。正確做法是從項目一開始就用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 在構(gòu)建環(huán)境時會先裝完 conda 那部分再用 pip 補齊。用這個文件一步建環(huán)境conda env create -f environment.yml反過來如果你已經(jīng)用手動方式建好了一個環(huán)境想把它導(dǎo)出成文件conda env export --no-builds environment.yml這里加--no-builds是我個人的強烈建議。默認導(dǎo)出的內(nèi)容里每個包都帶一個 build 字符串比如numpy-1.26.4-py311h1234567_0后面那一串它和具體的操作系統(tǒng)、架構(gòu)強綁定你把文件發(fā)給用不同系統(tǒng)的同事大概率裝不上。去掉 build 字符串之后conda 會自己挑當前平臺合適的版本兼容性大幅提升。一個實操細節(jié)conda env export導(dǎo)出的內(nèi)容會把你環(huán)境里所有包都列出來包括你隨手裝上、根本沒在用的那些。干凈的做法是手動維護一份精簡的依賴清單只寫項目真正需要的頂層依賴讓 conda 自己去解傳遞依賴。這份手工清單才是真正值得提交到代碼倉庫的東西。3.3 環(huán)境創(chuàng)建完成后必須驗證的幾件事建完環(huán)境不要直接開始寫代碼先做一輪驗證能省掉后面大量為什么跑不起來的困惑。先激活conda activate cv-torch2注意 Windows 上如果你用的是老的 cmd可能conda activate不認需要先用conda init cmd.exe初始化一次并重開窗口。PowerShell 同理conda init powershell。激活之后看解釋器路徑對不對where python # Windows which python # macOS / Linux輸出里應(yīng)該包含.conda或者envs\cv-torch2這樣的路徑。如果打出來的是系統(tǒng)自帶那個 Python說明激活沒生效多半是 shell 沒初始化好。然后驗證版本和關(guān)鍵庫python --version python -c import numpy; print(numpy.__version__)最后看一眼環(huán)境列表確認新環(huán)境確實存在conda env list帶星號*的那個是你當前激活的環(huán)境。這個命令以后你會天天用值得記熟。4. 讓 VS Code 認出你的 conda 環(huán)境4.1 裝什么擴展、哪個才是必須的VS Code 里和 Python 相關(guān)的擴展有好幾個裝的次序會影響體驗。必須裝的是官方那個 Python 擴展作者是 Microsoft它負責語言服務(wù)、調(diào)試、運行、環(huán)境發(fā)現(xiàn)。裝了它之后會自動帶上一個 Pylance提供類型推斷和代碼跳轉(zhuǎn)不用單獨裝。如果你經(jīng)常寫 Jupyter Notebook再補一個 Jupyter 擴展。有一個常見的困惑是裝了 Python 擴展之后右下角/狀態(tài)欄沒有顯示當前解釋器版本。這是因為新版 VS Code 把解釋器選擇器移到了別的位置通常是編輯器右上角的那個按鈕或者按CtrlShiftP輸入Python: Select Interpreter直接調(diào)出來。我一般直接記這個命令面板路徑比找按鈕快。4.2 解釋器沒有被自動識別怎么辦正常情況下 VS Code 會自動掃描常見安裝路徑把你的 conda 環(huán)境列出來。但如果你安裝時選了自定義目錄比如裝到了 D 盤它可能掃不到。這時候要手動把路徑告訴它。在 VS Code 的設(shè)置里搜python.defaultInterpreterPath填入你目標環(huán)境里解釋器的完整路徑。比如 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 的轉(zhuǎn)義規(guī)則寫單斜杠會解析失敗。第二行那句activateEnvironment的意思是在 VS Code 內(nèi)置終端里打開新終端時自動激活當前選中的 conda 環(huán)境這個配上之后體驗提升非常明顯不用每次手動敲conda activate。4.3 內(nèi)置終端的雙激活陷阱這是我最想強調(diào)的一個坑因為它太隱蔽了。你在 VS Code 里可能同時遇到兩件事一是你手動在終端里conda activate了某個環(huán)境二是 VS Code 的 Python 擴展根據(jù)defaultInterpreterPath又自動激活了一次。兩個來源不一致時就會出現(xiàn)編輯器里提示的庫版本和終端里 import 出來的版本對不上的詭異現(xiàn)象。排查這個問題的辦法很簡單在出錯的那個終端里直接跑python -c import sys; print(sys.executable)看它指向哪。如果和你編輯器狀態(tài)欄顯示的解釋器路徑不一致那就是激活沖突。修復(fù)方案是二選一別讓兩個機制同時管要么在 settings 里把python.terminal.activateEnvironment關(guān)掉、全靠手動 activate要么把它開著、并且保證defaultInterpreterPath指向的就是你要用的那個環(huán)境然后終端里不要再手動切換。還有一個 Windows 特有的情況PowerShell 默認的執(zhí)行策略可能禁止運行 conda 的激活腳本報錯大意是無法加載文件因為在此系統(tǒng)上禁止運行腳本。這不是 conda 的問題是 PowerShell 的安全策略。解決辦法是以管理員身份開一次 PowerShell執(zhí)行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重開終端。4.4 用 launch.json 固定調(diào)試時的解釋器當你需要打斷點調(diào)試時光選好解釋器可能還不夠因為 VS Code 的調(diào)試器會單獨讀launch.json的配置。一個穩(wěn)妥的寫法是把解釋器路徑直接寫進去避免它自己猜{ 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是因為很多庫比如帶進度條的、需要交互輸入的在內(nèi)置控制臺里表現(xiàn)異常用集成終端能看到真實的終端輸出出問題好排查。justMyCode設(shè)為 true 表示調(diào)試時只單步進入你自己的代碼不跳進標準庫和第三方庫里這是默認推薦值。5. 那些踩過才知道疼的細節(jié)5.1 激活失敗的一串排查鏈路conda activate不生效是最常見的求助點。我把完整排查鏈路列一下按這個順序試基本都能定位第一步確認 conda 本身可用conda --version如果不認識這個命令說明 shell 沒初始化。Windows 用conda init powershell或conda init cmd.exemacOS/Linux 用conda init zsh或conda init bash。執(zhí)行完必須重開終端窗口這是最多人漏掉的一步。第二步如果你把整個 Miniconda 目錄搬過位置比如從 C 盤挪到 D 盤那所有環(huán)境里的絕對路徑都失效了conda activate會指向不存在的路徑。這種情況得修envs目錄里的路徑記錄或者干脆按environment.yml重建環(huán)境——重建通常比修更快這也是我強調(diào)用 yml 管理依賴的現(xiàn)實理由。第三步確認 shell 的配置文件里那行 conda 初始化代碼沒被其他東西覆蓋。比如有的用戶裝完 conda 之后又裝了別的命令行工具它會在.zshrc末尾追加自己的初始化把 conda 那一段擠到前面去執(zhí)行依賴 conda 的命令就失敗了。用cat ~/.zshrc看一眼順序conda 那段應(yīng)該靠后一點。第四步Windows 上如果從資源管理器直接在某文件夾里在此處打開終端有時候拿到的是一份沒加載用戶配置的環(huán)境。這種情況換從開始菜單啟動專用終端或者手動 cd 過去。5.2 環(huán)境名拼錯和conda clean的空間回收conda activate cv-troch2拼錯一個字母conda 會直接報EnvironmentNameNotFound這個錯誤提示其實挺清楚的但新手常以為是自己環(huán)境沒建成功。養(yǎng)成conda env list先看一眼的習慣比猜快得多。另一個值得早點知道的命令是conda clean。conda 的包緩存策略很大方你每裝一次包下載的壓縮包和解壓出來的副本都會留著環(huán)境建多了之后pkgs目錄能吃掉好幾個 G。定期清理conda clean --all執(zhí)行時會列出要刪的東西讓你確認。我一般一個月跑一次尤其在做完大版本升級之后。注意這個操作只是刪緩存不會刪掉你正在用的環(huán)境放心跑。5.3 環(huán)境版本回退與別再重裝的兜底某天你更新了一個包代碼跑掛了想回到之前的狀態(tài)——這時候如果你沒留environment.yml就只能靠運氣。所以我在每個項目的根目錄都放一份 yml并且每次做出能跑通的改動之后就更新它。這個習慣救過我很多次。如果只是想單獨回退某個包conda install 包名舊版本號就行。conda 會自動把沖突的依賴一并調(diào)整。真正麻煩的是跨 Python 大版本的回退比如環(huán)境建在 3.12但某個庫只支持到 3.11這種情況下改環(huán)境里的 Python 版本很折騰更省事的做法是新建一個 3.11 的環(huán)境把代碼和依賴清單搬過去。這也印證了前面說的命名習慣的價值——cv-py311和cv-py312兩個環(huán)境并存誰是誰一目了然。5.4 幾個我反復(fù)見到的疑問第一個我能不能把所有項目都放在 base 環(huán)境里技術(shù)上可以實踐上不要。base 環(huán)境一旦被某個項目的依賴搞壞修復(fù)成本遠高于重建而重建意味著你要重裝所有東西。base 只用來放 conda 自己需要的少數(shù)幾個包這是我的原則。第二個虛擬環(huán)境會占用很多硬盤嗎會。一個只裝 numpy 和 pandas 的環(huán)境大概三五百兆裝了深度學(xué)習框架的能到三四個 G。所以要定期用conda env list回頭看把廢棄的環(huán)境conda env remove -n 環(huán)境名刪掉別留著當紀念品。第三個VS Code 里顯示的庫版本和我 import 出來的不一樣?；氐?4.3 那節(jié)跑sys.executable看路徑九成是解釋器沒選對或者激活沖突。第四個能不能直接復(fù)制環(huán)境文件夾來達到復(fù)制的效果不建議。環(huán)境里有大量寫死了絕對路徑的腳本和配置直接復(fù)制到別的路徑很多包會找不到自己的依賴。用--clone參數(shù)或者 yml 重建才是正路。把這幾件事從頭到尾走一遍其實也就半小時的事但它決定了你后面幾個月的開發(fā)體驗順不順。我自己是在被全局環(huán)境坑過兩次之后才徹底轉(zhuǎn)向一項目一環(huán)境 yml 管依賴這套做法的切換過去之后再沒因為環(huán)境問題浪費過一整天。 Miniconda虛擬環(huán)境配置指南：conda/pip分工與VS Code避坑
1. 先想清楚為什么是 Miniconda而不是 Anaconda 或裸 Python1.1 一個常見的翻車現(xiàn)場我見過太多人裝 Python 環(huán)境的流程是這樣的官網(wǎng)下個安裝包一路下一步裝完打開終端敲pip install然后過兩個月回頭看發(fā)現(xiàn) base 環(huán)境里堆了三四十個包numpy 從 1.x 升到 2.x某個老項目突然跑不起來了torch 和 tensorflow 互相打架最后只能重裝系統(tǒng)盤。這不是夸張這是我身邊真實發(fā)生過不只一次的事。問題的根源不在 Python 本身而在于很多人從第一天起就沒把環(huán)境隔離當成一件必須做的事。裸裝 Python 的問題是全局只有一套 site-packages所有項目的依賴都往一個池子里扔Anaconda 的問題是它一上來就給你塞了幾百個包、幾個 G 的空間base 環(huán)境臃腫得像個雜物間你根本不知道哪些包是項目要的、哪些是發(fā)行版自帶的。Miniconda 站的位置剛好在中間它只給你 conda 這個包管理器加一個最精簡的 Python 解釋器剩下的全靠你自己按需創(chuàng)建環(huán)境。聽起來像多了幾步麻煩但這幾步恰恰是把環(huán)境這件事從一開始就管住的關(guān)鍵。我個人的判斷標準很樸素——如果你需要跑超過兩個不同依賴的項目就該用 conda 系如果你還要在 Windows 上裝帶編譯擴展的包比如科學(xué)計算、深度學(xué)習那一套那 Miniconda 基本是最省心的選擇。1.2 conda 和 pip 到底該怎么分工這是新手最容易糊涂的一點。簡單說conda 管的是整個環(huán)境里的二進制包pip 管的是PyPI 上的純 Python 包。conda 的優(yōu)勢在于它能處理非 Python 的依賴比如某個庫底層依賴的 C 編譯庫、CUDA 運行時、MKL 數(shù)學(xué)庫這些都是 pip 裝不動的conda 能連包帶依賴一起給你擺平。pip 的優(yōu)勢是包全PyPI 上什么冷門庫都有conda 的官方頻道不一定收。所以我的實操原則是優(yōu)先 conda 裝conda 找不到或者版本太舊再用 pip 補。順序反了容易出事——先用 pip 裝了個包后來又用 conda 裝依賴它的東西conda 可能會把 pip 裝的那份覆蓋掉環(huán)境就變得很難解釋。真的混用了也要記住一條在同一個環(huán)境里盡量把 conda 的操作做完最后再用 pip 收尾。場景推薦工具原因科學(xué)計算棧numpy/scipy/pandasconda自帶優(yōu)化過的二進制省去編譯深度學(xué)習框架torch 等conda能一并處理 CUDA 相關(guān)依賴冷門純 Python 庫pipconda 頻道收錄不全需要指定精確小版本兩者皆可看哪個有裝前先conda search確認從 GitHub 源碼裝pip-e模式conda 不擅長處理本地源碼這個表我建議貼在顯示器邊上真能少走不少彎路。1.3 安裝前必須先確認的兩件事第一件是磁盤空間。Miniconda 本體裝完大概 500MB 左右但每個虛擬環(huán)境少則幾百 MB、多則兩三個 G裝了深度學(xué)習框架之后你會看到這個數(shù)字所以別把它裝在一個只剩兩個 G 的盤里。我一般會單獨留一個目錄比如D:\dev\miniconda3或者~/dev/miniconda3把所有環(huán)境集中在一個地方將來清理、備份、遷移都方便。第二件是路徑里絕對不能有中文和空格。這條是老生常談但每年還是有人栽在上面。conda 在創(chuàng)建環(huán)境時會往路徑里寫大量腳本文件一旦路徑含空格或中文某些包的編譯腳本、shell 激活腳本就會解析失敗報出來的錯誤往往莫名其妙比如The system cannot find the path specified或者某個.bat無法執(zhí)行排查半天最后發(fā)現(xiàn)是路徑問題。安裝目錄名、你的 Windows 用戶名、項目文件夾名這三處都要檢查。2. 裝 MinicondaWindows 和 macOS 的分步操作2.1 Windows 上的安裝細節(jié)與那個容易點錯的選項到 Miniconda 的官方下載頁選對應(yīng)系統(tǒng)、對應(yīng)架構(gòu)現(xiàn)在基本都是 64 位的安裝包。Windows 上給的是.exe大小一百來兆。下載完雙擊一路 Next中途有兩個地方需要停下來看一眼。第一個是Install for: Just Me / All Users。選 Just Me安裝路徑會在你的用戶目錄下不需要管理員權(quán)限后面用起來最省事選 All Users 會裝到C:\ProgramData下多用戶共用但某些操作需要提權(quán)。個人開發(fā)機我建議 Just Me。第二個是安裝向?qū)ё詈竽琼摰膬蓚€勾選框。第一個是Add Miniconda3 to my PATH environment variable官方建議不要勾原因很簡單勾了之后 conda 的 base 環(huán)境會永久性混進系統(tǒng) PATH你打開任何終端都默認在那個環(huán)境里容易和系統(tǒng)里其他軟件自帶的 Python 沖突。第二個是Register Miniconda3 as my default Python這個可以勾問題不大。正確做法是不勾 PATH然后用開始菜單里那個 Anaconda Prompt (Miniconda3) 作為專用入口——這個快捷方式啟動時會自動幫你初始化 conda不污染系統(tǒng)環(huán)境。安裝完成后從開始菜單打開 Anaconda Prompt敲conda --version能打出類似conda 24.x.x的字樣就說明裝好了。如果提示不是內(nèi)部或外部命令八成是你從普通的 cmd 或 PowerShell 打開的換那個專用快捷方式再試。2.2 macOS 上的安裝與 shell 初始化的坑macOS 上給的是.pkg安裝包雙擊按提示走默認會裝到~/miniconda3。裝完之后一定要做 shell 初始化這一步很多人漏掉結(jié)果終端里怎么敲 conda 都沒反應(yīng)?，F(xiàn)在的 macOS 默認 shell 是 zsh所以~/miniconda3/bin/conda init zsh如果你還在用 bash就把zsh換成bash。這個命令做的事是在你的~/.zshrc里追加一段 conda 初始化腳本。執(zhí)行完必須關(guān)掉終端重開或者手動source ~/.zshrc否則不生效。注意如果你的 Mac 是 Apple 芯片裝之前先確認下載的是 arm64 版本的安裝包。裝錯了 x86 版本conda 也能跑但會走 Rosetta 轉(zhuǎn)譯裝某些帶編譯擴展的包會明顯變慢甚至裝不上。Linux 上沒有圖形界面直接跑安裝腳本bash Miniconda3-latest-Linux-x86_64.sh一路回車看協(xié)議最后問是否 conda init 選 yes。裝完同樣重開終端。2.3 裝完馬上要做的三件配置第一件關(guān)掉 base 環(huán)境的自動激活。默認情況下你每開一個終端前面都會多一個(base)這意味著你所有的隨手操作都在 base 環(huán)境里做時間長了 base 就被污染了。執(zhí)行conda config --set auto_activate_base false之后再開終端就是干凈的需要哪個環(huán)境再手動 activate。這個習慣我強烈建議從第一天就養(yǎng)成我見過太多人 base 環(huán)境被搞壞之后不得不重裝 Miniconda。第二件配國內(nèi)鏡像源如果你在下載速度上確實有困擾。conda 默認走的是境外服務(wù)器裝大包時經(jīng)?？ㄗ』蛘邤?。鏡像源配置內(nèi)容是環(huán)境相關(guān)的各家鏡像站給的命令會變正常做法是到鏡像站官方說明頁照著抄那幾行conda config --add channels和conda config --set show_channel_urls yes。配置完之后conda config --show channels可以確認順序鏡像要放在前面才有意義。第三件驗證下載配置是否真的生效。隨便建個小環(huán)境試試conda create -n testenv python3.11看下載速度正常不正常。如果某個包一直卡在 Solving environment 半天不動那多半是源的問題或者 conda 版本太老可以考慮conda update -n base conda升一下本體。3. 創(chuàng)建虛擬環(huán)境命名、版本與依賴落地的實戰(zhàn)做法3.1 環(huán)境命名與目錄集中管理conda create -n 環(huán)境名 python版本是基本語法但環(huán)境名怎么起是有講究的。我的習慣是項目名 主要依賴的大版本比如cv-torch2、nlp-py311、web-django5。這么起名有兩個好處一是以后conda env list一眼能看出每個環(huán)境是干嘛的二是同時存在多個版本時不會搞混。不要用test1、env、myenv這種名字三個月后你自己都認不出來那是干什么的。環(huán)境默認存放在 Miniconda 安裝目錄的envs下面。如果你想讓環(huán)境放在別處比如 C 盤吃緊想放 D 盤可以在~/.condarc里加一行envs_dirs指定首選路徑envs_dirs: - D:\dev\conda-envs - ~/miniconda3/envs寫成列表的意思是有多個候選conda 會優(yōu)先用第一個可寫的。這種集中管理的思路在環(huán)境變多之后特別有用——清理、備份都只是對一個目錄操作。創(chuàng)建環(huán)境的命令本身很簡單但有幾個參數(shù)值得記住conda create -n cv-torch2 python3.11 numpy pandas -ypython3.11是指定解釋器版本盡量寫具體別只寫python否則 conda 會拉最新的將來復(fù)現(xiàn)時可能對不上。后面可以直接跟要裝的包conda 會在創(chuàng)建時一次性解決依賴比先建環(huán)境再一個個裝效率高得多。-y是跳過確認腳本化時有用手動操作可加可不加。另外還有--clone參數(shù)值得一提。當你需要一個當前環(huán)境的副本做實驗時怕把好好的環(huán)境搞壞conda create -n cv-torch2-exp --clone cv-torch2比重新裝一遍依賴快得多尤其在包很多的時候差距明顯。3.2 用 environment.yml 把環(huán)境存下來在同一個項目里反復(fù)建環(huán)境的場景下手動一條條敲conda install是低效且不可復(fù)現(xiàn)的。正確做法是從項目一開始就用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 在構(gòu)建環(huán)境時會先裝完 conda 那部分再用 pip 補齊。用這個文件一步建環(huán)境conda env create -f environment.yml反過來如果你已經(jīng)用手動方式建好了一個環(huán)境想把它導(dǎo)出成文件conda env export --no-builds environment.yml這里加--no-builds是我個人的強烈建議。默認導(dǎo)出的內(nèi)容里每個包都帶一個 build 字符串比如numpy-1.26.4-py311h1234567_0后面那一串它和具體的操作系統(tǒng)、架構(gòu)強綁定你把文件發(fā)給用不同系統(tǒng)的同事大概率裝不上。去掉 build 字符串之后conda 會自己挑當前平臺合適的版本兼容性大幅提升。一個實操細節(jié)conda env export導(dǎo)出的內(nèi)容會把你環(huán)境里所有包都列出來包括你隨手裝上、根本沒在用的那些。干凈的做法是手動維護一份精簡的依賴清單只寫項目真正需要的頂層依賴讓 conda 自己去解傳遞依賴。這份手工清單才是真正值得提交到代碼倉庫的東西。3.3 環(huán)境創(chuàng)建完成后必須驗證的幾件事建完環(huán)境不要直接開始寫代碼先做一輪驗證能省掉后面大量為什么跑不起來的困惑。先激活conda activate cv-torch2注意 Windows 上如果你用的是老的 cmd可能conda activate不認需要先用conda init cmd.exe初始化一次并重開窗口。PowerShell 同理conda init powershell。激活之后看解釋器路徑對不對where python # Windows which python # macOS / Linux輸出里應(yīng)該包含.conda或者envs\cv-torch2這樣的路徑。如果打出來的是系統(tǒng)自帶那個 Python說明激活沒生效多半是 shell 沒初始化好。然后驗證版本和關(guān)鍵庫python --version python -c import numpy; print(numpy.__version__)最后看一眼環(huán)境列表確認新環(huán)境確實存在conda env list帶星號*的那個是你當前激活的環(huán)境。這個命令以后你會天天用值得記熟。4. 讓 VS Code 認出你的 conda 環(huán)境4.1 裝什么擴展、哪個才是必須的VS Code 里和 Python 相關(guān)的擴展有好幾個裝的次序會影響體驗。必須裝的是官方那個 Python 擴展作者是 Microsoft它負責語言服務(wù)、調(diào)試、運行、環(huán)境發(fā)現(xiàn)。裝了它之后會自動帶上一個 Pylance提供類型推斷和代碼跳轉(zhuǎn)不用單獨裝。如果你經(jīng)常寫 Jupyter Notebook再補一個 Jupyter 擴展。有一個常見的困惑是裝了 Python 擴展之后右下角/狀態(tài)欄沒有顯示當前解釋器版本。這是因為新版 VS Code 把解釋器選擇器移到了別的位置通常是編輯器右上角的那個按鈕或者按CtrlShiftP輸入Python: Select Interpreter直接調(diào)出來。我一般直接記這個命令面板路徑比找按鈕快。4.2 解釋器沒有被自動識別怎么辦正常情況下 VS Code 會自動掃描常見安裝路徑把你的 conda 環(huán)境列出來。但如果你安裝時選了自定義目錄比如裝到了 D 盤它可能掃不到。這時候要手動把路徑告訴它。在 VS Code 的設(shè)置里搜python.defaultInterpreterPath填入你目標環(huán)境里解釋器的完整路徑。比如 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 的轉(zhuǎn)義規(guī)則寫單斜杠會解析失敗。第二行那句activateEnvironment的意思是在 VS Code 內(nèi)置終端里打開新終端時自動激活當前選中的 conda 環(huán)境這個配上之后體驗提升非常明顯不用每次手動敲conda activate。4.3 內(nèi)置終端的雙激活陷阱這是我最想強調(diào)的一個坑因為它太隱蔽了。你在 VS Code 里可能同時遇到兩件事一是你手動在終端里conda activate了某個環(huán)境二是 VS Code 的 Python 擴展根據(jù)defaultInterpreterPath又自動激活了一次。兩個來源不一致時就會出現(xiàn)編輯器里提示的庫版本和終端里 import 出來的版本對不上的詭異現(xiàn)象。排查這個問題的辦法很簡單在出錯的那個終端里直接跑python -c import sys; print(sys.executable)看它指向哪。如果和你編輯器狀態(tài)欄顯示的解釋器路徑不一致那就是激活沖突。修復(fù)方案是二選一別讓兩個機制同時管要么在 settings 里把python.terminal.activateEnvironment關(guān)掉、全靠手動 activate要么把它開著、并且保證defaultInterpreterPath指向的就是你要用的那個環(huán)境然后終端里不要再手動切換。還有一個 Windows 特有的情況PowerShell 默認的執(zhí)行策略可能禁止運行 conda 的激活腳本報錯大意是無法加載文件因為在此系統(tǒng)上禁止運行腳本。這不是 conda 的問題是 PowerShell 的安全策略。解決辦法是以管理員身份開一次 PowerShell執(zhí)行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重開終端。4.4 用 launch.json 固定調(diào)試時的解釋器當你需要打斷點調(diào)試時光選好解釋器可能還不夠因為 VS Code 的調(diào)試器會單獨讀launch.json的配置。一個穩(wěn)妥的寫法是把解釋器路徑直接寫進去避免它自己猜{ 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是因為很多庫比如帶進度條的、需要交互輸入的在內(nèi)置控制臺里表現(xiàn)異常用集成終端能看到真實的終端輸出出問題好排查。justMyCode設(shè)為 true 表示調(diào)試時只單步進入你自己的代碼不跳進標準庫和第三方庫里這是默認推薦值。5. 那些踩過才知道疼的細節(jié)5.1 激活失敗的一串排查鏈路conda activate不生效是最常見的求助點。我把完整排查鏈路列一下按這個順序試基本都能定位第一步確認 conda 本身可用conda --version如果不認識這個命令說明 shell 沒初始化。Windows 用conda init powershell或conda init cmd.exemacOS/Linux 用conda init zsh或conda init bash。執(zhí)行完必須重開終端窗口這是最多人漏掉的一步。第二步如果你把整個 Miniconda 目錄搬過位置比如從 C 盤挪到 D 盤那所有環(huán)境里的絕對路徑都失效了conda activate會指向不存在的路徑。這種情況得修envs目錄里的路徑記錄或者干脆按environment.yml重建環(huán)境——重建通常比修更快這也是我強調(diào)用 yml 管理依賴的現(xiàn)實理由。第三步確認 shell 的配置文件里那行 conda 初始化代碼沒被其他東西覆蓋。比如有的用戶裝完 conda 之后又裝了別的命令行工具它會在.zshrc末尾追加自己的初始化把 conda 那一段擠到前面去執(zhí)行依賴 conda 的命令就失敗了。用cat ~/.zshrc看一眼順序conda 那段應(yīng)該靠后一點。第四步Windows 上如果從資源管理器直接在某文件夾里在此處打開終端有時候拿到的是一份沒加載用戶配置的環(huán)境。這種情況換從開始菜單啟動專用終端或者手動 cd 過去。5.2 環(huán)境名拼錯和conda clean的空間回收conda activate cv-troch2拼錯一個字母conda 會直接報EnvironmentNameNotFound這個錯誤提示其實挺清楚的但新手常以為是自己環(huán)境沒建成功。養(yǎng)成conda env list先看一眼的習慣比猜快得多。另一個值得早點知道的命令是conda clean。conda 的包緩存策略很大方你每裝一次包下載的壓縮包和解壓出來的副本都會留著環(huán)境建多了之后pkgs目錄能吃掉好幾個 G。定期清理conda clean --all執(zhí)行時會列出要刪的東西讓你確認。我一般一個月跑一次尤其在做完大版本升級之后。注意這個操作只是刪緩存不會刪掉你正在用的環(huán)境放心跑。5.3 環(huán)境版本回退與別再重裝的兜底某天你更新了一個包代碼跑掛了想回到之前的狀態(tài)——這時候如果你沒留environment.yml就只能靠運氣。所以我在每個項目的根目錄都放一份 yml并且每次做出能跑通的改動之后就更新它。這個習慣救過我很多次。如果只是想單獨回退某個包conda install 包名舊版本號就行。conda 會自動把沖突的依賴一并調(diào)整。真正麻煩的是跨 Python 大版本的回退比如環(huán)境建在 3.12但某個庫只支持到 3.11這種情況下改環(huán)境里的 Python 版本很折騰更省事的做法是新建一個 3.11 的環(huán)境把代碼和依賴清單搬過去。這也印證了前面說的命名習慣的價值——cv-py311和cv-py312兩個環(huán)境并存誰是誰一目了然。5.4 幾個我反復(fù)見到的疑問第一個我能不能把所有項目都放在 base 環(huán)境里技術(shù)上可以實踐上不要。base 環(huán)境一旦被某個項目的依賴搞壞修復(fù)成本遠高于重建而重建意味著你要重裝所有東西。base 只用來放 conda 自己需要的少數(shù)幾個包這是我的原則。第二個虛擬環(huán)境會占用很多硬盤嗎會。一個只裝 numpy 和 pandas 的環(huán)境大概三五百兆裝了深度學(xué)習框架的能到三四個 G。所以要定期用conda env list回頭看把廢棄的環(huán)境conda env remove -n 環(huán)境名刪掉別留著當紀念品。第三個VS Code 里顯示的庫版本和我 import 出來的不一樣?；氐?4.3 那節(jié)跑sys.executable看路徑九成是解釋器沒選對或者激活沖突。第四個能不能直接復(fù)制環(huán)境文件夾來達到復(fù)制的效果不建議。環(huán)境里有大量寫死了絕對路徑的腳本和配置直接復(fù)制到別的路徑很多包會找不到自己的依賴。用--clone參數(shù)或者 yml 重建才是正路。把這幾件事從頭到尾走一遍其實也就半小時的事但它決定了你后面幾個月的開發(fā)體驗順不順。我自己是在被全局環(huán)境坑過兩次之后才徹底轉(zhuǎn)向一項目一環(huán)境 yml 管依賴這套做法的切換過去之后再沒因為環(huán)境問題浪費過一整天。