必须能通过ssh直连服务器且远程已装Python；配置时先建SSH连接，再填真实Python路径和同步目录。
PyCharm 配置 SSH 远程解释器，核心前提是：你必须能通过 ssh 命令从本地机器直连目标服务器，且远程服务器上已装好 Python（或 conda/uv/virtualenv 环境）。Windows 本地机不能作为远程主机，这是硬性限制。
确认远程服务器 SSH 可达且 Python 可用
别跳过这步——很多配置失败其实卡在这儿。打开终端执行：
ssh username@host -p 22
能成功登录后，立刻验证 Python 路径是否正确：
which python3
或如果你用 conda：
conda activate myenv && which python
记下输出的完整路径，比如 /opt/conda/envs/myenv/bin/python。这个路径后面要填进 PyCharm。
- 确保远程用户对 Python 解释器路径有读+执行权限（
ls -l /path/to/python查看） - 如果用 root 登录，建议改用普通用户（如
dev），避免权限污染和后续部署问题 - 防火墙或云厂商安全组必须放行 22 端口；若改过 SSH 端口，PyCharm 里端口字段必须同步
创建 SSH 配置（不是部署配置）
SSH 配置是独立于解释器的底层连接凭证，复用性强。路径：Settings → Tools → SSH Configurations → 点 +。
PyCharm 2026.2是 JetBrains PyCharm 的指定版本安装包，下载地址指向官方 Windows 安装包直链，可用于旧项目兼容、版本回退和环境测试。
-
Host填 IP 或域名（别写localhost，除非你在本机 Docker 里跑服务） -
Port默认 22，非标端口务必改 -
Authentication type优先选Key pair：私钥路径填本地文件（如~/.ssh/id_ed25519），有密码短语就填，勾选Save passphrase - 不要勾选
Only for this project，除非你明确只在当前项目复用该连接 - 点
Test Connection—— 成功才继续，失败就回退查网络/密钥/用户权限
注意：SSH Configuration ≠ SFTP Deployment Configuration。前者管连接，后者管文件上传，别混淆。
添加远程解释器时的关键三步
路径：Settings → Project → Python Interpreter → Add Interpreter → SSH。此时会复用你刚建好的 SSH 配置。
-
Python interpreter path：必须填远程服务器上真实的 Python 可执行文件绝对路径（就是前面
which python的结果），别填 conda root 的python，要填激活环境后的路径 -
Sync folder：左边填本地项目根目录（如
/Users/me/project），右边填远程对应路径（如/home/dev/project）。PyCharm 默认用 SFTP 同步，但不会自动创建远程目录，得你手动mkdir -p好 -
Upload directory：勾选
Automatically upload files时，保存即上传；但首次需手动点Sync and auto-upload触发全量同步
常见坑：Interpreter path 填错导致库列表为空、Sync folder 权限不足报 Permission denied、远程路径没提前建好导致上传失败。
远程调试与第三方库识别异常怎么办
配置完解释器后，PyCharm 会尝试探测远程 site-packages。如果第三方库不显示或调试断点不生效：
- 检查远程 Python 是否能 import 对应模块（
ssh user@host -t 'python3 -c "import requests; print(requests.__version__)"'） - 确认远程解释器路径没被 shell alias 或 wrapper 脚本劫持（比如某些 conda 初始化脚本会干扰）
- 调试时若提示
No module named pydevd，说明 PyCharm 的调试辅助包没自动部署到远程，重启解释器或手动运行pip install pydevd-pycharm（版本需匹配 PyCharm 版本） - 远程环境用了
uv或conda，确保其activate逻辑不依赖交互式 shell（PyCharm 的非交互式 SSH session 可能不 source ~/.bashrc）
最易被忽略的一点：PyCharm 的 SSH 解释器配置本身不包含任何环境变量继承机制。如果你的远程 Python 依赖 LD_LIBRARY_PATH 或自定义 PYTHONPATH，得在远程服务器的 ~/.bashrc 或解释器启动脚本里显式 export，否则本地 IDE 看不见。
