背景

在項目中，我們使用了 src/ 作為源碼根目錄，并通過 PyCharm 進行開發(fā)和調(diào)試。項目中存在一個本地模塊 src/mcp/，與第三方庫 mcp 同名。在使用 uv run 啟動項目時一切正常，但通過 PyCharm Debug 啟動時卻報錯：

ImportError: cannot import name 'ClientSession' from partially initialized module 'mcp'

進一步排查發(fā)現(xiàn)，PyCharm 會自動將項目路徑（如 src/）添加到 sys.path 的前面，導致 Python 優(yōu)先加載本地模塊，從而引發(fā)循環(huán)導入。

分析思路

• 理解 Python 模塊查找機制，明確 sys.path 的作用。
• 定位問題根源：為什么 PyCharm Debug 會加載錯誤的模塊。
• 解決問題：避免本地模塊與第三方庫沖突。

行動

1. 分析 sys.path 差異

• uv run 的 sys.path：

  ['/Users/.../project, ..., '/Users/.../.venv/lib/python3.12/site-packages']
  

  • 虛擬環(huán)境路徑靠后，但未額外添加 src/，因此正確加載第三方庫。

• PyCharm Debug 的 sys.path：

  ['/Users/.../project', ..., '/Users/.../project/src', ...]
  

  • src/ 路徑被提前添加，導致 Python 優(yōu)先加載本地模塊 src/mcp/。

2. 驗證模塊加載路徑

在代碼中添加調(diào)試信息：

import mcp
print("mcp module path:", mcp.__file__)

• 如果輸出為：

  mcp module path: /Users/...project/src/mcp/__init__.py  # ? 錯誤
  

  說明加載了本地模塊。

• 如果輸出為：

  mcp module path: /Users/.../.venv/lib/python3.12/site-packages/mcp/__init__.py  # ? 正確
  

  說明加載了第三方庫。

3. 解決方案

? 方法一：重命名本地模塊

將 src/mcp/ 改名為 src/mcp_client/：

mv src/mcp src/mcp_client

更新所有引用：

# 原來：
from src.mcp import AuthenticatedMCPClient

# 修改為：
from src.mcp_client import AuthenticatedMCPClient

? 方法二：調(diào)整 PyCharm 配置

• 打開 Run/Debug Configurations。
• 取消勾選：
  • Add content roots to PYTHONPATH
  • Add source roots to PYTHONPATH

? 方法三：手動調(diào)整 sys.path 優(yōu)先級

在 server.py 開頭添加：

import sys

site_packages = "/Users/sunfei13/gitRepo/srpa-deerflow/srpsa-deerflow/.venv/lib/python3.12/site-packages"
if site_packages in sys.path:
    sys.path.remove(site_packages)
    sys.path.insert(0, site_packages)

結(jié)果

通過以上排查，通過方法二排查解決本地調(diào)試問題，過程總結(jié)如下：

• 明確了 Python 模塊查找機制：sys.path 路徑順序決定模塊加載優(yōu)先級。
• 確認了問題根源：PyCharm Debug 配置了「Add source roots to PYTHONPATH」會自動添加 src/ 路徑，導致本地模塊優(yōu)先加載。
• 提供了多種解決方案：
  • 推薦方案：重命名本地模塊（如 src/mcp/ → src/mcp_client/）。
  • 臨時方案：調(diào)整 sys.path 或 PyCharm 配置。

最終，項目在 uv run 和 PyCharm Debug 下均能正常啟動，避免了模塊沖突和循環(huán)導入問題。

到此這篇關(guān)于python模塊導入沖突問題解決的文章就介紹到這了,更多相關(guān)python模塊導入沖突內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論