模块导入冲突问题分析与解决

---

背景

在项目中，我们使用了 src/ 作为源码根目录，并通过 PyCharm 进行开发和调试。项目中存在一个本地模块 src/mcp/，与第三方库 mcp 同名。在使用 uv run 启动项目时一切正常，但通过 PyCharm Debug 启动时却报错：

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

进一步排查发现，PyCharm 会自动将项目路径（如 src/）添加到 sys.path 的前面，导致 Python 优先加载本地模块，从而引发循环导入。

---

分析思路

1. 理解 Python 模块查找机制，明确 sys.path 的作用。
2. 定位问题根源：为什么 PyCharm Debug 会加载错误的模块。
3. 解决问题：避免本地模块与第三方库冲突。

---

行动

1. 分析 sys.path 差异

• uv run 的 sys.path：

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

  • 虚拟环境路径靠后，但未额外添加 src/，因此正确加载第三方库。

• PyCharm Debug 的 sys.path：

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

  • src/ 路径被提前添加，导致 Python 优先加载本地模块 src/mcp/。

2. 验证模块加载路径

在代码中添加调试信息：

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

✅ 方法二：调整 PyCharm 配置

1. 打开 Run/Debug Configurations。
2. 取消勾选：
   • Add content roots to PYTHONPATH
   • Add source roots to PYTHONPATH

✅ 方法三：手动调整 sys.path 优先级

在 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)

---

结果

通过以上排查，通过方法二排查解决本地调试问题，过程总结如下：

1. 明确了 Python 模块查找机制：sys.path 路径顺序决定模块加载优先级。
2. 确认了问题根源：PyCharm Debug 配置了「Add source roots to PYTHONPATH」会自动添加 src/ 路径，导致本地模块优先加载。
3. 提供了多种解决方案：
   • 推荐方案：重命名本地模块（如 src/mcp/ → src/mcp_client/）。
   • 临时方案：调整 sys.path 或 PyCharm 配置。

最终，项目在 uv run 和 PyCharm Debug 下均能正常启动，避免了模块冲突和循环导入问题。