企业官网建设流程全解析

很多人第一次给云主机配 PyCharm 远程开发，都是照着某篇教程把 IP、端口、账号密码填进去，点一下 Test Connection 看见绿色对勾，就以为大功告成。真正开始跑代码才发现：解释器一选就标红、装好的包在远端找不到、本地改完的代码远端纹丝不动、跑到一半连接断了还得重连。这些问题八成不在 PyCharm 本身，而是在前面几步——账号权限、Python 路径、SSH 服务端配置、路径映射——被跳过了。这篇就把 PyCharm 远程连接云服务器这条链路从头到尾拆开讲一遍，包括每一处配置为什么要这么填、填错会表现出什么症状、以及我自己用了一年多之后固定下来的那套习惯。标题里那台云主机，下文统一叫远端机器，本地这台开发机叫本地机器。适合已经有一台云主机、想把本地开发体验搬过去的人，也适合配置过一次但总感觉"能跑但不敢动"的人。全程用 PyCharm 专业版演示——社区版没有远程解释器和部署模块，这是前提，绕不过去。

1. 把"远程连接"拆成三件独立的事，先搞清楚 PyCharm 在远端做了什么

绝大多数教程把"远程连接"当成一个动作讲，于是读者脑子里也只有一幅模糊的画面：本地 PyCharm 连上远端机器，然后代码就在远端跑了。这个心智模型太粗，一旦出问题就无从下手。实际上一套完整的远程开发链路里，至少有三个互相独立、可以单独失效的环节：代码放在哪、解释器在哪跑、IDE 的索引和补全靠谁算。PyCharm 提供的几种远程方案，本质上就是这三个环节的不同组合方式。

1.1 远程解释器、文件同步、远程 IDE 后端：三种方案跑的是不同的活

最常用的方案是SSH 远程解释器。代码物理上仍然在本地，通过 SFTP 同步一份到远端，Python 解释器运行在远端。你点运行，PyCharm 把本地文件传上去，在远端调起 Python 执行，再把 stdout、stderr 回传到本地控制台。这个方案的关键特征是：索引、补全、语法分析全部在本地完成，远端只负责"跑"。所以它对远端机器的配置要求很低，1 核 2G 都能用，代价是本地机器要扛得住索引。

第二种是单独的部署（Deployment）配置。它只负责文件传输，不参与运行。很多人分不清它和远程解释器的关系：远程解释器内部其实也带一套路径映射，但如果你想做"手动上传""对比远端文件""下载远端产物"这类操作，就得单独配一个 Deployment。两者可以共用同一份 SSH 连接配置，这是 PyCharm 设计上比较顺手的一点。

第三种是远程 IDE 后端（Gateway 方案）。这个方案把整个 IDE 后端进程搬到远端机器上跑，本地只留一个瘦客户端负责渲染界面。代码、索引、解释器、终端全在远端，本地机器几乎不消耗资源。听起来很美，但它对远端机器的要求直接翻了几倍：内存建议 8G 起，4G 属于勉强能开、开完就卡的水平。而且后端组件需要在远端下载安装，第一次连的时候会有一个明显的等待过程。

记住一句话：远程解释器是"本地算、远端跑"，Gateway 是"远端算、远端跑"。选错了不是不能work，是体验会一直别扭。

1.2 选型判断：什么情况下远程解释器够用，什么情况下必须上 Gateway

先说结论：大部分个人自用场景，SSH 远程解释器就够了。理由很现实——你需要的往往只是"用远端的 GPU / 用远端的算力 / 用远端那套已经配好的环境"，本地机器性能并不差。这种情况下把 IDE 后端搬到远端，纯属给自己找麻烦，还白白吃掉远端那点宝贵的内存。

什么情况下应该考虑 Gateway？我总结了三类：第一，本地机器性能确实吃紧，打开一个稍大的项目索引就跑满 CPU，风扇狂转；第二，项目依赖极度庞杂，本地根本装不全，必须完全依赖远端环境才能获得正确的补全和跳转；第三，你需要多人连同一台远端机器协作，代码只存在远端一份，谁都不想在自己电脑上存副本。

还有一个容易被忽略的判断维度：网络质量。远程解释器方案下，每次运行都要上传改动过的文件，网络抖动会直接体现在"点运行到开始输出"的延迟上；Gateway 方案下，界面渲染本身就要走网络，抖动会变成操作卡顿。前者对网络的容忍度更高一些，因为文件传输有增量机制，而界面渲染是实时的。

我自己最终的取舍是：日常写业务代码用远程解释器，需要长时间跑训练任务、本地完全不开 IDE 的时候，才用 Gateway 连上去看看日志和调参。两套配置可以并存，SSH 连接配置复用同一份，切起来不冲突。

2. 远端机器先收拾干净：账号、Python、SSH 三处最容易埋雷

我见过太多"PyCharm 连不上"的求助，最后定位下去，问题全在远端机器这边，跟 PyCharm 一毛钱关系没有。所以我的建议是：先把远端机器准备到一个"用命令行能完整跑通"的状态，再去动 PyCharm。如果命令行都跑不顺，图形界面只会把错误信息藏得更深。这一节按账号、Python、SSH 的顺序讲，顺序本身就是排查优先级。

2.1 建一个专用账号，别拿最高权限账号跑全部流程

新手最省事的做法是直接用 root 或默认管理员账号连上去，一路畅通无阻。短期确实爽，长期全是坑。第一个直接后果是文件属主错乱：你用 root 创建的项目目录，后续用普通账号去同步文件会写不进去，PyCharm 报"Permission denied"但界面上看不出是谁的锅。第二个后果是虚拟环境和 pip 装包会装到系统级路径，几个项目之间互相污染，A 项目升级了个库，B 项目直接跑不起来。

我的做法是建一个专用账号，比如devuser，所有开发相关的操作都在它下面完成：

# 在远端机器上，用管理员权限执行 useradd -m -s /bin/bash devuser passwd devuser # 需要 sudo 时再单独授权，不要一上来就给全部权限

然后确认家目录权限正确：

ls -ld /home/devuser # 期望 drwx------ 或 drwxr-x--- ls -ld /home/devuser/workspace # 项目目录的属主必须是 devuser

如果接手的是别人配过的机器，或者之前用管理员账号操作过，大概率会遇到属主不对的情况。修复方式就是chown -R devuser:devuser /home/devuser/workspace。这一步看着琐碎，但它是后面所有"上传失败""写不进去"问题的总开关。

一个自查习惯：用准备连接 PyCharm 的那个账号登录，touch /home/devuser/workspace/test.txt能成功，说明写权限没问题。这一步比在 PyCharm 里点半天 Test Connection 有效得多。

2.2 Python 与虚拟环境的路径必须能一句话说清

PyCharm 配远程解释器的时候，最关键的输入项就是一个绝对路径。它会问你：远端的 Python 解释器在哪？如果你答不上来，或者答了个"python"这种依赖 PATH 的写法，后面一定会出问题——因为 PyCharm 的 SSH 会话拿到的 PATH 和你交互式登录拿到的 PATH 经常不一样。

所以先在远端把路径确认清楚：

# 确认系统 Python which python3 python3 -V # 建一个项目专属虚拟环境（强烈建议，不要用系统 Python 直接跑项目） python3 -m venv /home/devuser/venvs/proj-x # 确认虚拟环境里的解释器路径 ls -l /home/devuser/venvs/proj-x/bin/python

这里有个细节值得展开：venv建出来的bin/python通常是个软链接，指向系统的 python3。PyCharm 认这个软链接，但有些场景下（比如虚拟环境被移动过、或者远端重装过 Python）软链接会断，表现就是"解释器无效"。判断方法很简单，在远端直接执行一次：

/home/devuser/venvs/proj-x/bin/python -c "import sys; print(sys.executable)"

能打印出路径就说明解释器本身是健康的。这一步花十秒钟，能省掉后面半小时的困惑。

另外提醒一点：项目路径和虚拟环境路径里不要出现中文、空格、括号。PyCharm 的路径映射、SFTP 传输、shell 命令拼接在遇到这些字符时表现不稳定，有些能处理，有些会在奇怪的地方失败，报错信息还完全不知所云。用纯英文加下划线或者短横线，是最省心的选择。

2.3 SSH 服务端配置里真正影响 PyCharm 的几项

PyCharm 连远端走的就是标准 SSH，所以远端 SSH 服务的配置直接决定了你能不能用、稳不稳。这里只说真正会影响使用的几项，都在/etc/ssh/sshd_config里。

第一是认证方式。密码登录在前期调试时方便，但长期用建议切到密钥认证。PyCharm 的 SSH 配置支持 Key pair，指定私钥文件即可。生成密钥建议用 ed25519，比 RSA 短且更现代：

# 本地机器上生成 ssh-keygen -t ed25519 -C "dev-remote" # 把公钥内容追加到远端账号的 authorized_keys # 远端执行： mkdir -p ~/.ssh && chmod 700 ~/.ssh vi ~/.ssh/authorized_keys # 粘贴公钥内容 chmod 600 ~/.ssh/authorized_keys

权限位是硬性要求，~/.ssh必须是 700，authorized_keys必须是 600。权限过宽 SSH 服务会直接拒绝使用这个密钥，而且日志里写得很清楚，PyCharm 弹出来的报错则只有一句"Authentication failed"，非常误导人。

第二是连接保活。SSH 空闲一段时间会被中间链路或者服务端断开，表现是 PyCharm 用着用着突然提示连接丢失，重新连上之后索引又要重来一遍。服务端可以加两个参数缓解：

ClientAliveInterval 60 ClientAliveCountMax 3

意思是每 60 秒发一次探活，连续 3 次无响应才判定断开。改完记得重载服务：systemctl reload sshd（不同发行版服务名可能是ssh）。

第三是端口。默认 22 不是必须改，但如果你的机器暴露在公网上，改成非标端口能过滤掉大量无意义的扫描尝试，日志会干净很多。改端口的同时，云平台控制台的入方向规则也要跟着放行，这一处不同步是最常见的"改了端口就再也连不上"的原因。安全规则里只放行你实际要用的端口，数据库、缓存这类服务的端口不要对公网开放。

3. PyCharm 这一侧的完整配置链路：从新建 SSH 连接到跑通第一个脚本

远端准备就绪之后，PyCharm 这边其实只有四件事：建连接、选解释器、配映射、配同步。每一件都有明确的验证方法。我按实际操作顺序走一遍，并在每一步标注"这一步做完了应该看到什么"，方便你对照着确认。

3.1 新建 SSH 配置时的字段填写与"Test Connection"的真实含义

入口在Settings → Project → Python Interpreter → Add Interpreter → On SSH。第一次会让你新建一个 SSH Configuration，字段分别是 Host、Port、Username，然后选 Password 或 Key pair。

Host 填公网地址或者你在~/.ssh/config里配的别名都能识别。Port 就是 SSH 服务端口。Username 必须是你在 2.1 里建的那个专用账号，不要填管理员账号。选 Key pair 的话，私钥路径指向本地生成的私钥文件，passphrase 如果设了就填上。

点Test Connection出现绿色提示，只说明网络可达 + 认证通过。它完全不验证：你的账号能不能写项目目录、远端有没有可用的 Python、Python 版本是不是项目要求的。这就是为什么很多人 Test Connection 过了，下一步立刻卡住。

如果 Test Connection 失败，报错信息本身就是分叉点：Connection refused指向端口或服务没开；Connection timed out指向网络不通或者安全规则没放行；Authentication failed指向账号、密钥或文件权限。这三种在 4.1 里还会展开。

再往下一步是选解释器类型，这里有两个选项：System Interpreter（指向系统 Python）和Virtualenv（让你填虚拟环境目录）。我强烈建议选后者，路径填/home/devuser/venvs/proj-x/bin/python。选系统解释器的后果是：后面 pip 装的所有东西都进系统环境，你在远端终端里用虚拟环境跑脚本时会发现包全都不见了，然后开始怀疑人生。

3.2 解释器路径与路径映射：这里填错，后面全是玄学问题

选完解释器之后，PyCharm 会让你填 Path mappings。左边是本地项目根目录，右边是远端项目根目录。

这里的逻辑必须想明白：PyCharm 运行脚本时，会先算出脚本在本地路径下的相对位置，再拼到远端路径上，然后在远端执行。比如本地是D:/work/proj-x，远端映射到/home/devuser/workspace/proj-x，那么本地的D:/work/proj-x/src/train.py在远端会被当作/home/devuser/workspace/proj-x/src/train.py去执行。

映射填错的典型症状非常好认：运行时报can't open file '/home/devuser/workspace/proj-x/src/train.py': No such file or directory。或者反过来，能跑起来但__file__相关的相对路径全错，读配置文件读不到。遇到这类报错，先别改代码，去 Deployment 里看一眼远端那个路径下到底有没有文件。

我个人的习惯是让两边的目录名保持一致，只是根不同。这样在日志里看到路径能立刻对应上，排查时不至于来回换算。

还有一点：映射的远端目录必须是 2.1 里确认过可写的那个目录。如果映射到/root/xxx或者/opt/xxx，运行时会因为权限不足失败，而且 PyCharm 给出的错误信息经常只是"Exit code 1"，具体原因藏在 stderr 里，得往下翻。

3.3 部署配置和自动上传的触发条件

远程解释器工作的时候会自动同步文件，但如果你想控制"哪些文件同步、什么时候同步"，就需要单独配 Deployment。入口是Tools → Deployment → Configuration，新建一个类型为 SFTP 的服务器，SSH 那一项直接选 3.1 里建好的连接，不用重复填。

Connection 页签里填 Root path，也就是远端项目根目录；Mappings 页签里填本地路径和部署路径的相对关系。比较省事的填法是：本地路径填项目根，部署路径填/，Root path 填远端项目根，这样两边就对齐了。

Options 页签里有几个开关值得说：

• Create empty directories：本地建了空目录，远端也同步建。如果代码里有依赖空目录（比如日志目录）的逻辑，建议勾上。
• Delete target items when source doesn't exist：本地删了，远端也删。这个建议谨慎，一旦本地误删，远端那份也没了，回滚余地就没了。除非你能确保远端代码有备份，否则别勾。
• Exclude items by name：排除规则，见 5.1，这是最关键的一项。

自动上传的开关在Tools → Deployment → Automatic Upload (Always)，或者在 Options 里设Upload changed files automatically to the default server，可选 On explicit save / Always / Never。我的设置是Always，因为远程解释器方案下，你很容易在编辑器里改完直接点运行，如果靠手动保存触发，偶尔会忘了保存，跑的是旧代码，然后开始怀疑解释器缓存。用 Always 就是用一点点带宽换确定性，很值。

3.4 一份跑通验证清单：五步确认整条链路是通的

配置完别急着上真实项目，用最小化的方式验证一遍。我固定跑这五步：

1. 在远端终端里执行/home/devuser/venvs/proj-x/bin/python -V，确认解释器可用。
2. 本地在项目根下新建ping_test.py，内容就一行import sys; print(sys.executable)。
3. 运行它，看控制台输出的路径是不是远端的虚拟环境路径。是本地路径就说明解释器选错了。
4. 再打印import os; print(os.getcwd())，确认工作目录在远端映射路径下。
5. 用 PyCharm 底部的 Remote Host 窗口展开远端项目根，确认ping_test.py确实被传上去了。

五步全过，说明连接、认证、解释器、映射、同步整条链路都是通的。之后遇到任何问题，都可以退回到这五步来定位是哪一环断了。这套验证方法的价值在于：它把"远程开发能不能用"这个模糊问题，拆成了五个各自有明确通过标准的检查点。

4. 按现象排查：四类高频故障的完整定位链路

我自己的排查习惯是先看现象分类，再动手改配置。绝大多数人一遇到问题就开始乱改，改完更乱，最后连原本能跑的状态都回不去了。下面四类是我踩过最多次的，每一类都给一条从现象到根因的完整链路，不直接给答案，因为答案往往只有一个，链路才是可复用的。

4.1 连不上：Connection refused / timeout / auth fail 的分叉判断

这三种报错看着像，根因完全不同，必须分开处理。

Connection refused意思是网络通了，但目标端口上没有服务在监听。第一步确认 SSH 服务是不是在跑：systemctl status sshd。服务正常的话，看监听端口：ss -tlnp | grep sshd。如果服务监听在 2222 而你在 PyCharm 里填的是 22，那就是端口不对。还有一种情况是服务只监听了内网地址，公网请求被拒。

Connection timed out意思是连 SYN 包都没回来，请求在中间被丢了。查两处：云平台控制台的入方向安全规则有没有放行该端口；远端机器自身的防火墙（iptables、firewalld、ufw三者看你用的是哪个）有没有拦。判断方法是在本地用telnet 远端地址 端口或者nc -zv 远端地址 端口，通了说明不是防火墙问题，不通就往这个方向查。

Authentication failed意思是 TCP 连上了，SSH 握手到了认证阶段被拒。这一类的排查顺序是：账号名有没有打错（尤其注意别把账号和主机名搞混）；密码/密钥是否正确；密钥文件权限位是不是过宽（本地私钥通常要 600）；远端~/.ssh和authorized_keys的权限位是否正确。最后去远端看认证日志，/var/log/secure或/var/log/auth.log，里面会明确写是"invalid user"还是"publickey denied"，比 PyCharm 的提示精确一百倍。

排查顺序上有个原则：先在命令行把ssh 账号@地址 -p 端口跑通，再去 PyCharm 里配。命令行过不了，图形界面一定过不了。

4.2 解释器标红、包装不上：多半不是网络问题

远程解释器配好之后，Project Interpreter 页面转圈然后显示一堆红色，或者在 PyCharm 里装包失败，很多人第一反应是"远端网络不好，装不上包"。实际上远端能正常跑脚本，说明网络是通的，问题通常在别处。

第一个可能：解释器路径指向的环境没有 pip。用venv建的虚拟环境默认带 pip，但如果环境是人工拼出来的，或者用--without-pip建的，就没有。远端执行~/venvs/proj-x/bin/pip -V确认一下。

第二个可能：PyCharm 用的解释器和你在终端里用的不是同一个。这是最高频的。判断方法就是 3.4 第 3 步，打印sys.executable。很多人的情况是：PyCharm 里配的是系统 Python，终端里激活的是虚拟环境，于是在终端里pip install装上了，PyCharm 里却一直显示没有。

第三个可能：装包时用了远端连不上的源。如果远端访问外部资源受限，可以换成内部镜像源。这一项在pip.conf里配，或者装包时加-i参数指定。这条不算敏感操作，但要注意别把私有源地址写进提交到仓库的配置文件里。

第四个可能：索引缓存没刷新。改了环境之后 PyCharm 不会立刻感知，需要手动触发一次解释器重载：在 Interpreter 页面点刷新按钮，或者File → Invalidate Caches。这个操作很轻，但经常立竿见影。

4.3 本地改了代码远端没变：自动上传的三个失效原因

症状很典型：本地编辑器里明明是改过的代码，运行时输出的还是旧结果，去远端看文件时间戳也没变。这一类问题有三个常见原因，按概率排。

第一种：自动上传没开或者没生效。检查Tools → Deployment → Automatic Upload是否勾选，以及当前文件所属的 Deployment 是不是默认服务器。PyCharm 允许多个 Deployment 共存，如果项目关联到了另一个服务器，上传会跑到别的地方去。

第二种：文件被排除规则挡住了。Exclude items by name 里如果有*.py或者目录级的规则写得太宽，某些文件就不会同步。这类问题最隐蔽，因为界面没有任何提示，你只是发现文件没传上去。排查方法是在Tools → Deployment → Upload to...里手动上传一次，看它有没有跳过这个文件。

第三种：映射路径对不上。本地文件所在的目录不在映射范围内，PyCharm 就不知道它该传到远端哪里，于是静默跳过。这种情况常见于新建的目录、或者把文件挪到了项目根之外。

排查这类问题的通用方法是打开Tools → Deployment → Browse Remote Host，直接对比两边的文件列表和时间戳。图形化对比比猜快得多。

4.4 断线、卡顿、索引转圈：连接保活与资源占用的处理

用久了会遇到"连接莫名断开，重连后索引重来一遍"。这是 SSH 空闲超时导致的，处理方式在 2.3 已经说过，客户端侧也可以配。PyCharm 的 SSH 配置里可以选择使用内置 SSH 还是系统 OpenSSH，内置的实现对断线重连的处理相对友好一些，网络不稳定的环境可以优先试它。

卡顿分两种。一种是操作界面卡：输入延迟、菜单响应慢，这种通常是本地索引在跑，等它跑完就好，或者在Settings → Project → Shared indexes里让公共库索引走共享方式。另一种是运行卡：点运行之后要等好几秒才开始输出，这种是文件上传的耗时，项目越大越明显。减少上传量的办法就是 5.1 里的排除规则。

索引转圈还有一种情况值得单独提：远端机器内存吃紧。如果你用的是 Gateway 方案，IDE 后端在远端跑，内存不够的时候整个界面都会跟着钝。判断方法是在远端free -h看一眼 available 还剩多少，如果长期低于 500M，基本可以确认是这个问题。这时候要么升配，要么退回远程解释器方案。

5. 长期使用要养成的几个习惯：同步策略、目录规范和回滚

配置能跑通只是起点。用上几个月之后，真正决定体验的是几个看起来不起眼的习惯。这些习惯不会让你的程序跑得更快，但会让你在出问题的时候少花几个小时。

5.1 排除目录清单和它的实际收益

远程解释器方案下，每次运行都要把改动过的文件传上去。如果.git、__pycache__、虚拟环境目录、数据集缓存这些都被算进同步范围，上传量会膨胀十几倍，还可能因为文件数太多导致超时。

排除规则在Tools → Deployment → Options → Exclude items by name，用分号分隔，支持通配符。我的固定清单：

.git; .idea; __pycache__; *.pyc; *.pyo; .venv; venv; node_modules; .mypy_cache; .pytest_cache; logs; data; *.log; .DS_Store

这份清单里每一项都有明确理由。.git不同步，因为远端不需要再存一份完整历史；__pycache__和*.pyc不同步，因为远端会自己生成，传过去反而可能因为 Python 版本不一致导致加载失败的缓存文件；logs和data不同步，因为它们往往很大且只增不减；.idea不同步，因为里面是本地的项目配置，两边混用容易出乱子。

有一条经验值得单独说：不要把虚拟环境目录放在项目目录内部。虽然本地开发这样很方便，但在远程场景下，它会让同步、备份、grep搜索全都变慢。虚拟环境统一放~/venvs/下，项目目录里只放代码和配置。

5.2 项目路径、虚拟环境、数据目录的放置规范

我在远端固定用这样一套目录结构，用久了会发现排查效率高很多：

/home/devuser/ ├── venvs/ # 所有虚拟环境，一个项目一个 │ └── proj-x/ ├── workspace/ # 所有项目代码 │ └── proj-x/ ├── data/ # 数据集、模型文件，不进代码目录 │ └── proj-x/ └── logs/ # 运行日志，按项目分 └── proj-x/

好处有三个。第一，代码目录变小了，备份和同步都快。第二，数据和代码分离，误删代码目录不会连带毁掉数据集。第三，日志集中，出问题的时候tail -f ~/logs/proj-x/app.log一条命令就能看，不用在各层目录里翻。

对应的，代码里所有涉及数据路径和日志路径的地方，都用绝对路径或者环境变量，不要用../data这种相对路径。远程开发场景下，工作目录经常和你以为的不一样，相对路径是最容易出问题的地方。我一般在配置文件里留一个DATA_ROOT环境变量，本地和远端各配各的，代码里只引用变量名。

5.3 远端代码的备份与回滚

远程开发有个容易被忽视的风险：代码只有一份在远端，而且远端是你随时可能重装、重买的那台机器。本地虽然有副本，但如果远端跑出了一些只在远端才有的改动（比如现场调试时临时改的参数），这部分是没有任何保护的。

我的做法很轻量：项目在远端也初始化一个 Git 仓库，平时不用，只在关键节点做一次快照提交。配合.gitignore把数据、日志、虚拟环境都排除掉，仓库体积很小，几秒钟就提交完。真出了事，git reset --hard或者git checkout .能救回来。

另外，部署配置里那个"删除目标文件"的开关，我建议一直关着。理由很直白：自动同步本身已经是一个有风险的操作，再叠加一个自动删除，一旦本地某次操作失误（比如误删目录、或者切错分支），远端那份也就没了。宁可手动清理，也别让它自动删。

6. 我自己的配置速查表与几条不写在文档里的经验

最后把我这一年多沉淀下来的配置整理成一张表，以及几条不容易在文档里看到、但真正影响使用体验的经验。

6.1 场景对照表

对应到 PyCharm 的具体配置项，速查如下：

6.2 几条踩出来的经验

第一条：先用命令行把一切跑通，再动图形界面。这句话我说过很多次，但每次遇到问题还是会被验证一遍。SSH 连不上、解释器不生效、包装不上，这三类问题在命令行里都有明确的报错，在图形界面里往往只剩一句"失败"。

第二条：不要在项目根目录下用中文命名任何东西。包括目录名、文件名、虚拟环境名。PyCharm 在这块的容错能力比想象中差，有些操作（尤其是路径映射和 shell 命令拼接）会在中文目录下出现难解释的失败。换成英文，问题消失。

第三条：改配置之前先记录当前能用的状态。PyCharm 的项目配置存在.idea目录里，改之前复制一份整个目录，出问题直接还原。我吃过亏——乱改一通之后发现原来的配置也回不去了，最后只能重建项目。这个成本太高，提前备份几乎零代价。

第四条：远端机器的时区要设对。听起来和远程开发没关系，但日志时间戳差 8 小时的时候，你会怀疑人生。timedatectl set-timezone Asia/Shanghai一条命令的事，顺手做了。

第五条：别在远端跑需要长期占住终端的交互式命令。远程解释器方案的终端是跟着 IDE 会话走的，会话一断，进程可能被挂断信号带走。需要长跑的任务，用nohup或者放后台，输出重定向到文件，然后tail -f看。这一条救过我一次跑了六个小时的任务。

第六条：远程解释器装包，优先在远端终端里装。PyCharm 的包管理界面偶尔会因为解释器重载不及时导致装完了还显示未安装，直接在远端~/venvs/proj-x/bin/pip install xxx更快更确定，装完回 PyCharm 刷新一下解释器即可。

这套配置我从最开始的"每次连接都提心吊胆"，到现在的"基本不用管它"，中间大约踩了七八个坑，大部分都写在上面了。真正让我省心的不是某个神奇配置，而是把"本地能跑、远端能跑、两边一致"这三件事拆成了可验证的小检查点，任何一处不对劲都能立刻定位。上面那份五步验证清单，建议你直接抄下来存成文本文件放在项目根下，下次换机器或者换项目，照着走一遍就行。