PyCharm未将源根添加至sys.path的排查求助

我之前也碰到过几乎一模一样的情况——重装系统后PyCharm的老项目配置全乱了，明明按要求勾了PYTHONPATH选项，源根就是不生效。给你几个亲测有效的排查方向：

• 检查运行配置的工作目录
  重装后很多运行配置的Working directory会被重置成PyCharm的默认路径，而不是你的项目根目录。打开Run > Edit Configurations，找到你用的运行配置，看「Working directory」是不是指向项目的根目录（比如/home/xxx/your-project）。如果不是，改成项目根目录，或者直接用PyCharm的内置变量$PROJECT_DIR$，这样能保证路径始终正确。

• 清除缓存并重启PyCharm
  缓存损坏是这类问题的重灾区，尤其是新安装的PyCharm加载旧项目时容易出问题。点击File > Invalidate Caches...，勾选「Clear file system cache and local history」，然后选择「Invalidate and Restart」。重启后PyCharm会重新扫描项目结构，很多路径识别问题都会自动修复。

• 确认Python解释器配置
  重装系统后，PyCharm可能自动绑定了系统默认的Python，而不是你项目原来用的虚拟环境。先去File > Project Structure > Project，确认「Project SDK」是你项目对应的虚拟环境或者正确的Python版本；再去运行配置里检查「Python interpreter」是不是和项目SDK一致——不同的解释器对应的PYTHONPATH配置是独立的，选错了解释器自然加载不了源根。

• 手动添加源根到环境变量
  如果上面的方法都没效果，可以临时手动指定PYTHONPATH。在运行配置里找到「Environment variables」，点击编辑按钮，添加一个名为PYTHONPATH的变量，值设为你的src目录绝对路径（比如/home/xxx/your-project/src），或者用$PROJECT_DIR$/src这种动态变量。这样运行时PyCharm会强制把源根加到Python的路径里。

• 检查.iml项目配置文件
  如果你用的是IntelliJ格式的项目（有.idea文件夹），可以打开项目根目录下.idea文件夹里的[你的项目名].iml文件，看看里面有没有类似这样的配置：

  <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
  

  如果没有的话手动加上这一行，然后重启PyCharm。有时候重装系统后.iml文件里的源根配置会丢失，导致PyCharm识别不到。

关于你提到的「预期有误」的疑问：你的预期完全是对的——正常情况下勾选「Add content roots to PYTHONPATH」和「Add source roots to PYTHONPATH」后，源根应该自动出现在sys.path里。所以这肯定是PyCharm的配置或缓存异常导致的，不是你理解错了规则。

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