BUG-001: 相对导入超出顶级包范围导致程序启动失败

属性	内容
日期	2026-05-30
状态	✅ 已修复
优先级	P0 - 阻塞（程序无法启动）
影响模块	ui/game_widget.py
报告人	开发团队
修复人	AI Assistant

---

1. Bug 描述

在运行项目主程序 main.py 时遇到 ImportError，具体错误为"attempted relative import beyond top-level package"（尝试的相对导入超出了顶级包范围），导致 PyQt6 GUI 应用无法正常启动。

2. 环境信息

配置项	值
操作系统	Windows
Python 版本	3.12 (py312_project_env)
项目路径	D:\coding\project\Vibe_Coding_project\trae_cn\rules_demo\mentor_game
PyQt6 版本	6.11.0

3. Bug 表现

3.1 复现步骤

# 进入项目目录
cd D:\coding\project\Vibe_Coding_project\trae_cn\rules_demo\mentor_game
​
# 尝试运行主程序
python .\main.py

3.2 错误输出

Traceback (most recent call last):
  File "D:\coding\project\Vibe_Coding_project\trae_cn\rules_demo\mentor_game\main.py", line 20, in <module>
    from ui.main_window import MainWindow
  File "D:\coding\project\Vibe_Coding_project\trae_cn\rules_demo\mentor_game\ui\__init__.py", line 3, in <module>
    from .main_window import MainWindow
  File "D:\coding\project\Vibe_Coding_project\trae_cn\rules_demo\mentor_game\ui\main_window.py", line 10, in <module>
    from .game_widget import GameWidget
  File "D:\coding\project\Vibe_Coding_project\trae_cn\rules_demo\mentor_game\ui\game_widget.py", line 10, in <module>
    from ..src.game_logic import GameLogic, GameState, AttackResult
ImportError: attempted relative import beyond top-level package

4. 根本原因分析

4.1 问题定位

问题出在 ui/game_widget.py 第 10 行：

from ..src.game_logic import GameLogic, GameState, AttackResult

4.2 原因详解

Python 解释器在执行导入时的包层级判定逻辑如下：

项目目录结构：
mentor_game/                    # 项目根目录
├── main.py                     # 入口脚本（直接执行）
├── ui/                         # ← Python 将 ui 视为顶级包
│   ├── __init__.py
│   ├── main_window.py
│   └── game_widget.py          # ← 在这里使用 ..src 会超出 ui 包的范围
└── src/                        # ← 与 ui 平级，但不在同一个包层次中
    ├── __init__.py
    └── game_logic.py

关键机制：

1. 当使用 python main.py 直接运行脚本时，Python 将 ui/ 目录识别为顶级包

2. .. 在 Python 相对导入中表示"上一级包"

3. 由于 ui 已经是顶级包，..src 尝试访问 ui 包的上一级，超出了包的定义范围

4. 这就是为什么报错信息是 "beyond top-level package"

4.3 为什么不报错其他文件

• ui/__init__.py 中的 .main_window 导入是包内相对导入 （. 表示当前包），始终有效

• ui/main_window.py 中的 .game_widget 同样是包内导入，有效

• 只有 ui/game_widget.py 中的 ..src 试图跨越包边界，才会触发错误

5. 解决方案

5.1 采用的方案：将相对导入改为绝对导入

修改文件：ui/game_widget.py

修改前（第 10 行）：

from ..src.game_logic import GameLogic, GameState, AttackResult

修改后：

from src.game_logic import GameLogic, GameState, AttackResult

5.2 方案评估

方案	优点	缺点	是否采用
改为绝对导入	简单直接，不改变项目结构，兼容 python main.py 和 python -m	导入语句基于项目根目录	✅ 采用
添加 sys.path	灵活	代码不整洁，需要在每个入口脚本添加路径操作	❌ 未采用
使用 python -m	规范	需要改变团队运行习惯	❌ 未采用

5.3 修改范围

仅修改 1 个文件，1 行代码，影响范围最小化。

6. 实施过程

1. 使用 SearchReplace 工具定位并修改 ui/game_widget.py 第 10 行

2. 重新运行 python main.py 验证修复

3. GUI 应用正常启动，无错误输出

验证命令

# 修复后重新运行
python .\main.py
​
# 结果：GUI 窗口正常显示，无报错

7. 预防措施

为避免类似问题再次发生，项目遵循以下编码规范：

1. 统一使用绝对导入 ：所有跨模块导入使用基于项目根目录的绝对路径，不使用 .. 跨包引用

2. 项目结构保持一致 ：src/ 和 ui/ 为同级目录，导入路径应基于项目根目录

3. 入口脚本统一 ：所有入口脚本（main.py）放在项目根目录下，确保 Python 能正确识别包层级

---