# Python 版本好多，而且啟用虛擬環境好麻煩喔
> 最近因為在設定新電腦，當然要下載 Python 來使用，以前都用 `python -m venv venv` 來設定虛擬環境，現在決定要用 pyenv & pyenv-virtualenv 來對 Python 環境管理，所以寫這篇紀錄一下

# 安裝與基本配置
## 安裝 `pyenv` 與 `pyenv-virtualenv`

使用 Homebrew 來安裝核心工具和虛擬環境插件：

brew install pyenv
brew install pyenv-virtualenv

## Shell 初始化配置 ( Zsh/`~/.zshrc`)

為了讓 `pyenv` 和 `pyenv-virtualenv` 能夠自動切換 Python 版本並自動啟用/停用虛擬環境，您需要將初始化指令加入您的 `~/.zshrc` 檔案。

### 編輯你的 ~/.zshrc，加入下面這幾行

# PYENV / PYENV-VIRTUALENV 初始化
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

> [!Warning]
> **因為我有使用 P10k，所以這邊有一個注意事項：**
> 這些指令必須放在 Shell 配置檔案（特別是 Powerlevel10k 或其他自訂提示符號）載入**之後**，但必須確保 `pyenv init` 在 `pyenv virtualenv-init` 之前執行。
>
> 通常放在 `source $ZSH/oh-my-zsh.sh` 之後，`[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh` 之前：

### 配置生效：
儲存檔案後，請執行:

source ~/.zshrc

# 虛擬環境的創建與使用
## 安裝 Python 版本

在創建虛擬環境前，您必須先安裝一個基礎 Python 版本：

pyenv install 3.13.0

> [!Note]
> Install any version you want.

## 創建虛擬環境

基於已安裝的基礎版本，創建一個名為 `venv` 的虛擬環境。

pyenv virtualenv <Python Version> <Virtual Environment Name>

> [!Note]
> 我這邊範例如下，實際上命名虛擬環境時，應該要跟隨專案名稱（e.g. my-blog-api-env, testing-sandbox-env...)，因為**虛擬環境名稱不能重複**
> ```bash
> pyenv virtualenv 3.13.0 venv
> ```

> [!Note]
> 這個指令**不會**在當前資料夾建立任何檔案或資料夾。虛擬環境是集中存放在 `pyenv` 的專用目錄中：`~/.pyenv/versions/3.13.0/envs/venv`。

## 查看所有環境

檢查所有已安裝的 Python 版本和虛擬環境：

pyenv versions

或只查看虛擬環境：

pyenv virtualenvs

> [!Note]
> 輸出會包含基礎版本 (如 3.13.0) 和環境名稱 (如 venv)
> 

## 在專案中啟用虛擬環境（設定連結）

進入您的專案資料夾，執行 `pyenv local` 將該目錄**連結**到特定的虛擬環境。

cd /path/to/your/project
pyenv local venv

- 這邊的 `venv` 是因為我前面創建 venv，而我在這邊選擇這個
- 執行此指令後，專案資料夾會生成一個隱藏檔案：`.python-version`，內容為 `venv`。
- **自動啟用 venv：** 由於您已正確配置 `pyenv virtualenv-init`，當您進入此資料夾時，提示符號前會自動顯示 `(venv)`。

> [!Tip]
> pyenv 提供了三種等級的指令來決定當前使用的 Python 版本或虛擬環境，它們的優先級如下：
> - Shell (最高) --> Local --> Global (最低)
> - `pyenv shell <version>` 僅影響當前終端機工作階段。儲存在環境變數 `PYENV_VERSION`。
> - `pyenv local <version>` 影響當前資料夾及其所有子資料夾。設置在專案目錄下的 `.python-version` 檔案。
> - `pyenv global <version>` 影響所有未指定 Local 或 Shell 版本的目錄。設置位置在 `$(pyenv root)/version` 檔案。

# 虛擬環境的管理與刪除

## 停用虛擬環境

* **自動停用：** 離開專案資料夾（`cd ..`）時會自動停用。
* **手動停用：** 在資料夾內手動切換回全域版本（Global Version）：

    pyenv deactivate

## 移除專案連結（解除設定）

如果您想保留虛擬環境，但讓專案資料夾停止使用它，您應當：

pyenv local --unset
# 等同於手動刪除 .python-version 檔案

## 徹底刪除虛擬環境

當您確認不再需要某個虛擬環境時，請使用 `pyenv uninstall`。這會**永久刪除**環境及其所有套件，並釋放硬碟空間。

> [!Warning]
> 在執行此指令前，請務必先退出正在使用該環境的資料夾。

cd ..  # 先退出專案資料夾
pyenv uninstall venv

在卸載過程中，`pyenv` 會提示兩次，分別刪除**快捷連結**和**實際環境資料夾**：

1. `pyenv: remove .../versions/venv? (y/N)` → **刪除快捷連結**
2. `pyenv-virtualenv: remove .../3.13.0/envs/venv? (y/N)` → **刪除實際內容**

# 結論：
沒什麼結論哈哈，就是這麼簡單的一篇紀錄貼文而已～