Python 環境建置與套件管理

不要動系統內建的 Python

多數 Linux 發行版內建的 Python 是系統工具依賴的執行環境。直接用它安裝套件、或升級版本，可能導致系統管理工具失效。

原則：系統的 Python 用來跑系統的東西，你的專案用自己的環境。

虛擬環境是基本做法

虛擬環境讓每個專案有獨立的套件目錄，彼此不干擾。

# 建立
python3 -m venv .venv

# 啟用（Linux / macOS）
source .venv/bin/activate

# 啟用（Windows）
.venv\Scripts\activate

# 離開
deactivate

為什麼一定要用

• 不同專案可能需要不同版本的套件
• 不會污染系統環境
• 可以完整記錄專案的相依套件
• 刪除整個目錄就等於清除環境，不留殘留

建議把 .venv 加入版本控制的忽略清單——它應該由設定檔重建，而不是直接納入版控。

套件管理

記錄相依套件

pip freeze > requirements.txt

在另一台機器重建

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

一個實務建議

pip freeze 會列出所有套件（含相依的相依），版本鎖得很死。

比較好的做法是手動維護一份只列出直接使用的套件，例如：

requests>=2.31
Pillow>=10.0
openpyxl>=3.1

需要完全重現時再另外產生鎖定版本的檔案。

版本的選擇

Python 每個版本大約有五年的支援期。正式使用的腳本建議選擇仍在支援期內的版本，並避免使用剛發布的最新版——部分套件可能還沒跟上。

實務上，選擇比最新版舊一到兩個小版本，通常是穩定與相容性的平衡點。

確認版本

python3 --version
pip --version
pip list

同一台機器有多個版本

可以並存，用明確的版本號呼叫：

python3.11 -m venv .venv311
python3.12 -m venv .venv312

不要修改系統的 python3 指向，那會影響系統工具。

專案的目錄結構

簡單的自動化腳本專案，建議這樣安排：

project/
├── .venv/              # 虛擬環境（不納入版控）
├── scripts/            # 執行的腳本
├── lib/                # 共用的函式
├── config/             # 設定檔（敏感資訊不納入版控）
├── logs/               # 執行紀錄
├── output/             # 產出檔案
├── requirements.txt
└── README.md

README 要寫清楚怎麼建置環境與執行——三個月後的自己會感謝你。

敏感資訊不要寫在程式碼裡

資料庫密碼、API 金鑰、主機帳號不應該直接寫在腳本中。

常見做法

import os

DB_PASSWORD = os.environ.get('DB_PASSWORD')
API_KEY = os.environ.get('API_KEY')

if not DB_PASSWORD:
    raise SystemExit('缺少必要的環境變數 DB_PASSWORD')

或使用獨立的設定檔，並確實加入版本控制的忽略清單。

為什麼重要

• 避免密碼隨程式碼進入版本控制
• 不同環境可用不同設定
• 指令列中的密碼會出現在行程列表，可被同機的其他使用者看到

在伺服器上執行的注意事項

用絕對路徑

排程執行時的工作目錄可能與你預期的不同。腳本中的檔案路徑建議用絕對路徑，或明確設定工作目錄。

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent
LOG_FILE = BASE_DIR / 'logs' / 'run.log'

指定虛擬環境的直譯器

排程中不會自動啟用虛擬環境，要直接指定：

/path/to/project/.venv/bin/python /path/to/project/scripts/backup.py

權限

執行的身分要有讀寫相關目錄的權限。不要為了方便而用最高權限執行——腳本出錯時的破壞範圍會大很多。

常用的標準函式庫

很多需求不需要額外安裝套件：

能用標準函式庫解決的，就不要多裝套件——減少相依就減少維護負擔。

本文的範例以 Python 3 為例，實際的套件版本與 API 可能隨版本更新而異。在正式環境執行任何批次處理前，請先以少量資料測試並確實備份。