在實際的軟件開發中，Python 環境混亂、依賴衝突、版本不一致等問題，是許多初學者和工程團隊最常遇到的痛點。為了避免：

  • 同一台機器上多個項目互相污染
  • 版本升級導致舊項目無法運行
  • 依賴越來越多、pip freeze 輸出雜亂無章
  • 跨團隊開發難以復現項目環境

我們必須掌握**環境管理（Environment Management）與依賴管理（Dependency Management）**這兩項核心能力。

本篇文章對 Python 官方內置的虛擬環境工具 venv 以及現代依賴管理工具 Poetry 進行系統講解，幫助你構建可靠、可復現的 Python 開發環境。

1. 為什麼環境管理如此關鍵？

如果你遇過以下問題，那麼你一定需要虛擬環境：

  • A 項目用 Django 2.x，B 項目用 Django 4.x，衝突怎麼辦？
  • 升級 numpy 後，某個舊腳本無法運行？
  • 新人加入團隊，不知道安裝哪些版本才能跑起來？
  • 項目部署到生產服務器後報錯 “ModuleNotFoundError”？

這些問題的根源是：

不同項目需要不同的 Python 包依賴，不能在同一個全局環境中混合。

因此，“一個項目一個獨立環境”已經成為現代開發的事實標準。

2. venv：Python 官方內置虛擬環境工具

venv 是 Python 3 內置的環境隔離機制，特點是：

  • 無需安裝額外工具
  • 簡單輕量
  • 能滿足大多數輕量項目需求
  • 支持 Windows / macOS / Linux

2.1 創建虛擬環境

在項目目錄下執行：

python3 -m venv venv

創建一個名為 venv 的虛擬環境目錄，這裏麪包含：

  • 獨立的 Python 可執行文件
  • 獨立的 site-packages 目錄
  • pip 專屬版本

2.2 激活虛擬環境

macOS / Linux：

source venv/bin/activate

Windows（命令行）：

venv\Scripts\activate

激活後終端前面會出現 (venv) 前綴。

2.3 安裝依賴

虛擬環境激活後安裝的包只會影響當前項目：

pip install requests
pip install flask

2.4 導出依賴列表（requirements.txt）

pip freeze > requirements.txt

團隊成員可以通過：

pip install -r requirements.txt

來複現同樣的環境。

2.5 退出虛擬環境

deactivate

3. venv 的不足與痛點

雖然 venv 足夠基礎開發，但仍存在一些明顯不足：

  • requirements.txt 不記錄依賴樹，容易出現“幽靈衝突”
  • 不支持鎖定依賴（鎖文件）
  • 無法方便管理多個命令、腳本
  • 缺乏更加現代化的自動依賴解析功能
  • 對多項目依賴管理支持較弱

因此，大型項目、團隊協作項目往往需要使用更現代的管理工具，例如 Poetry。

4. Poetry：現代 Python 依賴 & 項目管理工具

Poetry 的目標是提供一個完整、自洽的 Python 項目管理體驗，包括：

  • 環境管理（virtualenv 自動管理）
  • 依賴管理（自動解析正確版本）
  • 鎖文件（完全可復現的依賴版本）
  • 構建和發佈包
  • 統一項目配置 (pyproject.toml)

它已經成為近年來最受企業和開源社區歡迎的 Python 項目工具。

5. Poetry 快速上手

5.1 安裝 Poetry

官方推薦腳本安裝：

curl -sSL https://install.python-poetry.org | python3 -

安裝完成後通過：

poetry --version

確認是否成功。

6. 使用 Poetry 創建項目

在任意目錄執行：

poetry new myproject

自動生成標準項目目錄結構：

myproject/
    myproject/
        __init__.py
    tests/
    pyproject.toml

所有項目配置放在 pyproject.toml 中。

7. Poetry 依賴管理

7.1 添加依賴

poetry add requests
poetry add flask

Poetry 會自動解析可用版本，並生成：

  • pyproject.toml（版本範圍）
  • poetry.lock（鎖定具體版本）

7.2 安裝項目依賴

poetry install

這會：

  • 創建並管理獨立的虛擬環境
  • 安裝所有依賴
  • 保證可復現的版本一致性

7.3 查看虛擬環境路徑

poetry env info

7.4 激活虛擬環境

poetry shell

退出：

exit

8. Poetry 常見功能

① 添加開發依賴

poetry add --dev pytest black

② 移除依賴

poetry remove flask

③ 更新所有依賴

poetry update

④ 構建包

poetry build

⑤ 發佈到 PyPI

poetry publish

Poetry 完整覆蓋了從開發到發佈的流程。

9. venv 與 Poetry 對比總結

功能 venv Poetry
是否內置 ✔ 是 ❌ 需安裝
依賴解析 手動（pip） 自動
鎖文件 無 ✔ 有（poetry.lock）
可復現性 一般 很高
項目結構 自行維護 自動生成
包發佈支持 無 ✔ 支持
團隊開發 需要技巧 更高效
適用場景 小項目、腳本 企業級項目、多人協作

一句話總結：

  • venv：輕量、基礎、簡單
  • Poetry：現代、強大、專業

10. 實踐建議：如何選擇？

如果是單機腳本、一次性任務

→ 使用 venv + requirements.txt

如果是長期維護、多人協作、Web 後端、爬蟲框架、數據分析項目

→ 強烈推薦使用 Poetry

如果你是初學者

→ 建議先用 venv 入門，再用 Poetry 提升工程化能力

結語

無論是 venv 還是 Poetry，目的都是讓項目環境更加可控、穩定、可復現。 掌握這些工具，是成為專業 Python 工程師的重要一步。