文章目錄
Python 專案換到另一台電腦時，最花時間的通常是重建環境：要裝哪個 Python 版本、虛擬環境建在哪裡、當初 pip install 過哪些套件。用 uv 管理專案，這三件事都會記在專案資料夾裡，VS Code 打開資料夾就能找到專案內的 .venv，換電腦時執行一次 uv sync 就能把環境補回來。
uv 是 Astral 開發的 Python 套件與專案管理工具，可以下載指定版本的 Python、建立虛擬環境，並把依賴寫進 pyproject.toml 與 uv.lock。電腦上不需要先另外安裝 Python。以下以 Windows 為例。
安裝 uv
依照 uv 官方安裝文件，Windows 可以在 PowerShell 執行官方安裝腳本：
1powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
習慣用套件管理器的話，也可以用 winget install --id=astral-sh.uv -e 安裝。
安裝腳本會把 uv.exe 與 uvx.exe 放在使用者目錄下的 .local\bin，並加入 PATH。
開一個新的終端機視窗，確認指令可以執行：
1uv --version
有印出版本號就代表安裝完成。原本開著的終端機還抓不到 uv 時，關掉重開即可，因為 PATH 只在新開的視窗生效。
用 VS Code 開啟專案資料夾
VS Code 以資料夾作為工作區，Python 的解譯器、虛擬環境與設定都跟著這個資料夾走。先建立一個空資料夾，例如 python-project，對它按右鍵選「以 Code 開啟」。Windows 11 的右鍵選單沒有這個項目時，先按「顯示其他選項」，或按住 Shift 再按右鍵。
接著到左側「延伸模組」搜尋 Python，安裝 Microsoft 發佈的 Python 延伸模組。它負責語法提示、偵錯與解譯器切換，安裝時會一併帶入 Pylance、Python Debugger 與 Python Environments。
建立專案並指定 Python 版本
按 Ctrl + ` 開啟 VS Code 的終端機，確認路徑在專案資料夾裡。先列出 uv 可以使用的 Python 版本：
1uv python list
清單中標示 <download available> 的是 uv 可以下載的版本，有路徑的則是電腦上已經有的 Python，包含 uv 先前下載過的版本。
接著初始化專案，並用 --python 指定版本。本文截圖使用 3.10，其他版本改成對應的版本號即可：
1uv init --python 3.10
uv init 會建立 pyproject.toml、.python-version、main.py、README.md 與 .gitignore，資料夾還不是 Git repo 時也會一併初始化 Git。.python-version 記錄專案要用的 Python 版本，電腦上沒有這個版本時，uv 會在需要時自動下載。
.venv 要到第一次執行 uv run、uv sync 或 uv add 時才會建立，預設放在專案資料夾內。執行一次範例程式就能把環境建好：
1uv run main.py
終端機印出 Hello from python-project!，資料夾中也會多出 .venv 與 uv.lock。
讓 VS Code 使用專案內的 .venv
VS Code 會自動搜尋工作區中的 .venv，通常不需要手動設定。不過電腦上同時裝了好幾個 Python 時，還是值得確認一次。看右下角狀態列的 Python 版本，有顯示 ('.venv') 就代表已經接上專案環境。
電腦上已經裝過其他 Python 時，狀態列可能仍顯示原本的版本，下圖右下角就是 3.10.11。這時按 Ctrl + Shift + P 執行「Python: Select Interpreter」，選擇路徑為 .\.venv\Scripts\python.exe 的那一項，VS Code 也會把它標成「推薦項目」。
解譯器選錯時，最常見的症狀是程式用 uv run 可以執行，編輯器裡卻標出「找不到模組」的紅色波浪線。這是因為 Pylance 還在用另一個 Python 分析程式碼，切回 .venv 後就會消失。
用 uv 管理套件
改用 uv 之後，安裝套件改用 uv add。它會把套件裝進 .venv，同時寫進 pyproject.toml 並更新 uv.lock，專案用了哪些套件都有紀錄：
1uv add requests
不需要的套件用 uv remove 移除，pyproject.toml、uv.lock 與 .venv 都會同步移除：
1uv remove requests
執行程式時優先用 uv run。它會先確認 .venv 和 pyproject.toml、uv.lock 一致，再執行指令，不需要先手動啟用虛擬環境。
在另一台電腦重建環境
把專案推到 Git 時，要一起提交 pyproject.toml、uv.lock 與 .python-version，.venv 則不提交（uv init 產生的 .gitignore 已經排除它）。在另一台電腦 clone 專案後，執行：
1uv sync
uv 會依照 .python-version 準備 Python，再依照 uv.lock 安裝完全相同版本的套件。手動改過 pyproject.toml 之後，也是用 uv sync 讓環境重新對齊。
從 requirements.txt 轉換
既有專案只有 requirements.txt 時，先執行 uv init，再把清單匯入：
1uv add -r requirements.txt
之後新增套件都改用 uv add，依賴就會集中記錄在 pyproject.toml。
總結
VS Code + uv 的分工很清楚：uv 管 Python 版本、.venv 與套件，VS Code 只需要指向專案內的 .venv。建立專案用 uv init --python 版本號，加套件用 uv add，執行用 uv run，換電腦用 uv sync。只要 pyproject.toml、uv.lock 與 .python-version 跟著專案走，環境就能在任何一台電腦重建。
