LDOCE5 Viewer 词典工具实战指南：解决3类核心运行问题

问题1：依赖库加载失败

问题现象：启动时报"ModuleNotFoundError"错误

排查流程：检查Python版本→验证requirements.txt完整性→确认依赖安装状态

解决方案：

🔧 基础环境配置

# 检查Python版本（需3.6+）
python3 --version  # 示例输出：Python 3.9.7

# 安装依赖
pip3 install -r /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/requirements.txt
# 成功提示：Successfully installed PySide6-6.4.2 ...

🔧 虚拟环境隔离方案

# 创建虚拟环境
python3 -m venv /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/venv

# 激活环境（Linux/macOS）
source /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/venv/bin/activate

# 安装依赖
pip install -r requirements.txt

避坑指南： 📌 始终使用pip3明确指定Python3版本 📌 定期执行pip check验证依赖完整性 📌 保持requirements.txt与实际安装版本同步

💡 专家建议：生产环境可使用pip-tools维护依赖版本，避免版本漂移问题

问题2：数据文件加载失败

问题现象：启动后提示"Dictionary data not found"

排查流程：检查数据目录→验证文件完整性→确认配置路径

解决方案：

🔧 标准路径配置

# 创建标准数据目录
mkdir -p /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/ldoce5viewer/data

# 验证目录权限
ls -ld /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/ldoce5viewer/data
# 正确输出：drwxr-xr-x ...

🔧 自定义路径配置

# 编辑配置文件
nano /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/ldoce5viewer/qtgui/config.py

# 添加配置行（文件末尾）
DATA_PATH = "/path/to/your/custom/dictionary/files"

避坑指南： 📌 数据文件需包含".ldoce5"扩展名 📌 确保文件系统支持大文件（单文件>4GB） 📌 移动数据文件后需重新启动应用

💡 专家建议：使用符号链接管理数据文件，便于版本切换和备份

问题3：界面渲染异常

问题现象：窗口错乱或中文显示方块

排查流程：检查Qt版本→验证字体配置→查看错误日志

解决方案：

🔧 组件更新方案

# 升级PySide6组件
pip3 install --upgrade PySide6

# 验证版本
pyside6-rcc --version  # 示例输出：6.4.2

🔧 字体修复方案

# 复制系统字体到应用字体目录
mkdir -p /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/ldoce5viewer/static/fonts
cp /usr/share/fonts/truetype/wqy/wqy-microhei.ttc /data/web/disk1/git_repo/gh_mirrors/ld/ldoce5viewer/ldoce5viewer/static/fonts/

避坑指南： 📌 避免混合安装PyQt5和PySide6 📌 确保系统已安装中文字体包 📌 高DPI屏幕需设置环境变量export QT_SCALE_FACTOR=1.2

💡 专家建议：使用QT_DEBUG_PLUGINS=1环境变量开启调试模式，定位渲染问题根源