Django项目集成Pylint时路径配置异常问题求助

核心问题分析 #

项目启动时，python src/manage.py runserver会自动通过manage.py中的代码将src目录加入Python路径，因此能正常识别apps和config模块；但Pylint从项目根目录运行时，默认不会把src加入路径，导致无法找到对应模块，引发配置错误。

解决方案 #

1. 配置Pylint自动添加src到Python路径

修改项目根目录下的pyproject.toml，添加Pylint初始化钩子和正确的Django设置路径：

[tool.pylint]
load-plugins = "pylint_django"
# 去掉src前缀，因为后续会把src加入路径，直接用config.settings即可
django-settings-module = "config.settings"
# 初始化时将src目录加入Python路径
init-hook = "import sys; sys.path.insert(0, './src')"

2. 验证manage.py的路径配置

确保src/manage.py中已包含将自身所在目录（即src）加入路径的代码，这是Django项目的标准配置：

import os
import sys

if __name__ == "__main__":
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    # 将src目录加入Python路径，确保启动时能找到apps和config模块
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    execute_from_command_line(sys.argv)

3. 统一项目内部导入方式

项目代码中导入模块时，使用基于src根目录的绝对导入（不要加src前缀），比如：

# 正确写法
from config.settings import DEBUG
from apps.identity.models import User

# 错误写法（会导致启动报错）
from src.config.settings import DEBUG
from src.apps.identity.models import User

验证效果 #

完成配置后，直接运行pylint src即可正常检查代码，同时python src/manage.py runserver仍能正常启动项目，路径冲突问题解决。

内容的提问来源于stack exchange，提问作者Yozhik