Python 程式設計的世界

使用相對路徑匯入 Python 模組完整指南｜也說明錯誤的解決方法

外部函式庫、API與通訊
目次

1. Python 中的 import 語法與相對路徑匯入的概要

在使用 Python 撰寫程式時，為了有效地重複使用模組，會使用 import 語法。當中，相對路徑匯入在模組之間有彈性依賴關係時特別實用。本文將說明在 Python 中如何使用相對路徑進行匯入，以及這樣做的優點。

什麼是相對路徑匯入？

相對路徑匯入是以當前模組的位置為基準，匯入其他模組的方法。這在大型專案或包含多個模組的套件開發中特別有用。使用相對路徑匯入可以明確管理模組之間的依賴關係，讓專案的維護變得更容易。 舉例來說，假設我們有如下的目錄結構：
project/
    ├── main.py
    ├── package/
    │   ├── module_a.py
    │   └── sub_package/
    │       └── module_b.py
如果要從 module_b.py 使用相對路徑匯入 module_a.py，可以這樣寫：
from ..module_a import some_function
像這樣使用相對路徑，就能依照目錄層級的結構，靈活地匯入模組。
Ad

2. 相對路徑與絕對路徑的差異

在 Python 中的 import 語法有兩種方式：相對路徑與絕對路徑。這兩者的主要差別在於如何指定要匯入的模組。

絕對路徑匯入

絕對路徑匯入是從專案的根目錄開始，明確指定要匯入的模組。例如，在以下專案結構中，如果要從 main.py 匯入 module_a.py，可以這樣寫：
from package.module_a import some_function
這種方式在專案結構穩定且模組位置固定的情況下非常方便。

相對路徑匯入

另一方面，相對路徑匯入是根據當前模組的位置來尋找其他模組。當專案結構可能變動時，相對路徑匯入相對靈活，可以保持模組間的關聯性並提升程式碼的重用性。 例如，以下是從目前模組向上一層目錄匯入模組的寫法：
from ..module_a import some_function
至於選擇哪一種方式，需視專案的規模與複雜度而定。一般來說，如果模組位置固定就使用絕對路徑；如果經常變動，則推薦使用相對路徑。
Ad

3. 使用相對路徑進行匯入的方法

匯入同一個目錄中的模組

當要匯入與目前模組位於同一個目錄的其他模組時，不需要特別的路徑指定，只需直接寫模組名稱即可。例如，module_a.py 和 module_b.py 位於同一個資料夾時，可以這樣匯入：
import module_a
如果只想匯入特定的函式或類別，可以這樣寫：
from module_a import some_function

從上層目錄匯入模組

若要從上層目錄匯入模組，可以使用 .. 回到上一層，接著指定模組名稱。例如，從上一層匯入模組時可寫成：
from ..module_a import some_function

從下層目錄匯入模組

若要從子目錄（下層資料夾）匯入模組，請使用點號（.）來區隔目錄與模組名稱。例如，以下是從子目錄中匯入模組的方法：
from sub_package.module_b import some_function
使用相對路徑的好處是，即使專案中的資料夾結構變動，程式碼也能靈活應對，大大提高維護性。
Ad

4. 匯入套件中的模組

在 Python 中，有「套件（Package）」這個概念，用來整理模組。當開發大型專案時，將模組組成套件會更加有組織，也更方便管理。你也可以在套件中使用相對路徑匯入模組。

套件的結構與 __init__.py 檔案

建立套件時，必須在該資料夾中加入一個名為 __init__.py 的檔案。這個檔案的作用是讓 Python 能夠辨認該目錄為一個「套件」。我們以以下的專案結構為例來說明：
project/
    ├── main.py
    ├── package/
    │   ├── __init__.py
    │   ├── module_a.py
    │   └── sub_package/
    │       ├── __init__.py
    │       └── module_b.py

在套件中使用相對路徑匯入模組

例如，從 module_b.py 使用相對路徑匯入 module_a.py，可以這樣寫：
from ..module_a import some_function
這裡的 .. 表示回到上一層目錄。透過這種方式，可以在套件內部共享函式或類別。 如果是同一個套件內的模組，也可以用單一個點 . 來進行相對匯入：
from .module_a import some_function
這讓模組之間的關聯更簡潔，即使資料夾的結構發生變化，也不需要大幅修改原本的程式碼。
Ad
侍エンジニア塾

5. 常見錯誤與解決方法

在使用 Python 的相對路徑匯入時，經常會遇到一些典型的錯誤。本節將介紹這些錯誤的原因以及對應的解決方法。

ImportError: attempted relative import with no known parent package

這是使用相對路徑匯入模組時最常見的錯誤之一，特別是當直接執行腳本時。舉例來說，以下的程式碼可能會導致這個錯誤：
from ..module_a import some_function
這個錯誤的原因是 Python 無法識別該腳本所屬的父套件。換句話說，Python 必須能夠明確知道該模組是某個套件的一部分。當你直接執行模組時，這種辨識就可能失敗，進而導致錯誤發生。

解決方法

其中一種解決方式是使用 sys.path 明確設定模組的搜尋路徑。以下是將上層目錄加入 sys.path 的範例：
import sys
sys.path.append('..')
from module_a import some_function
這樣可以讓 Python 成功找到指定的模組。

ModuleNotFoundError

另一個常見錯誤是 ModuleNotFoundError，即找不到指定的模組。這通常是因為指定的路徑錯誤，或者 sys.path 沒有正確設置。

解決方法

為了解決這個問題，請先確認你的匯入語法是否正確，並確保該模組確實存在於你指定的路徑中。另外，也可以使用 sys.path.append() 手動加入正確的目錄，協助 Python 找到該模組。
Ad

6. 實戰範例與應用

在本節中，我們將透過實際的程式碼範例，說明如何在實務專案中應用相對路徑匯入。

範例：從上層目錄匯入模組

假設你的專案目錄結構如下：
project/
    ├── main.py
    ├── package/
    │   ├── module_a.py
    │   └── sub_package/
    │       └── module_b.py
如果要從 module_b.py 匯入 module_a.py 的函式 some_function，可以這樣寫：
# module_b.py
from ..module_a import some_function

def use_function():
    some_function()
這段程式碼中，.. 表示回到上層目錄，從而能夠正確匯入 module_a。這種方法在跨資料夾使用模組時特別有用。

範例：使用 sys.path 匯入模組

以下是另一種做法，使用 sys.path.append() 加入搜尋路徑來匯入模組：
# module_b.py
import sys
sys.path.append('..')
from module_a import some_function

def use_function():
    some_function()
這種方法特別適合當你要直接執行腳本時，能確保 Python 找到正確的模組。
Ad

7. 結論

在本文中，我們詳細介紹了 Python 中使用 import 搭配相對路徑匯入模組的方法。透過相對路徑匯入，可以讓專案內的模組之間保持彈性的依賴關係，這在開發大型專案或套件時特別有幫助。不過也需要注意一些常見的錯誤，並善用 sys.path 等工具來解決。 只要理解相對路徑匯入的特性，並靈活運用，你將能有效提升程式碼的可維護性與重用性，讓開發流程更順利。
Ad