有些急性子

AI 代碼今天能跑明天就崩？5 分鐘搞定虛擬環境#

你一定遇到過這個問題#

昨天你讓 ChatGPT 寫了個數據分析腳本，運行得好好的。

今天你又讓 AI 寫了個爬蟲項目，裝了新版本的 pandas。

結果，昨天的數據分析腳本突然報錯了：

AttributeError: 'DataFrame' object has no attribute 'append'

你懵了：我什麼都沒改，怎麼就不能跑了？

問題出在這裡：新項目需要 pandas 2.0，你用pip install升級了系統裡的 pandas。

但舊項目是基於 pandas 1.5 寫的，pandas 2.0 移除了.append()方法。

系統只能裝一個版本，新項目能跑了，舊項目就崩了。

這篇文章會告訴你：

• 為什麼會出現這種 "按下葫蘆浮起瓢" 的問題
• 專業開發者怎麼解決（虛擬環境）
• 5 分鐘學會用 uv 工具管理虛擬環境
• 3 個新手最容易踩的坑

閱讀時間：8 分鐘
實操時間：5 分鐘
前提：你已經裝好 Python，能運行簡單代碼

第 1 章：為什麼你的項目會互相 "打架"？#

問題的本質#

你的電腦上有一個系統 Python 環境，所有用pip install裝的庫都放在這裡。

C:\Python\Lib\site-packages\
├─ pandas (只能裝一個版本!)
├─ numpy
└─ requests

當你做多個項目時，問題就來了：

場景 1：

• 項目 A（3 個月前寫的數據分析）：需要 pandas 1.5
• 項目 B（今天寫的爬蟲）：需要 pandas 2.0

你裝了 pandas 2.0，系統裡的 1.5 就被覆蓋了。

場景 2：

• 項目 C：AI 聊天機器人，用了 openai 庫
• 項目 D：圖像處理，用了 pillow、opencv

3 個月後，你想重新運行項目 C，但忘了當時裝了哪些庫。

系統環境裡躺著 50 個庫，你也不知道哪些是項目 C 需要的。

場景 3：

你把代碼發給同事，他問："我需要裝什麼庫？"

你回答："呃...pandas、numpy、requests... 還有啥來著？"

同事按你說的裝了，但版本不對，代碼還是報錯。

問題根源#

系統環境 = 公共衣櫃

所有人（所有項目）共用一個櫃子：

• 哥哥要放球鞋，妹妹要放高跟鞋
• 爸爸的皮鞋和媽媽的拖鞋混在一起
• 時間久了，誰都不敢刪東西（怕影響別人）

這就是為什麼你的項目會互相打架。

第 2 章：虛擬環境 - 給每個項目一個獨立房間#

專業開發者的做法#

不要讓所有項目共用系統環境，而是給每個項目創建一個獨立的虛擬環境。

虛擬環境 = 獨立房間

每個項目有自己的房間（.venv文件夾）：

• 項目 A 在自己房間裝 pandas 1.5
• 項目 B 在自己房間裝 pandas 2.0
• 兩個房間互不干擾，各玩各的

一張圖看懂#

你的電腦
│
├─ 系統Python環境 (公共客廳，盡量空著)
│  └─ 只裝Python本身和uv工具
│
└─ 你的項目文件夾
   │
   ├─ 項目A：數據分析
   │  ├─ analysis.py (你的代碼)
   │  └─ .venv (項目A的獨立房間)
   │      └─ pandas 1.5
   │
   └─ 項目B：爬蟲
      ├─ scraper.py
      └─ .venv (項目B的獨立房間)
          └─ pandas 2.0  ← 和項目A不衝突!

核心價值#

1. 版本隔離

• 項目 A 用 pandas 1.5，項目 B 用 2.0，互不影響

2. 依賴清晰

• 每個項目的.venv只裝這個項目需要的庫
• 3 個月後重新運行，依賴關係一目了然

3. 可復現

• 導出requirements.txt，別人一鍵重建你的環境
• 不用再問 "你裝了啥庫"

4. 幹淨可刪

• 刪除項目文件夾，.venv一起刪除
• 系統環境永遠幹淨

類比理解#

不用虛擬環境：

全家人共用一個衣櫃(系統環境)
├─ 爸爸的衣服
├─ 媽媽的衣服
├─ 哥哥的衣服
└─ 妹妹的衣服  ← 全混在一起,誰都不敢刪

用虛擬環境：

每個人有自己的衣櫃(虛擬環境)
├─ 爸爸的房間/.venv  →  放爸爸的衣服
├─ 媽媽的房間/.venv  →  放媽媽的衣服
├─ 哥哥的房間/.venv  →  放哥哥的衣服
└─ 妹妹的房間/.venv  →  放妹妹的衣服
                          ↑ 互不干擾!

第 3 章：實戰 - 5 分鐘學會用 uv 管理虛擬環境#

虛擬環境的概念懂了，現在學怎麼用。

傳統工具是pip + venv，但我推薦直接用uv：更快、更簡單、一站式。

步驟 1：安裝 uv 工具（1 分鐘）#

Windows 用戶：

打開 PowerShell，運行：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Mac/Linux 用戶：

打開終端，運行：

curl -LsSf https://astral.sh/uv/install.sh | sh

安裝完成後，驗證：

uv --version

看到版本號就成功了！

步驟 2：創建你的第一個虛擬環境（2 分鐘）#

假設你要做一個數據分析項目。

2.1 創建項目文件夾

mkdir data-analysis
cd data-analysis

2.2 創建虛擬環境

在項目文件夾裡運行：

uv venv

你會看到提示：

Creating virtual environment at .venv

這個命令在項目文件夾裡創建了一個.venv隱藏文件夾，裡面有：

• 獨立的 Python 解釋器
• 獨立的庫存放空間

2.3 激活虛擬環境

創建完還要 "激活"，告訴電腦 "接下來用這個項目的 Python"。

Windows：

.venv\Scripts\activate

Mac/Linux：

source .venv/bin/activate

激活成功後，終端提示符前面會出現(.venv)：

(.venv) C:\Users\YourName\data-analysis>

這個(.venv)標誌說明：你現在在項目的獨立房間裡了！

步驟 3：安裝庫和運行代碼（2 分鐘）#

現在你在虛擬環境裡，可以裝庫了。

3.1 安裝 pandas

uv pip install pandas

uv 速度很快，幾秒鐘就裝好了。

這個 pandas只裝在.venv裡，不會影響系統環境！

3.2 測試代碼

創建一個test.py文件：

import pandas as pd

print(f"pandas版本: {pd.__version__}")

data = pd.DataFrame({
    '項目': ['A', 'B', 'C'],
    '依賴': ['pandas 1.5', 'pandas 2.0', 'openai 1.0']
})

print("\n虛擬環境讓它們和平共處:")
print(data)

運行：

python test.py

輸出：

pandas版本: 2.x.x

虛擬環境讓它們和平共處:
  項目      依賴
0   A  pandas 1.5
1   B  pandas 2.0
2   C  openai 1.0

成功！

3.3 驗證隔離性（關鍵實驗！）

現在做個實驗，驗證虛擬環境真的隔離了。

實驗 1：退出虛擬環境

deactivate

終端的(.venv)消失了，說明你回到系統環境了。

實驗 2：嘗試運行代碼

python test.py

報錯：

ModuleNotFoundError: No module named 'pandas'

為什麼？因為 pandas 只裝在.venv裡，系統環境沒有！

實驗 3：重新激活虛擬環境

# Windows
.venv\Scripts\activate

# Mac/Linux
source .venv/bin/activate

再運行：

python test.py

又能正常運行了！

這就是虛擬環境的魔法：

• 進房間（activate） → 有家具（pandas）
• 出房間（deactivate） → 毛坯（沒有 pandas）
• 系統環境完全沒變

為什麼選 uv 而不是 pip？#

對新手來說，uv 更簡單、更快。

第 4 章：3 個新手最容易踩的坑#

我教過十幾個朋友，90% 的人會踩這 3 個坑。

坑 1：忘記激活虛擬環境就運行代碼#

症狀：

明明裝了 pandas，還是報錯ModuleNotFoundError。

原因：

你在虛擬環境裡裝的，但在系統環境運行代碼。

解決：

養成習慣：每次運行代碼前，先看終端有沒有(.venv)。

沒有就運行：

# Windows
.venv\Scripts\activate

# Mac/Linux
source .venv/bin/activate

看到(.venv)，再運行代碼。

激活狀態對比：

快速檢查命令：

不確定自己在哪個環境？運行：

python -c "import sys; print(sys.executable)"

輸出包含.venv就對了：

C:\Users\YourName\data-analysis\.venv\Scripts\python.exe  ✅

輸出是系統路徑就錯了：

C:\Python\python.exe  ❌ 需要激活虛擬環境

坑 2：把.venv 文件夾上傳到 Git#

症狀：

項目文件夾幾百 MB，上傳 GitHub 卡半天。

原因：

.venv包含所有庫的完整代碼，體積很大（100-500MB）。

但它不應該上傳，因為：

1. 太大，浪費流量
2. 不同操作系統不兼容（Windows 的不能在 Mac 用）
3. 別人可以用requirements.txt重建

解決：

在項目根目錄創建.gitignore文件：

.venv/

Git 就會忽略.venv。

正確做法：

上傳requirements.txt，不上傳.venv。

導出依賴列表：

uv pip freeze > requirements.txt

別人拿到代碼後：

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

幾秒鐘，環境就一模一樣了！

坑 3：不知道 requirements.txt 的作用#

場景：

3 個月後，你想重新運行項目，但忘了當時裝了哪些庫。

或者，你把代碼發給朋友，他不知道需要裝什麼。

解決：

用requirements.txt記錄依賴。

生成：

uv pip freeze > requirements.txt

文件內容（記錄精確版本）：

pandas==2.1.0
numpy==1.25.2
requests==2.31.0

使用：

uv pip install -r requirements.txt

一鍵安裝所有依賴，版本完全一致。

類比：

requirements.txt = 購物清單
你去超市(PyPI)按清單買東西(安裝庫)

最佳實踐：

每次裝新庫，更新requirements.txt：

uv pip install new-package
uv pip freeze > requirements.txt
git add requirements.txt
git commit -m "add new-package"

第 5 章：一張清單，建立正確習慣#

新項目標準流程（6 步）#

□ 創建項目文件夾: mkdir my-project
□ 進入文件夾: cd my-project
□ 創建虛擬環境: uv venv
□ 激活環境: source .venv/bin/activate (Mac) 或 .venv\Scripts\activate (Win)
□ 安裝依賴: uv pip install pandas numpy
□ 導出依賴: uv pip freeze > requirements.txt
□ 創建.gitignore: echo ".venv/" > .gitignore

把這個 checklist 貼在桌上，養成肌肉記憶。

常用命令速查表#

故障排查清單#

代碼運行失敗？按順序檢查：

□ 虛擬環境激活了嗎？(終端有(.venv)標誌?)
□ 庫裝在虛擬環境裡了嗎？(激活後pip list查看)
□ 終端當前目錄對嗎？(pwd或cd查看)
□ requirements.txt更新了嗎？

3 條鐵律#

鐵律 1：永遠不要在系統環境裝庫
系統環境只裝 Python 和 uv，其他什麼都不裝。

鐵律 2：新項目第一件事 - 創建虛擬環境
養成習慣：mkdir → cd → uv venv → activate

鐵律 3：統一用 uv，不要混用 pip
不要pip install和uv pip install混著用。

下一步學什麼？#

你現在已經掌握了虛擬環境的核心技能！

可選進階方向：

1. 學 Git 版本控制（管理代碼變更）
2. 學 VS Code + Python 插件（專業編輯器）
3. 學 Jupyter Notebook（互動式編程）
4. 深入 uv 高級功能（uv.lock 鎖文件）

最重要的建議：

不要只看教程，動手做 3 個項目：

1. 項目 1：數據分析腳本（用 pandas）
2. 項目 2：簡單爬蟲（用 requests）
3. 項目 3：AI 聊天機器人（用 openai）

每個項目都用虛擬環境，3 個項目做完，你對虛擬環境的理解會比讀 10 遍教程還深。

記住這句話：

"虛擬環境不是麻煩，而是救命稻草。"

現在你知道怎麼避免項目互相打架了，去用 AI 做點有趣的事情吧！