Python 模塊導入機制詳解：同級目錄、子包、父目錄與 sys.path 動態調整

場景一：同級目錄導入

# 目錄結構
src/
  mod1.py
  test1.py

# test1.py 中
import mod1
# 或
from mod1 import *

場景二：導入子目錄模塊

# 目錄結構
src/
  mod1.py
  lib/
    __init__.py   # 必須存在（可為空），標識為包
    mod2.py
  test1.py

# test1.py 中
from lib.mod2 import *
# 或
import lib.mod2

場景三：導入父目錄或兄弟目錄模塊

# 目錄結構
src/
  mod1.py
  lib/
    __init__.py
    mod2.py
  sub/
    test2.py

# test2.py 中
import sys
sys.path.append("..")  # 將父目錄加入模塊搜索路徑
import mod1
import lib.mod2

最佳實踐建議

• 項目根目錄加入 PYTHONPATH：開發環境配置 PYTHONPATH 或 IDE 設置 Sources Root，避免代碼中硬編碼 sys.path。
• 使用相對導入：包內部模塊間優先用 from . import mod、from ..lib import mod2（需在包結構下運行）。
• 設置 __init__.py 導出公共 API：__all__ = ['mod2', 'func'] 控制 from lib import * 行為。
• 虛擬環境隔離依賴：使用 venv + pip install -e . 以可編輯模式安裝本地包。

常見錯誤與排查