PyCharm选中正确解释器仍提示Django项目unresolved references如何解决

学习Django第5天，已通过PyCharm在虚拟环境中搭建了可正常运行的Django项目，当前遇到如下问题：

• 部分导入语句在Django运行环境下可无报错正常执行
• 已为项目选中正确的解释器，该解释器所属虚拟环境确实已安装Django
• PyCharm始终无法识别对应引用，无法将导入语句与项目内的.py文件建立关联
• 问题截图如下：
  

按顺序操作即可，绝大多数同类问题都能在前两步解决：

标记项目源码根目录 #

Django的模块查找逻辑和原生Python有区别，PyCharm默认不会自动适配，需要手动指定源码查找起点：

• 在项目文件树中找到存放manage.py的目录，右键点击
• 依次选择Mark Directory as > Sources Root
• 标记完成后该文件夹会显示为蓝色，PyCharm会将该路径作为模块查找的根路径重新索引。

开启PyCharm原生Django支持 #

• 打开设置面板：Windows/Linux系统走File > Settings，Mac系统走PyCharm > Preferences
• 依次进入Languages & Frameworks > Django配置页
• 勾选Enable Django support选项
• 按项目实际路径填写三个配置项：
  • Django project root：选择存放settings.py的目录
  • Settings：选择项目的配置文件，默认路径为项目名/settings.py
  • Manage script：选择项目根目录下的manage.py文件
• 点击OK保存，等待索引更新完成即可。

清除缓存重建索引 #

如果前两步操作后仍有识别问题，是PyCharm本地历史缓存损坏导致：

• 点击顶部菜单File > Invalidate Caches...
• 在弹窗中勾选Clear file system cache and Local History
• 点击Invalidate and Restart，重启后PyCharm会重新扫描所有项目文件和解释器依赖，修复索引错误。

核对解释器配置 #

最后排查容易踩的路径选错问题：

• 进入设置面板的Project: 你的项目名 > Python Interpreter页
• 确认选中的解释器为当前项目虚拟环境目录下的Python可执行文件，不是全局Python环境、也不是其他项目的虚拟环境
• 点击解释器列表旁的刷新按钮，同步已安装包列表，确认列表中存在对应版本的Django即可。

本质原因：Django运行时会自动把项目根目录等路径加入模块搜索路径，所以代码实际跑起来不会报导入错误；但PyCharm默认不会主动读取Django的路径配置，必须手动标记源码根、开启Django框架支持，它才能按照和Django一致的规则查找模块，消除未解析引用的提示。

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