寫(xiě)過(guò)幾年 Python 的人，大概都被這行報(bào)錯(cuò)折磨過(guò)

ImportError: attempted relative import with no known parent package

或者它的兄弟版本

ValueError: attempted relative import beyond top-level package

明明代碼邏輯完全沒(méi)問(wèn)題，卻因?yàn)檫\(yùn)行方式不對(duì)而炸了。這背后其實(shí)是 Python 導(dǎo)入系統(tǒng)一套挺精巧但也挺反直覺(jué)的設(shè)計(jì)，搞懂了原理，這些坑基本就能繞開(kāi)。下面把這套機(jī)制拆開(kāi)揉碎講清楚。

?? 絕對(duì)導(dǎo)入和相對(duì)導(dǎo)入到底是什么

先把兩個(gè)概念擺正。絕對(duì)導(dǎo)入就是寫(xiě)出模塊的完整路徑，從頂層包名開(kāi)始，比如 from mypackage.utils import helper。這種寫(xiě)法清晰明確，不管你從哪個(gè)位置執(zhí)行代碼，只要 mypackage 在搜索路徑里能被找到，導(dǎo)入就能成功。

相對(duì)導(dǎo)入則是用點(diǎn)號(hào)表示相對(duì)位置，一個(gè)點(diǎn)代表當(dāng)前包，兩個(gè)點(diǎn)代表上一級(jí)包，以此類(lèi)推。比如在 mypackage/subpkg/module.py 里寫(xiě) from . import sibling 或 from .. import other，靠的是當(dāng)前模塊在包層級(jí)中的相對(duì)位置去定位目標(biāo)。

這套語(yǔ)法是 Python 2.5 通過(guò) PEP 328 正式引入的，目的是解決一個(gè)歷史問(wèn)題：早期 Python 的隱式相對(duì)導(dǎo)入經(jīng)常會(huì)和標(biāo)準(zhǔn)庫(kù)同名模塊沖突，比如你的包里有個(gè) string.py，結(jié)果導(dǎo)入語(yǔ)句意外抓到了標(biāo)準(zhǔn)庫(kù)的 string 模塊 。PEP 328 之后，相對(duì)導(dǎo)入必須顯式寫(xiě)點(diǎn)號(hào)，隱式相對(duì)導(dǎo)入被逐步淘汰，Python 3 里徹底移除了隱式相對(duì)導(dǎo)入。

兩者的核心差異可以這樣理解，絕對(duì)導(dǎo)入靠的是 搜索路徑（也就是 sys.path）去定位模塊，相對(duì)導(dǎo)入靠的是 包的層級(jí)關(guān)系 去定位模塊。這個(gè)差異就是后面所有坑的根源。

?? 涉及的核心概念

要理解相對(duì)導(dǎo)入為什么會(huì)出問(wèn)題，得先搞清楚幾個(gè) Python 內(nèi)部機(jī)制。

__name__和__package__

每個(gè)模塊被加載時(shí)，解釋器會(huì)給它設(shè)置一個(gè) __name__ 屬性。如果這個(gè)模塊是被導(dǎo)入的，__name__ 就是它的完整點(diǎn)分路徑，比如 mypackage.subpkg.module。但如果這個(gè)模塊是被 直接當(dāng)作腳本運(yùn)行（也就是 python module.py 這種方式），它的 __name__ 會(huì)被強(qiáng)制設(shè)為 "__main__"，完全丟失了包信息。

相對(duì)導(dǎo)入的解析恰恰依賴(lài)這個(gè)包信息。PEP 328 里說(shuō)得很明白，相對(duì)導(dǎo)入用模塊的 __name__ 屬性去判斷它在包層級(jí)中的位置 。如果 __name__ 是 "__main__"，Python 根本不知道你的模塊屬于哪個(gè)包，相對(duì)導(dǎo)入自然就找不到參照點(diǎn)，直接報(bào)錯(cuò)。

__package__ 是配套的另一個(gè)屬性，它顯式記錄了模塊所屬的包名，避免每次都要從 __name__ 里反推。當(dāng)你直接運(yùn)行腳本時(shí)，__package__ 通常是空字符串或者 None，這也是導(dǎo)致相對(duì)導(dǎo)入失敗的直接原因。

sys.path和搜索路徑

絕對(duì)導(dǎo)入依賴(lài) sys.path 這個(gè)列表，Python 會(huì)依次在這些路徑里找模塊。當(dāng)你直接運(yùn)行一個(gè)腳本時(shí)，Python 會(huì)自動(dòng)把這個(gè)腳本所在的目錄插入到 sys.path 的最前面，而不是把項(xiàng)目根目錄加進(jìn)去。這就導(dǎo)致一個(gè)很常見(jiàn)的詭異現(xiàn)象，腳本所在目錄里的同級(jí)模塊能被絕對(duì)導(dǎo)入找到，但上級(jí)目錄或者兄弟目錄的包卻找不到。

運(yùn)行方式的分野，腳本 vs 模塊

這是整個(gè)問(wèn)題里最關(guān)鍵也最容易被忽視的一點(diǎn)。Python 提供兩種執(zhí)行文件的方式：

• 直接執(zhí)行，python path/to/module.py，這時(shí)該文件的 __name__ 被設(shè)為 __main__，且不攜帶任何包上下文；
• 以模塊方式執(zhí)行，python -m package.module，這時(shí) Python 會(huì)先把 package 作為包導(dǎo)入，正確設(shè)置 __package__，再執(zhí)行目標(biāo)模塊，__name__ 依舊是 __main__，但包上下文是完整的。

PEP 366 專(zhuān)門(mén)解決了這個(gè)場(chǎng)景，它規(guī)定用 -m 方式啟動(dòng)時(shí)，解釋器要負(fù)責(zé)正確設(shè)置 __package__，這樣即便主模塊的 __name__ 是 __main__，相對(duì)導(dǎo)入也能正常工作 。也就是說(shuō)，同一份代碼，用兩種方式啟動(dòng)，相對(duì)導(dǎo)入的命運(yùn)完全不同，這是絕大多數(shù)踩坑案例的根源 。

下面用一張圖梳理這套判斷邏輯。

?? 常見(jiàn)踩坑場(chǎng)景與本質(zhì)原因

結(jié)合社區(qū)里反復(fù)出現(xiàn)的報(bào)錯(cuò)案例，把典型的坑歸納一下。

坑一，腳本直接運(yùn)行觸發(fā)相對(duì)導(dǎo)入報(bào)錯(cuò)

假設(shè)項(xiàng)目結(jié)構(gòu)是這樣：

project/
├── mypackage/
│   ├── __init__.py
│   ├── main.py
│   └── utils.py

main.py 里寫(xiě)了 from . import utils，然后你在 project/mypackage/ 目錄下執(zhí)行 python main.py，直接報(bào) ImportError: attempted relative import with no known parent package。原因前面說(shuō)過(guò)，直接運(yùn)行腳本時(shí) __name__ 變成 __main__，Python 完全不認(rèn)為這個(gè)文件屬于 mypackage 這個(gè)包，相對(duì)導(dǎo)入的點(diǎn)號(hào)無(wú)從解析 。

正確的做法是回到 project 目錄，用 python -m mypackage.main 運(yùn)行，這樣解釋器會(huì)把 mypackage 識(shí)別為包，main.py 也就拿到了正確的包上下文。

坑二，相對(duì)導(dǎo)入越過(guò)了頂層包邊界

如果你在某個(gè)模塊里寫(xiě)了太多層的點(diǎn)號(hào)，比如已經(jīng)在包的最頂層還寫(xiě) from .. import something，就會(huì)觸發(fā) ValueError: attempted relative import beyond top-level package。這是因?yàn)橄鄬?duì)導(dǎo)入的點(diǎn)號(hào)數(shù)量不能超過(guò)當(dāng)前模塊實(shí)際所在的包層級(jí)深度，越界了 Python 也沒(méi)法憑空造出一個(gè)更高層的包 。

社區(qū)討論里有個(gè)挺形象的總結(jié)，相對(duì)導(dǎo)入只能在包的層級(jí)樹(shù)上下移動(dòng)，不能跳到相鄰的、平級(jí)但不屬于同一父包的目錄里去 。這也解釋了為什么有些人試圖用相對(duì)導(dǎo)入去引用完全獨(dú)立的另一個(gè)頂層項(xiàng)目，怎么調(diào)都調(diào)不通，因?yàn)檫@本身就不在這套機(jī)制能解決的范圍內(nèi)。

坑三，測(cè)試目錄和主項(xiàng)目目錄之間的導(dǎo)入混亂

這是工程實(shí)踐里最常見(jiàn)的翻車(chē)現(xiàn)場(chǎng)。測(cè)試代碼放在 tests/ 目錄，嘗試相對(duì)導(dǎo)入 src/ 里的模塊，結(jié)果因?yàn)闇y(cè)試框架（比如 pytest）執(zhí)行時(shí)的工作目錄和 sys.path 設(shè)置跟你預(yù)想的不一樣，導(dǎo)致時(shí)好時(shí)壞 。這類(lèi)問(wèn)題往往不是相對(duì)導(dǎo)入語(yǔ)法錯(cuò)了，而是項(xiàng)目缺乏統(tǒng)一的打包結(jié)構(gòu)，導(dǎo)致解釋器判斷包邊界的方式和開(kāi)發(fā)者的預(yù)期出現(xiàn)偏差。

坑四，IDE 能跑但命令行跑不了（或者反過(guò)來(lái)）

這個(gè)現(xiàn)象背后的鍋幾乎都在 sys.path 和工作目錄上。很多 IDE 會(huì)自動(dòng)把項(xiàng)目根目錄加入 sys.path，或者自動(dòng)用類(lèi)似 -m 的方式啟動(dòng)腳本，所以在 IDE 里一切正常，一旦換到命令行直接 python xxx.py，各種導(dǎo)入報(bào)錯(cuò)就冒出來(lái)了。這不是導(dǎo)入語(yǔ)法的問(wèn)題，而是執(zhí)行環(huán)境配置不一致造成的假象。

?? 工程實(shí)踐中該怎么做

社區(qū)里其實(shí)早就吵過(guò)這個(gè)問(wèn)題，Stack Overflow 上那篇討論絕對(duì)導(dǎo)入和顯式相對(duì)導(dǎo)入孰優(yōu)孰劣的老帖子，熱度一直不低 ，Software Engineering 版塊也專(zhuān)門(mén)有帖子討論過(guò)相對(duì)導(dǎo)入到底哪里讓人不放心 。綜合各方經(jīng)驗(yàn)，比較靠譜的實(shí)踐路徑大致如下。

優(yōu)先用絕對(duì)導(dǎo)入，包內(nèi)小范圍用相對(duì)導(dǎo)入

絕大多數(shù)風(fēng)格指南（包括 PEP 8）建議，跨包、跨模塊的導(dǎo)入盡量用絕對(duì)導(dǎo)入，因?yàn)樗男袨椴灰蕾?lài)運(yùn)行方式，可讀性也更好，一眼就能看出模塊來(lái)自哪里。相對(duì)導(dǎo)入更適合用在包內(nèi)部關(guān)系緊密、層級(jí)很淺的兄弟模塊之間，比如同一個(gè)子包里幾個(gè)互相協(xié)作的文件。

把項(xiàng)目當(dāng)成一個(gè)真正的包來(lái)組織，而不是一堆腳本

工程上推薦的目錄結(jié)構(gòu)大概是這樣：

project/
├── pyproject.toml
├── src/
│   └── mypackage/
│       ├── __init__.py
│       ├── main.py
│       └── utils.py
└── tests/
    └── test_utils.py

用 pyproject.toml（或者老一點(diǎn)的 setup.py）把 mypackage 聲明成一個(gè)可安裝的包，開(kāi)發(fā)時(shí)用 pip install -e . 裝成可編輯模式。這樣一來(lái)，無(wú)論從哪個(gè)目錄、用哪種方式運(yùn)行代碼，mypackage 都能被正確找到，因?yàn)樗呀?jīng)注冊(cè)進(jìn)了 Python 的包管理體系，而不再依賴(lài)脆弱的相對(duì)路徑猜測(cè)。

需要執(zhí)行入口腳本時(shí)，永遠(yuǎn)用-m

如果你的包里有個(gè)模塊需要被直接執(zhí)行（比如作為程序入口），運(yùn)行的時(shí)候用 python -m mypackage.main，而不是 python mypackage/main.py。前者會(huì)正確建立包上下文，相對(duì)導(dǎo)入能正常工作；后者則會(huì)把這個(gè)文件降級(jí)成一個(gè)孤立腳本，包信息全部丟失 。

測(cè)試代碼統(tǒng)一交給測(cè)試框架管理路徑

不要手寫(xiě) sys.path.append(...) 這種臨時(shí)補(bǔ)丁去解決測(cè)試導(dǎo)入問(wèn)題，這種做法脆弱又難維護(hù)。更穩(wěn)妥的方式是依賴(lài) pytest 之類(lèi)的框架，配合 conftest.py 和正確的包結(jié)構(gòu)（確保 src 布局加上可編輯安裝），讓測(cè)試運(yùn)行時(shí)的路徑解析交給工具鏈去處理 。

一句話原則

如果非要提煉成一條準(zhǔn)則，大概是這樣，導(dǎo)入方式要和項(xiàng)目結(jié)構(gòu)、運(yùn)行方式保持一致，而不是靠臨時(shí)補(bǔ)丁去湊合。相對(duì)導(dǎo)入本身沒(méi)有錯(cuò)，PEP 328 引入它是為了解決真實(shí)的歷史問(wèn)題 ，但它對(duì)運(yùn)行環(huán)境的假設(shè)比絕對(duì)導(dǎo)入更苛刻，一旦項(xiàng)目結(jié)構(gòu)或者啟動(dòng)方式跟這套假設(shè)不匹配，坑就來(lái)了。

?? 兩種導(dǎo)入方式對(duì)比一覽

這張表基本涵蓋了兩者在實(shí)際工程里最容易出現(xiàn)分歧的地方。真正把項(xiàng)目按標(biāo)準(zhǔn)包結(jié)構(gòu)組織好、入口腳本用 -m 啟動(dòng)，絕對(duì)導(dǎo)入和相對(duì)導(dǎo)入其實(shí)可以相安無(wú)事，各自發(fā)揮所長(zhǎng)。

參考資料

Relative Imports - Python Discussions, discuss.python.org/t/relative-…

What's wrong with relative imports in Python?, Software Engineering Stack Exchange, softwareengineering.stackexchange.com/questions/1…

How to Fix 'ImportError: attempted relative import' in Python, oneuptime.com/blog/post/2…

How to resolve relative import - python, Stack Overflow, stackoverflow.com/questions/7…

PEP 328 – Imports: Multi-Line and Absolute/Relative, peps.python.org/pep-0328/

Absolute vs. explicit relative import of Python module, Stack Overflow, stackoverflow.com/questions/4…

PEP 366 – Main module explicit relative imports, peps.pythondiscord.com/pep-0366/

PEP 328: Absolute and Relative Imports, Python 2.5 What's New, edoras.sdsu.edu/doc/Python-…

到此這篇關(guān)于Python 相對(duì)導(dǎo)入與絕對(duì)導(dǎo)入的坑：從原理到工程實(shí)踐指南的文章就介紹到這了,更多相關(guān)Python 相對(duì)導(dǎo)入與絕對(duì)導(dǎo)入內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論