如何导入FastAPI项目文件夹以同时适配PyCharm和pylint？

你遇到的问题既不是PyCharm的兼容性bug，也不是项目结构有原则性错误，是PyCharm的源根配置错误导致的，和你生产、工具链的路径逻辑不匹配。

你的生产环境WORKDIR设置为/app，Python会自动把工作目录加入sys.path，你拷贝的内层app目录到/app/app，所以app包在sys.path下，from app.utils import xxx的绝对导入完全合法。
pylint和pytest运行时，你是在最外层app目录（存放Dockerfile的那层）执行命令，当前工作目录也会被加入sys.path，能找到内层app包，所以运行正常。
你之前把内层app/app设为源根，相当于把app/app加到sys.path里，此时utils.py是顶级模块，不存在app.utils这个路径，所以PyCharm识别不到导入。

• 打开PyCharm的项目文件树，找到最外层的app目录（存放Dockerfile、requirements.txt的那一层）
• 右键点击该目录 → Mark Directory as → Sources Root
• 找到之前被标记为Sources Root的内层app/app目录，右键点击 → Mark Directory as → Unmark as Sources Root
• 清理索引重启：顶部菜单栏选择 File → Invalidate Caches... → 勾选Clear file system cache and local history → 点击Invalidate and Restart，等待索引重建完成即可

配置完成后PyCharm的路径逻辑会和生产、pylint、pytest完全对齐，绝对导入可以正常识别，不会再报Unresolved reference错误。

如果想从根源避免目录重名带来的配置混淆，可以调整最外层项目目录的名称，避免和内层业务包重名：

my-fastapi-project
 ┣ app
 ┃ ┣ static
 ┃ ┃ ┗ myfrontend.js
 ┃ ┣ templates
 ┃ ┃ ┗ index.html
 ┃ ┣ tests
 ┃ ┃ ┣ __init__.py
 ┃ ┃ ┗ test_server.py
 ┃ ┣ __init__.py
 ┃ ┣ main.py
 ┃ ┗ utils.py
 ┣ Dockerfile
 ┗ requirements.txt

对应修改Dockerfile的COPY指令为COPY ./app /app/app，其余逻辑、导入语句、运行命令都不需要修改，配置IDE时直接把my-fastapi-project设为Sources Root即可，不会再有重名导致的配置错误。

你修改的相对导入逻辑是基于内层app/app为源根的路径，而pylint、pytest、生产环境都是把外层目录作为工作目录，此时内层app是顶级包，相对导入向上跳转超过了顶级包的范围，所以会抛出relative-beyond-top-level错误，生产环境也会出现导入失败问题，因此不要用相对导入适配IDE，统一使用绝对导入、对齐各环境的路径逻辑才是最优方案。

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