Python 課程 – 模組與套件（Modules & Packages）

主題：模組搜尋路徑（`sys.path`）

簡介

在 Python 開發中，模組是程式碼重用的基礎，而套件則是模組的集合。當我們在程式中 import 一個模組時，Python 必須先找到該模組的實體檔案。這個搜尋過程由 sys.path 這個列表負責管理。了解 sys.path 的結構與變化，不僅能避免「找不到模組」的錯誤，還能讓我們靈活地安排專案的目錄結構，提升開發與部署的效率。

本篇文章將從概念說明、實作範例、常見陷阱與最佳實踐，逐層剖析 sys.path 的運作機制，並提供在真實專案中如何善用它的技巧。即使你是剛接觸 Python 的新手，也能在閱讀後快速上手；如果你已有一定開發經驗，則能從更深入的角度重新檢視自己的模組管理方式。

核心概念

1. `sys.path` 是什麼？

sys.path 是一個 Python list，內含一系列字串，每個字串代表一個「搜尋目錄」。
Python 依序檢查這些目錄，尋找符合 import 名稱的 .py、.pyc、或套件目錄（含 __init__.py）。
預設情況下，sys.path 包含以下幾類路徑：
1. 腳本所在目錄（或當前工作目錄）
2. 標準庫目錄（例如 .../lib/python3.x）
3. 第三方套件安裝目錄（site-packages）
4. 環境變數 PYTHONPATH 所指定的路徑

Tip：sys.path 的內容在執行期間可以動態增減，這也是許多開發者在測試或臨時加入自訂模組時的常用技巧。

2. 為什麼要手動調整 `sys.path`？

開發階段：專案結構常常不是一次就能符合 Python 預設的搜尋規則，尤其在多層子目錄或共用程式庫時，需要手動加入路徑。
測試環境：測試套件（如 pytest）常會把測試目錄加入 sys.path，讓測試檔案可以直接 import 專案模組。
部署需求：在容器化或 serverless 環境中，可能需要把自訂路徑寫入 PYTHONPATH，或在程式啟動時動態調整 sys.path。

3. `PYTHONPATH` 與 `sys.path` 的關係

PYTHONPATH 是 環境變數，在 Python 啟動時會被自動加入 sys.path（排在標準庫之前）。
若同一條目同時出現在 PYTHONPATH 與程式碼中手動加入的 sys.path，前者的順序較靠前，會優先被搜尋。

4. `sys.path` 的典型操作

操作	說明	範例
查看	直接印出 `sys.path` 內容	`print(sys.path)`
追加 (append)	把新路徑加到最後，搜尋優先權最低	`sys.path.append('/my/custom/dir')`
插入 (insert)	把新路徑插入指定位置，提升優先權	`sys.path.insert(0, '/my/custom/dir')`
移除 (remove)	從列表中刪除不需要的路徑	`sys.path.remove('/unwanted/dir')`

程式碼範例

以下範例均使用 Python（標記為 python），每段程式碼均加上說明註解，方便讀者快速理解。

範例 1：檢視預設搜尋路徑

import sys

# 印出目前的 sys.path（每一個元素都是一個字串路徑）
for idx, path in enumerate(sys.path):
    print(f"{idx}: {path}")

執行結果會列出從 0 開始的路徑清單，最上方通常是執行腳本所在的目錄。

範例 2：把專案的 `src` 目錄加入搜尋路徑

假設專案結構如下：

my_project/
├─ src/
│   └─ utils.py
└─ main.py

main.py 想直接 import utils，但 src 不在預設搜尋範圍。可以在程式開頭動態加入：

import sys
import os

# 取得當前檔案所在目錄的絕對路徑
BASE_DIR = os.path.abspath(os.path.dirname(__file__))
# 把 src 目錄加入 sys.path，放在最前面以提升優先權
sys.path.insert(0, os.path.join(BASE_DIR, "src"))

# 現在可以直接 import utils
import utils

print(utils.some_helper())

重點：使用 os.path.abspath 取得絕對路徑，避免相對路徑在不同工作目錄下產生錯誤。

範例 3：利用 `PYTHONPATH` 環境變數

在 Unix 系統（Linux / macOS）中，臨時設定 PYTHONPATH：

export PYTHONPATH="/home/user/my_libs:$PYTHONPATH"
python my_script.py

在 Windows 命令提示字元：

set PYTHONPATH=C:\Users\user\my_libs;%PYTHONPATH%
python my_script.py

接著在 my_script.py 中：

import my_custom_module   # 只要 my_custom_module.py 位於 my_libs 目錄即可被找到

技巧：PYTHONPATH 支援多個路徑，使用冒號（Unix）或分號（Windows）分隔。

範例 4：在測試框架中自動加入測試目錄

使用 pytest 時，常見的做法是把 tests 目錄加入 sys.path：

# tests/conftest.py
import sys
import os

# 把專案根目錄加入搜尋路徑，讓測試檔案可以 import src 裡的模組
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
sys.path.insert(0, PROJECT_ROOT)

此時，測試檔案只需要：

# tests/test_utils.py
import utils   # 直接 import，因為 src 已在 sys.path 中

def test_helper():
    assert utils.some_helper() == "expected"

範例 5：動態移除不需要的路徑（避免衝突）

在大型專案中，可能會因為不同套件的相同名稱而產生衝突。可以在程式啟動時先檢查並移除不必要的路徑：

import sys

# 假設某個舊版套件的路徑被誤加入，現在要移除
UNWANTED = "/opt/old_package"
if UNWANTED in sys.path:
    sys.path.remove(UNWANTED)
    print(f"已移除 {UNWANTED}，避免模組衝突")

常見陷阱與最佳實踐

陷阱	說明	最佳實踐
相對路徑錯誤	使用 `sys.path.append('..')` 時，工作目錄不一定是腳本所在目錄，導致找不到模組。	使用 `os.path.abspath(os.path.dirname(__file__))` 取得腳本所在的絕對路徑，再拼接相對路徑。
路徑順序不當	把自訂路徑加入 `sys.path` 的位置太靠後，會被標準庫或已安裝套件「先搶」走。	通常使用 `sys.path.insert(0, ...)` 把自訂路徑放在最前面，確保優先權。
重複加入	多次 `append` 同一條路徑，會造成 `sys.path` 變長且不易除錯。	在加入前先檢查 `if new_path not in sys.path:`
跨平台分隔符	Windows 使用 `;`，Unix 使用 `:` 作為 `PYTHONPATH` 分隔符，寫死會在另一平台失效。	使用 `os.pathsep`（平台自動判斷）來組合多個路徑。
忘記清理測試路徑	測試框架加入的路徑若未在正式執行環境中移除，可能導致意外載入測試版本的模組。	在測試完成後或正式啟動腳本中，使用 `sys.path.remove(...)` 清除不必要的路徑。

其他建議

盡量使用套件（Package）結構：將專案模組放入具 __init__.py 的資料夾，配合相對匯入 (from . import module) 可以減少對 sys.path 的依賴。
使用虛擬環境：在 venv 或 conda 中安裝套件，site-packages 會自動加入 sys.path，避免全域污染。
記錄路徑變動：在程式啟動時印出 sys.path（或寫入日誌），有助於追蹤因環境變數或程式碼改動導致的搜尋問題。

實際應用場景

資料科學專案：常見的資料夾結構 src/, notebooks/, data/ 中，Jupyter Notebook 需要匯入 src 內的工具函式。只要在 Notebook 開頭加入 sys.path.insert(0, '../src')，即可順利使用自訂模組。
微服務與容器化：Dockerfile 中可以透過 ENV PYTHONPATH=/app/lib 設定環境變數，讓容器內的所有服務都能共用同一套工具函式庫，而不必在每個程式碼檔案裡手動調整 sys.path。
插件系統：開發可擴充的應用程式時，常把外掛放在 plugins/ 目錄。程式啟動時遍歷該目錄，將每個子目錄加入 sys.path，再使用 importlib 動態載入插件模組。
CI/CD 自動化測試：在 GitHub Actions、GitLab CI 等流水線中，經常需要先把測試資料夾加入 sys.path，才能讓測試腳本正確 import 內部模組。

總結

sys.path 是 Python 模組搜尋的核心清單，了解它的組成與優先順序是避免 ImportError 的第一步。
透過 絕對路徑、sys.path.insert(0, ...) 與 PYTHONPATH，我們可以彈性地把自訂目錄加入搜尋範圍，滿足開發、測試、部署的各種需求。
常見的陷阱包括相對路徑錯誤、路徑順序不當與重複加入，採取 檢查重複、使用平台無關的分隔符、清理不必要路徑 等最佳實踐，可讓程式碼更穩定、易於維護。
在實務上，無論是資料科學、微服務、插件系統或 CI/CD，正確管理 sys.path 都是確保程式模組化、可重用與可部署的關鍵。

掌握了 sys.path 的運作原理與操作技巧，你就能在任何 Python 專案中自如地安排模組結構，讓程式碼保持乾淨、可讀且易於擴充。祝你在 Python 的模組世界裡玩得開心！

Python 課程 – 模組與套件（Modules & Packages）

主題：模組搜尋路徑（sys.path）

簡介