Python uv 最佳實踐：穩定性與協作清單
進到實際維運後，搞掛環境的往往不是「uv 不夠強」，而是流程跟習慣。下面這份清單可以直接當日常準則用——少踩一次雷，就多一次準時下班。
推薦做法
1) uv.lock 一定要 commit
lockfile 是重現性的基礎。不 commit 等於每人、每台機器、每次 CI 可能裝出不同依賴，重現 bug 會地獄難度。沒 lockfile 的專案，就像沒試穿過的新鞋，上戰場才知道磨腳。
2) .venv 不要 commit
虛擬環境是本地產物，應該在 .gitignore。uv 會自動把 .venv 加進專案 ignore，確認一下就好。
3) 依賴能鎖就鎖
pyproject.toml 裡避免裸寫 requests，盡量寫 requests>=2.31,<3 或更精確。uv add 預設會加合理約束，手動改時別放太寬。
4) CI 用 uv sync 或 uv pip sync
# GitHub Actions 範例
- run: uv sync
- run: uv run pytest先 sync 再跑，確保環境與 lockfile 一致。別在 CI 裡 uv add，那會改 lockfile，容易造成非預期 diff。
5) 開發工具放 optional / dev
uv add --dev pytest ruff mypy測試、lint、型別檢查不影響生產依賴，也不會被打進 wheel。生產 image 只需要 uv sync --no-dev。
常見誤區
誤區 1：混用 pip 跟 uv add
同一個 venv 裡不要又 pip install 又 uv add，lockfile 會對不上。選一條路走到底。
誤區 2：把 uvx 當專案工具用
專案要固定版本的工具（如 pytest、mypy）→ 用 uv add --dev + uv run。
臨時試一下、一次性腳本 → 用 uvx。
誤區 3：不讀 pyproject.toml 就手動改
改依賴盡量用 uv add / uv remove，避免格式跑掉或漏更新 lockfile。
誤區 4：CI 不安裝 uv
很多 CI 現在支援 uv，安裝快、執行更快。用官方 installer 或 pip install uv 都可，別堅持用 pip 解鎖依賴到天荒地老。
誤區 5：專案不用 requires-python
在 pyproject.toml 標明 requires-python = ">=3.12" 等，讓工具跟協作者知道最低版本，避免「我這 3.12 能跑你那 3.8 爆」的慘劇。
照這份清單做，不敢說零故障，但至少少走很多彎路。有問題再翻官方文件，多數坑都有人踩過了。
祝開發順利，依賴乖乖裝、測試都綠燈、CI 不再等你等到天荒地老～ 🦦
（對了，用 uv 之後你會發現：等 pip 轉圈圈的時間，夠你撸三輪貓了。）