Python uv 核心概念：pyproject.toml、lockfile 與虛擬環境

在狂敲指令之前，先把這四個概念裝進腦子：你會更清楚「依賴寫在哪、lockfile 幹嘛用、venv 什麼時候建」。就像打遊戲先看技能說明，不然會一直送頭。

概念一：pyproject.toml 是專案身份證

專案 metadata 跟依賴都寫在這裡，是 PEP 518 的標準格式。

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.31",
]

• 手動改：直接編輯 pyproject.toml
• 用指令改：uv add requests、uv remove requests 會自動幫你更新

不要混用——要嘛都用手動，要嘛都用指令，不然容易打架。

概念二：uv.lock 是依賴快照

pyproject.toml 寫的是「我要什麼」（例如 requests>=2.31），uv.lock 記錄的是「實際裝了哪些版本」——精確到每一層依賴。

• 為什麼要有 lockfile？ 確保所有人、CI、生產環境裝出來的依賴完全一致，不會「我這能跑你那爆」。
• 要 commit 嗎？ 要。uv.lock 應該進版控，讓團隊與 CI 都用同一份依賴樹。

# 更新 lockfile（例如升級某個套件）
uv lock --upgrade-package requests

概念三：.venv 是專案專屬沙盒

uv 會在專案根目錄建立 .venv，所有 uv add 的套件都裝在這裡，跟系統 Python 隔離。

• 要手動 activate 嗎？ 不用。uv run 會自動用這個環境。
• 要 commit 嗎？ 不要。.venv 應該在 .gitignore 裡。

# 手動同步環境（例如剛 clone 下來）
uv sync
source .venv/bin/activate  # 之後可直接用 python、pytest 等

概念四：uv run 是無腦執行入口

uv run 會：

1. 檢查 lockfile 是否與 pyproject.toml 一致
2. 確保 .venv 與 lockfile 同步
3. 在正確環境下執行你指定的指令

uv run python main.py
uv run pytest
uv run flask run -p 3000

你不用記得 activate，也不用擔心環境錯亂——交給 uv 就好，就像貓不用記得貓砂在哪，身體會自動導航。這種「開了就跑」的體驗，用過就回不去了。

下一步

核心概念消化完，直接進高頻操作：依賴管理、uvx、腳本執行。
👉 常見模式