PyCharm 不自动索引远程模块，因索引器仅扫描本地标记为 Sources Root 的路径；必须手动添加远程源码路径（如 sftp://.../myproject）并标记为 Sources Root，否则 import 报红、无法跳转和补全。
PyCharm 无法自动索引远程模块，必须显式配置解释器路径和源码映射，否则补全、跳转、类型提示全部失效。
为什么远程模块不被识别？
PyCharm 的代码索引（code insight）完全依赖本地已知的 Python 路径：它不会主动扫描远程文件系统，也不会从 sys.path 动态推导远程包位置。即使你已成功配置了 SSH Interpreter，PyCharm 默认只把远程解释器的 site-packages 当作“库”，而忽略你自己的项目模块、本地开发中的第三方私有包、或通过 pip install -e . 安装的可编辑包。
- 现象：
import mypackage报红，Ctrl+Click无法跳转，autocomplete不出现自定义类名 - 根本原因：PyCharm 的索引器（indexer）没看到这些模块的源码路径
- 关键误区：以为“用了远程解释器 = 自动同步所有路径”——实际只同步执行环境，不自动同步源码可见性
必须手动添加远程源码路径到 Sources Root
只有被标记为 Sources Root 的目录，PyCharm 才会递归解析其中的 .py 文件并建立符号索引。这一步不能跳过，且必须在远程路径上操作。
- 先确保已配置好
SSH Interpreter（例如/home/user/venv/bin/python） - 打开
File > Settings > Project > Project Structure - 点击
Add Content Root，选择Remote...（不是本地文件夹） - 填入远程绝对路径，例如：
sftp://user@192.168.1.100/home/user/myproject - 选中该路径，点击
Mark as Sources Root（图标变成蓝色文件夹） - 如果项目含多个子模块（如
src/,utils/,tests/），需分别添加并标记
处理 pip install -e . 或本地开发包
远程环境中用 -e 安装的包，其源码不在 site-packages 下，而是在任意路径（比如 /home/user/mylib）。PyCharm 不会自动发现它，必须人工关联。
立即学习“Python免费学习笔记（深入）”；
- 在
Project Structure中再次点击Add Content Root→Remote... - 输入该包的远程根目录，如：
sftp://user@192.168.1.100/home/user/mylib - 务必勾选
Include subdirectories（默认已选） - 不要试图把
/home/user/venv/lib/python3.x/site-packages/mylib.egg-link加进去——那是文本链接，PyCharm 无法解析 - 验证：在 Python Console 中运行
import mylib; mylib.__file__，确认路径与你添加的一致
常见坑点：路径一致性与权限
索引失败往往不是配置逻辑错，而是路径或权限层面的硬性阻断。
-
Root path必须与 SSH Interpreter 配置里的Python interpreter path所在目录可访问——例如解释器在/home/user/venv/bin/python，那么/home/user至少要有rx权限 - 避免使用
~或环境变量（如$HOME）：PyCharm 不展开它们，必须写绝对路径 - 如果远程用的是 Conda 环境，注意
conda activate不改变sys.path的物理路径，仍要按真实安装路径添加 Sources Root - 修改后需等待右下角 “Indexing…” 完成，或手动触发
File > Reload project from disk
最易被忽略的是：Sources Root 添加后，PyCharm 仍会缓存旧索引。遇到“明明加了却还是报红”，先检查远程路径是否拼错、权限是否足够，再强制重建索引——这不是配置遗漏，而是 IDE 对远程路径的感知存在延迟和缓存边界。
