2025 從零開始 | 在 VSCode 用 venv 打造專屬 Python 專案

2,126

打造 Python 專屬專案，使用 VSCode + venv 建立專業的 Python 開發環境，並整合 Git 版本控制，讓你從第一天就養成良好的開發習慣！
您是不是也遇過這些情況：

  • 「在我的電腦可以跑，為什麼你的不行？」 —— 套件版本衝突，團隊開發陷入混亂。
  • 「我只是更新了一個套件，整個專案就壞了！」 —— 全域環境被污染，不同專案互相干擾。
  • 「這個專案需要哪些套件？我忘記了…」 —— 缺乏依賴管理，重現環境變成惡夢。

這些痛點，90% 的 Python 開發者都踩過。
而解決方案，其實很簡單：虛擬環境 + 專案化架構 + Git 版本控制。

venv

什麼是 Python 虛擬環境？

Python 虛擬環境是一個獨立的 Python 執行環境，允許你在同一台機器上為不同專案創建隔離的環境。每個虛擬環境都有自己的：

  • Python 二進制文件
  • 套件安裝目錄
  • 獨立的全域變數
  • 環境變數設定

這樣做的好處是：

  • 方便團隊協作，確保環境一致性
  • 不同專案可以使用不同版本的 Python 和套件
  • 避免系統 Python 環境被污染

虛擬環境 vs 容器化

雖然 Docker 等容器技術也能解決環境隔離問題，但虛擬環境更輕量級：

  • 不需要額外安裝 Docker
  • 啟動速度快
  • 資源消耗低
  • 適合本地開發階段使用

如何使用虛擬環境？

創建和使用 venv 非常簡單：

# Create a virtual environment
python -m venv my_project_env

# Activate virtual environment (Linux/macOS)
source my_project_env/bin/activate

# Activate virtual environment (Windows)
my_project_env\Scripts\activate

# Install packages
pip install package_name

# Deactivate virtual environment
deactivate

開發環境

作業系統

  • macOS / Linux / Windows 皆可

安裝 Python

  • 建議版本：Python 3.9 ~ 3.12
  • 檢查是否已安裝：
python3 --version

如果沒有安裝，請到 Python 官方網站 下載並安裝。

安裝 VSCode

Git（版本控制用）

  • 檢查是否安裝：
git --version

若未安裝，可到 Git 官方網站 下載。

建立 Python 專案

建立專案資料夾
先在你的工作目錄建立一個資料夾，例如：

mkdir my_python_project
cd my_python_project

專案結構

my_python_project/     # 專案根目錄
├── my_project_env/    # 虛擬環境資料夾（不會上傳到 Git）
├── app.py             # 主程式
├── requirements.txt   # 套件依賴清單
└── .gitignore         # Git 忽略規則

建立虛擬環境
在終端機輸入：

python3 -m venv my_project_env

這會在專案底下建立一個 my_project_env 資料夾，裡面放著專案專用的 Python 解譯器與套件。

啟動虛擬環境
macOS / Linux：

source my_project_env/bin/activate

Windows（PowerShell）：

my_project_env\Scripts\Activate.ps1

啟動後，終端機前面會出現 (my_project_env)，代表你已經在專案的虛擬環境裡。

在 VSCode 開啟專案

code .
  • 安裝 Python 插件
  • VSCode 會偵測 my_project_env 中的虛擬環境，左下角選擇正確的解譯器

建立 app.py 測試檔
在專案根目錄新增 app.py：

print("Hello World from my_project_env!")

執行程式
確保終端機在虛擬環境 (my_project_env) 內：

python app.py

你會看到：

Hello World from my_project_env!

離開虛擬環境 (my_project_env)
在虛擬環境啟動的終端機裡輸入：

deactivate
  • 終端機前面的 (my_project_env) 會消失。
  • 你就回到系統全域 Python 環境了。
  • 不同作業系統（macOS / Linux / Windows）都一樣用 deactivate。

不要把 “虛擬環境資料夾” 推到 Git

  • 佔空間（幾百 MB）
  • 不同系統不相容
  • 可用 requirements.txt 重建

建立 .gitignore 後加入以下：

my_project_env/

保存環境套件列表（pip freeze）

在虛擬環境中輸入：

pip freeze > requirements.txt

會生成如下：

PySide6==6.5.2
numpy==1.25.1
pandas==2.0.3

重建環境

別人 clone 您的專案後：

python3 -m venv my_project_env
source my_project_env/bin/activate # 啟動虛擬環境
pip install -r requirements.txt

如果是 Windows PowerShell，啟動虛擬環境的指令會改成：

.\my_project_env\Scripts\Activate.ps1    # Activate the virtual environment (Windows PowerShell)

這樣就能獲得一模一樣的開發環境。

結論

透過 VSCode + venv，我們成功打造了一個乾淨、獨立、可重現的 Python 開發環境，並且用 Git 管理程式碼版本，避免了套件版本衝突與全域環境污染的老問題。

記住幾個關鍵習慣：

  • 每個專案都建立獨立虛擬環境
  • 用 .gitignore 忽略虛擬環境資料夾
  • 用 pip freeze > requirements.txt 保存套件版本
  • 在新環境用 pip install -r requirements.txt 一鍵重現

這套流程不只適合初學者，也是專業團隊維持專案穩定性、可移植性的基礎。
從今天開始，你就可以跟「在我電腦可以跑」的尷尬說再見了。

標籤

相關文章