本地与服务端 PYTHONPATH 不一致导致自定义模块导入失败

[XieTJ]

Issue 描述正文

问题现象

本地IDE运行项目可正常导入utils、common等内部自定义模块，部署至服务器执行启动脚本时，抛出ModuleNotFoundError，第三方依赖包无异常。

根因分析

1. IDE会自动将项目根目录加入PYTHONPATH，服务器Shell环境无该自动处理；
2. 项目现有启动脚本未统一配置模块检索路径，新人部署极易遗漏路径配置步骤。

复现步骤

1. 本地IDE启动主程序，导入内部模块正常；
2. 服务器直接执行python main.py，未前置设置PYTHONPATH；
3. 运行至自定义模块导入代码行，程序报错终止。

优化建议

1. 在项目启动脚本内置自动追加项目根目录至sys.path的代码，抹平本地与服务端路径差异；
2. 文档补充路径校验命令，方便快速排查：

# 查看当前Python模块检索路径
python -c "import sys; print('\n'.join(sys.path))"

3. 提供标准化启动前置命令模板：

export PYTHONPATH=$(pwd):$PYTHONPATH
python main.py

环境信息

系统：Linux
Python版本：3.9+
项目：OpenHUTB
部署环境：服务器虚拟环境

[tyy433]

问题根源

IDE会自动把项目根目录注入sys.path，但服务器Shell/容器环境无此机制，运行脚本时Python检索路径缺失项目根目录，内部自定义包无法被识别，第三方库不受影响。

3种快速临时解决方案

方案1：启动前临时注入环境变量（Shell部署）

# 进入项目根目录后执行
export PYTHONPATH=$(pwd):$PYTHONPATH
python main.py

方案2：代码内自动补全路径（跨环境通用，推荐）

在项目入口main.py最顶部添加：

import sys
from pathlib import Path
# 将项目根目录加入检索路径
sys.path.append(str(Path(__file__).parent))

方案3：Docker部署适配

在Dockerfile工作目录后添加：

WORKDIR /app
ENV PYTHONPATH=/app

长期优化建议（项目层面修复）

1. 入口文件内置路径兼容代码，彻底抹平本地/服务端路径差异；
2. 提供标准化一键启动脚本，自动配置PYTHONPATH；
3. 文档补充路径排查命令，快速验证当前检索目录：

python -c "import sys; print('\n'.join(sys.path))"

快速排查命令

执行后核对输出列表是否包含项目根路径，无对应路径则确认是路径缺失问题：

python -c "import sys; print(sys.path)"