?? Python 項(xiàng)目標(biāo)準(zhǔn)化開發(fā)與維護(hù)指南

第一階段：全局環(huán)境凈化 (Global Cleanup)

?? 警告：此階段操作的是你電腦系統(tǒng)的全局 Python 環(huán)境。請謹(jǐn)慎操作，確保只清理第三方雜包，保留核心工具。

1. 升級核心構(gòu)建工具

首先確保全局的 pip、setuptools 和 wheel 是最新版，以防止后續(xù)構(gòu)建失敗。

python -m pip install --upgrade pip setuptools wheel

2. 清洗全局依賴 (PowerShell 專用)

此命令會列出所有已安裝包，排除核心包 (pip, setuptools, wheel, packaging) 和可編輯模式包 (-e)，然后批量卸載其余所有包。

注意：我額外加入了 packaging 到排除列表，因?yàn)樗?pip 的內(nèi)部強(qiáng)依賴，誤刪會導(dǎo)致 pip 崩潰。

# 復(fù)制并運(yùn)行以下整行命令
pip freeze | ForEach-Object { $_.Split('=')[0] } | Where-Object { $_ -notin @('pip', 'setuptools', 'wheel', 'packaging', '-e') } | ForEach-Object { pip uninstall -y $_ }

第二階段：項(xiàng)目虛擬環(huán)境搭建 (Project Setup)

? 最佳實(shí)踐：每個(gè)項(xiàng)目都應(yīng)擁有獨(dú)立的虛擬環(huán)境，互不干擾。推薦將環(huán)境文件夾命名為 .venv（加點(diǎn)表示隱藏）。

1. 創(chuàng)建虛擬環(huán)境

在項(xiàng)目根目錄下執(zhí)行（二選一，推薦 .venv）：

# 方案 A (推薦): 創(chuàng)建名為 .venv 的隱藏文件夾
python -m venv .venv

# 方案 B: 創(chuàng)建名為 venv 的普通文件夾
python -m venv venv

2. 激活虛擬環(huán)境

激活后，命令行提示符前會出現(xiàn) (.venv) 或 (venv) 標(biāo)識。

• Windows PowerShell:

  # 如果文件夾叫 .venv
  .\.venv\Scripts\Activate.ps1
  
  # 如果文件夾叫 venv
  .\venv\Scripts\Activate.ps1
  

  ?? 遇到報(bào)錯(cuò)？ 如果提示“禁止運(yùn)行腳本”，請以管理員身份運(yùn)行 PowerShell 并執(zhí)行：
  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

• macOS / Linux / Git Bash:

  # 如果文件夾叫 .venv
  source .venv/bin/activate
  
  # 如果文件夾叫 venv
  source venv/bin/activate
  

3. 安裝項(xiàng)目依賴

確保激活成功后，再安裝項(xiàng)目所需的庫。這些庫只會安裝在當(dāng)前虛擬環(huán)境中，不會污染全局。

pip install -r requirements.txt

第三階段：項(xiàng)目運(yùn)行與開發(fā) (Run & Dev)

? 確認(rèn)狀態(tài)：運(yùn)行任何命令前，請?jiān)俅未_認(rèn)命令行前方有 (.venv) 標(biāo)識。

1. 運(yùn)行普通 Python 腳本

python run.py

2. 啟動 FastAPI / Uvicorn 服務(wù)

適用于現(xiàn)代異步 Web 框架開發(fā)（支持熱重載）：

# 格式：uvicorn [文件路徑]:[變量名] --reload --port [端口]
uvicorn src.api.main:app --reload --port 8000

• src.api.main: 對應(yīng)文件 src/api/main.py
• app: 對應(yīng)該文件中實(shí)例化的 FastAPI 對象 app = FastAPI()

?? 常用速查表 (Cheat Sheet)

?? 核心原則總結(jié)

1. 全局要干凈：全局只留 pip, setuptools, wheel, packaging。
2. 項(xiàng)目要隔離：每個(gè)項(xiàng)目必須有自己的 .venv。
3. 激活再操作：安裝包、運(yùn)行代碼前，必須先激活虛擬環(huán)境。