1. 为什么要用PyCharm连远程SSH先想清楚你的场景先说一个我自己的例子。之前有个数据处理项目本地跑的时候一切正常但数据规模从几十万行涨到几百万行之后笔记本的风扇就开始起飞一次训练动辄三四个小时期间电脑基本干不了别的活。后来把任务丢到公司的Linux服务器上跑半个小时就搞定。但问题来了——代码还得在本地写每次改完要手动传到服务器、再跑一遍测试来回折腾非常痛苦。这就是PyCharm连接远程SSH的典型场景代码在本地编辑运行和调试在远程服务器上完成。它解决的核心痛点不是能不能连上这个表面问题而是如何在保持本地开发体验的前提下利用远程的计算资源和环境。具体来说你通过PyCharm的远程开发能力做三件事远程解释器让PyCharm直接把服务器上的Python解释器当作项目的解释器来用运行、调试、终端执行都在服务器上本地的PyCharm只负责编辑代码和展示结果。远程部署通过SFTP把本地文件同步到远程服务器你设置好映射后每次保存文件可以自动上传。远程终端在PyCharm里直接打开一个SSH终端不用再切到iTerm、Termius或者其他SSH工具。这套方案适合的人群很明显项目代码量大、计算任务较重需要用到服务器GPU或高配CPU的开发者项目必须跑在Linux环境里但日常开发离不开本地Windows或Mac的开发者以及和我一样需要在多个设备之间切换但希望代码和运行环境统一在服务器上的团队协作场景。但我也得泼一盆冷水。不是所有项目都适合用PyCharm远程SSH。如果你的项目只是简单的脚本或者服务器和本地的网络延迟很高比如跨地域访问那远程编辑的体验会很差——每次输入代码都有肉眼可见的延迟补全弹窗像PPT一样卡。还有一种情况是项目依赖本地硬件比如摄像头、USB设备、本地数据库服务这时候远程开发的意义就不大了。另外要说明的是PyCharm的远程SSH功能分两层Professional版专业版支持完整的远程解释器和远程开发Community版社区版只能用于纯SSH终端连接但不支持远程解释器。如果你在社区版上找不到Deployment或Remote Interpreter的配置项不是设置错地方了而是版本不支持。预算不足的情况下可以考虑正版授权或者先评估项目对远程开发的依赖程度再决定是否升级。2. 开始之前的花十分钟环境与账号准备清单很多人配置失败问题往往不在PyCharm本身而是前置条件没满足。远程SSH的链路是本地PyCharm → 网络 → 服务器SSH服务 → 服务器上的Python环境这条链路上任何一环有问题后面的配置都是白搭。2.1 本地机器的三项准备PyCharm版本确认。这是最容易被忽略的一点。打开PyCharm的Help → About确认你用的是Professional版还是Community版。如果是2023.1以后的版本PyCharm还推出了独立的JetBrains Gateway工具做远程开发但核心使用体验和我在下面讲的配置流程是一致的逻辑上没有变化。SSH客户端。Windows 10以上系统自带OpenSSH客户端一般不用额外安装。Mac和Linux原生就带SSH命令。验证方法是打开终端输入ssh -V能看到版本号就说明没问题。项目代码。确认你本地有一份完整的项目副本或者准备新建一个空项目用于连接。推荐的做法是先从Git仓库clone一份到本地之后远程初始同步会节省很多时间。2.2 服务器端的三件事SSH服务必须处于运行状态。Ubuntu系统上常见的问题是只装了openssh-client没装openssh-server用ps aux | grep sshd检查一下有没有ssh进程没有的话执行sudo apt install openssh-server安装然后sudo systemctl status ssh确认服务状态是running。确认登录方式。你要明确自己是用密码登录还是密钥登录。如果是阿里云、腾讯云这类云服务器首次创建实例时设置的密码就是SSH登录密码如果忘了可以直接在控制台重置。公司内网服务器的话找管理员开通账号即可。密钥登录的配置我放到后面专门讲。Python环境要准备好。远程解释器本质上是调用服务器上的Python所以服务器上必须提前装好Python。推荐在服务器上用sudo apt install python3 python3-venv python3-pip装基础环境或者用Anaconda/Miniforge管理环境。我个人的习惯是每个项目在服务器上单独建一个虚拟环境或conda环境避免全局环境被不同项目依赖搅乱。2.3 网络与端口连通性检查这一步是很多人卡住的重灾区。SSH默认端口是22但很多云服务器出于安全考虑会改成其他端口比如2222、22022。如果你不清楚端口号先登录服务器管理后台看安全组规则或者直接问管理员。检查连通性用一行命令就够了# 在本机终端执行把user和ip换成你的实际账号和服务器地址 ssh -p 22 useryour-server-ip如果这一步都不通PyCharm里配置再多也是白搭。常见的表现是卡住半天最后报Connection timed out。这时候优先排查三件事服务器防火墙是否放行了该端口、云安全组是否放行了该端口、服务器IP是否从本机ping得通。3. 完整配置流程从SSH连接到远程解释器的四个层次很多人理解PyCharm连远程SSH以为只是配置一个地方就行实际上它分四个层次每一步都是在为下一步打基础。3.1 第一步SSH连接配置打开PyCharm依次进入File → Settings → Tools → SSH Configurations在macOS上是PyCharm → Preferences。点击左上角的号新建一个连接填写Host服务器IP或域名PortSSH端口默认22按实际修改Username服务器登录用户名填完先别急着写密码点击页面下方的Test Connection按钮。如果网络通、端口对、账号没问题会弹出一个连接成功的提示。这时候再选择认证方式——密码认证直接填密码密钥认证则选择私钥文件路径。我个人强烈建议即使你用密码连接也在这一步测试成功之后回头把密钥认证配好。原因很简单密码认证每次连接都要交互输入PyCharm虽然可以记住密码但在命令行Git操作、后续的SFTP同步时还是会遇到各种需要二次认证的场景密钥认证一劳永逸。具体的密钥配置方法见下一节。3.2 第二步部署配置远程与本地文件的桥梁配置SSH连接只是打通了通道要让PyCharm把本地代码同步到服务器还得配置Deployment。路径是File → Settings → Build, Execution, Deployment → Deployment。新建一个部署配置类型选择SFTP然后在SSH Configuration下拉框里选择刚才创建好的SSH连接。这里有两个关键参数需要理解Root PathSFTP连接后默认进入的服务器根目录一般填服务器上你用户名的主目录路径例如/home/yourname。Mappings本地项目和服务器目录的映射关系。比如本地项目在D:\projects\mysite你希望它对应服务器的/home/yourname/projects/mysite那就在Deployment Path里填/home/yourname/projects/mysite而且这个目录最好在服务器上先手动建好否则自动创建时可能因为权限不足报错。配置完之后在项目文件上右键菜单里会出现Deployment → Upload to和Download from这就是手动同步的入口。这时候不用急着设置自动上传先把手动同步跑通确认文件能正常传到服务器再开自动上传。3.3 第三步配置远程解释器核心中的核心部署配置解决的是文件怎么过去远程解释器解决的是代码跑到哪里去。路径是File → Settings → Project → Python Interpreter点击齿轮图标选择Add Interpreter → On SSH。PyCharm会要求你指定刚才创建的SSH连接然后选择解释器类型。这里会出现几个选项我解释一下区别Virtual Environment在服务器上基于某个Python版本创建新的虚拟环境适合新项目。Conda Environment使用服务器上conda管理的环境适合Anaconda用户。System Interpreter直接使用服务器上系统默认的Python简单直接但不推荐因为系统Python通常会被系统工具依赖装包容易污染。选好之后PyCharm会扫描服务器上的Python路径。如果你服务器上装了多个Python版本建议用which python3确认具体路径因为有时代码用的库只在python3.10里有PyCharm默认找到的却是python3.8。配置完成后PyCharm会自动把本地代码上传到远程目录如果目录还没内容并在服务器上初始化解释器信息。这个过程第一次会有点慢因为要同步一些辅助文件耐心等它转完即可。3.4 第四步验证整个链路运行配置的核心验证方式很简单在PyCharm里打开一个Python文件右键选择Run。注意观察Run工具栏里的解释器名称如果显示的是Remote Python 3.x字样说明代码真的是在服务器上跑的。再验证一下终端。打开PyCharm底部的Terminal窗口PyCharm会直接帮你SSH到服务器上显示的是远程shell提示符在终端里执行pwd确认当前目录再执行python --version确认Python版本。到这里最基础的PyCharm 远程SSH已经打通了。我每次配完都会做一个小测试在本地代码里加一行import platform; print(platform.node())运行后看输出的主机名是不是服务器的主机名一目了然。4. 免密登录配置别再每次输密码了开头提到的热搜词里有otty如何设置能每次ssh连接服务器时不用输密码除了otty那边PyCharm自己也支持免密登录。这一步做完后面的Git操作、SFTP同步、远程终端都会顺滑很多。4.1 生成密钥对在本地执行ssh-keygen -t ed25519 -C your_emailexample.com我的习惯是用ed25519算法比RSA更安全且生成速度快。一路回车会生成在~/.ssh/id_ed25519私钥和~/.ssh/id_ed25519.pub公钥。你也可以用-t rsa -b 4096兼容性更好主要看服务器端是否支持ed25519——现在的主流Linux发行版都支持不用太纠结。4.2 公钥拷贝到服务器最方便的方式是用ssh-copy-idssh-copy-id -i ~/.ssh/id_ed25519.pub useryour-server-ip它会要求你输入一次密码然后自动把公钥追加到服务器的~/.ssh/authorized_keys文件里并把权限设置成正确值。之后你再ssh useryour-server-ip就不需要密码了。如果没有ssh-copy-id命令Windows上这种情况很常见手动操作也可以原理一样# 先打印公钥内容 cat ~/.ssh/id_ed25519.pub # 然后SSH登录服务器把公钥粘贴到authorized_keys文件 mkdir -p ~/.ssh chmod 700 ~/.ssh echo 粘贴的公钥内容 ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys两个chmod非常关键authorized_keys文件权限必须是600.ssh目录必须是700否则服务器会出于安全考虑拒绝使用密钥认证。4.3 私钥的权限问题在Windows上容易踩的坑是私钥文件权限过大。OpenSSH对于权限过宽的私钥文件会直接拒绝加载报错信息类似UNPROTECTED PRIVATE KEY FILE。解决办法是右键私钥文件 → 属性 → 安全 → 高级 → 禁用继承 → 删除所有用户只保留当前用户并把权限设为完全控制。在Linux/Mac上执行chmod 600 ~/.ssh/id_ed25519即可。4.4 Git仓库的SSH密钥配置配置好服务器登录之后还有一个高频场景服务器上从GitLab/GitHub拉取代码。这和你本地连服务器是两码事——服务器上的Git要访问GitLab需要为服务器单独生成一份密钥并把公钥配置到GitLab的SSH Keys页面。流程是SSH登录服务器 → 在服务器上执行ssh-keygen -t ed25519生成一对密钥 →cat ~/.ssh/id_ed25519.pub查看公钥 → 登录GitLab在Preferences → SSH Keys里粘贴。这样服务器从GitLab拉取代码时才不会每次都让输入密码。如果你用的是GitLab热词里gitlab配置ssh密钥指的就是这个操作。5. 踩坑排查我从配置失败到成功运行的经历复盘这部分内容说多了都是泪。我在不同时期、不同服务器上配过很多次远程SSH几乎把所有能踩的坑都踩了一遍。下面按排查顺序讲你可以对照自己的报错信息来定位问题。5.1 Connection timed out网络层的典型问题表现为PyCharm卡在连接界面最后报超时。这个问题的排查链路非常明确先用命令行的ping确认服务器IP可达——如果ping不通问题在防火墙或者IP本身。再用telnet your-server-ip 22或nc -vz your-server-ip 22确认端口通不通——如果不通检查云安全组和服务器内网防火墙。确认服务器SSH服务端口是否是22修改过端口的必须在PyCharm中同步修改。我有一次遇到服务器内网可以连接外网不行的情况最后发现是云服务商的安全组规则只对内部IP段开放了22端口。这类问题排查顺序就是从自己这台机器出发逐层往外检查不要一上来就去动服务器配置。5.2 Permission denied, please try again认证信息不对如果密码确认无误但还是报这个错有一种隐蔽原因是服务器禁用了密码登录。检查服务器的/etc/ssh/sshd_config文件找到PasswordAuthentication这一项如果是no说明服务器只允许密钥登录。有两种选择让管理员开启密码认证或者按照上一节的方法配置密钥认证。还有种情况是用户名写错。服务器上的账号可能不是你心里想的那个尤其在使用云服务器时不同系统镜像默认用户不一样——Ubuntu通常是ubuntuCentOS通常是root或者centos。不确定的话用whoami命令验证一下当前登录用户。5.3 解释器在服务器上找不到包远程解释器配置成功之后运行代码时提示ModuleNotFoundError但你明明在服务器上装过这个包。这个问题八成是解释器路径选错了。比如你在服务器上有个conda环境叫env1但PyCharm配置解释器时选择的可能是系统默认的/usr/bin/python3而不是conda环境所在的/opt/anaconda3/envs/env1/bin/python。解决办法是手动指定在配置远程解释器时选择Conda Environment并浏览到正确的Python可执行文件路径。另外也提醒一下在PyCharm的远程解释器下用pip install装包实际上是在服务器上执行的。如果PyCharm提示权限不足无法安装就在服务器终端手动pip install --user或者进入虚拟环境安装不要只盯着PyCharm的报错看。5.4 文件上传了但运行报错提示找不到文件这个坑很隐蔽。有一次我配置完Deployment文件也上传成功了但在服务器上查看目录结构时发现代码在/home/user/projects/abc而PyCharm里运行的路径却是/home/user/abc。原因在于Mappings里的Deployment Path配置错了。PyCharm的Deployment是相对Root Path来定位的如果你在Mappings里只填了abc实际同步路径是Root Path abc如果填了/projects/abc实际路径就变成了Root Path /projects/abc。建议在配置好之后在服务器上find一下看看文件究竟传到了哪里确认路径层级合理。5.5 远程终端里中文乱码或者命令找不到中文乱码通常是编码设置问题在PyCharm的Settings → Editor → File Encodings里把IDE Encoding和Project Encoding都设为UTF-8同时服务器上的locale也要是UTF-8一般默认就是。命令找不到大概率是PATH环境变量问题。远程终端是非交互shell不会加载你.bashrc里设置的内容。解决办法是在服务器上编辑~/.bashrc把conda或自定义路径加到PATH里然后source ~/.bashrc之后在PyCharm终端里如果还是找不到检查PyCharm的终端设置里是否有Shell path覆盖了默认shell。5.6 SSH服务故障快速诊断方法如果你本来就打算在自己的Linux服务器上开启SSH服务提供几个常用排查命令热词里ubuntu ssh无法连接基本都能靠这套流程找到答案# 查看SSH服务状态 sudo systemctl status sshd # 查看SSH服务监听的端口 sudo netstat -tlnp | grep :22 # 查看防火墙规则是否放行了端口 sudo ufw status # 测试本地能否直接连上在服务器本机执行 ssh localhost如果服务器本机ssh localhost可以连但外网连不上问题基本就在防火墙或者安全组。如果本机也连不上优先重启SSH服务sudo systemctl restart sshd同时查看日志sudo journalctl -u sshd -n 50里面通常有明确的报错原因比如监听了错误端口、公钥权限错误等。5.7 端口与安全的几个提醒网上常搜到网络攻击 ssh大量连接怎么办这个确实值得重视。如果你的服务器IP暴露在公网上SSH端口每天会被扫很多次日志里经常能看见一堆failed password记录。几个基础建议改用非默认端口比如22022能挡掉大部分自动化扫描安全风险会显著降低。配置PermitRootLogin no禁止root直接登录用普通用户登录后再sudo提权。有条件就只开放密钥登录关闭密码登录。使用fail2ban这类工具在多次失败尝试后自动封禁来源IP。这些不是PyCharm相关配置能解决的但远程开发的前提是服务器本身安全可靠。别项目没出问题服务器先被人拿了。6. PyCharm远程开发的进阶使用从能跑到顺手配置通了之后日常使用中还有几个能明显提升体验的设置分享几个我一直在用的方案。6.1 自动上传与手动上传的平衡在部署配置里勾选On Save自动上传好处是修改文件保存后立即同步到服务器缺点是频繁保存会触发很多次上传。写代码时习惯性按CtrlS的人会被这个行为烦到。我的做法是关键项目开自动上传一般项目手动上传。手动上传时右键项目根目录选Deployment → Upload to即可也可以用快捷键默认是CtrlShiftX不同版本不一样右键菜单里能看到。注意别把sync with deployed to之类的功能和Automatic Upload设置搞混了前者是双向同步谨慎使用因为服务器上的文件变化可能会直接覆盖你的本地版本。6.2 端口转发直接访问服务器的内部服务远程开发比较实用的场景是代码在服务器上跑了一个Web服务比如Flask或Django你想在本地浏览器里直接访问它。PyCharm的SSH配置里有一项是Port Forwarding可以用这个功能把服务器的127.0.0.1:8000转发到本地的8000端口。操作路径SSH Configurations→ 选中你的连接 →Open SSH Terminal旁边的下拉菜单里找Edit settings→ 在连接详情里配置端口转发规则。或者更简单地——直接在服务器上python manage.py runserver 0.0.0.0:8000然后本地浏览器访问your-server-ip:8000前提是服务器防火墙放行了8000端口。公司网络环境如果不允许直接开端口PyCharm的端口转发功能就派上用场了。6.3 快捷键在远程模式下是否可用远程模式下PyCharm的快捷键、代码补全、重构、版本控制功能基本都是完整的因为界面渲染和交互仍然是本地的。唯一有感的差异是高亮报错和自动补全的响应速度会受网络延迟影响延迟越高越明显。如果服务器离你几千公里远老老实实把代码改完再传上去跑别指望有本地顺滑的体验——这是远程开发的物理边界。6.4 多台服务器管理如果你有开发服务器和测试服务器两台机器可以在SSH Configurations里按不同的名称分别保存在切换Deployment和解释器时各自选择对应配置即可。需要注意区分项目级别的设置和全局级别的设置SSH Configurations在全局但Deployment和Python Interpreter是项目级的切换项目时会恢复成各自的配置。7. 用了一段时间之后的实际体验远程SSH这套方案我用了很长时间最终形成了几条个人结论。优点是真的解放了本地机器。CPU、内存、磁盘占用几乎都在服务器那边本地笔记本就算配置一般也能跑大的数据处理任务。代码在本地编辑、服务器执行的模式下CtrlS保存后代码立即同步到服务器调试过程中改几个参数再跑整个流程比想象中顺畅。缺点是初次配置确实麻烦。SSH连接、部署、解释器三个配置环环相扣任何一步错位都要回头排查。我建议你在正式项目上使用之前先拿一个小Demo项目把整个流程走一遍——连接服务器、上传代码、跑通运行三十分钟内应该能搞定。走过一遍之后再往大项目上切就会从容很多。还有一个容易忽略的点是存储空间。PyCharm远程模式下会在服务器上创建缓存和索引文件项目代码量大的话占用的磁盘空间可能比你预想的多。服务器磁盘紧张的话定期清理日志和缓存是必要的。最后再分享一个小经验远程开发时养成定期提交代码的习惯比平时更重要。因为你在本地改了代码、同步到服务器但整个过程都在本地编辑器中完成如果不提交Git代码在本地和服务器之间的流转路径可能会让你对哪个版本是最新的产生混乱。用Git管理好代码版本远程SSH只是替你执行代码代码本身始终在版本控制之下这样才能省心。