Pycharm跨系统远程开发：突破环境限制，高效开发

原创已于 2025-04-01 10:59:45 修改 · 2.8k 阅读

39 ·

CC 4.0 BY-SA版权

文章标签：

#pycharm #ide #python #经验分享 #开发语言 #个人开发 #远程开发

于 2025-04-01 10:43:18 首次发布

为什么选择 Pycharm 远程开发

对个人开发者，当本地电脑配置有限，无法满足复杂项目的运算需求时，可借助远程高性能 Linux 服务器资源进行开发，在本地 Windows 客户端进行代码的编写和调试，而让代码在 Linux 服务端运行，充分利用服务器强大的计算资源。

在团队协作项目中，不同成员可能习惯使用不同操作系统，通过远程开发，大家能统一基于 Linux 服务端环境进行开发，避免因环境差异产生的问题，确保代码一致性和兼容性。

前期必备条件

软件版本确认

你需要确保使用的是 Pycharm 专业版，因为只有专业版才支持远程开发功能。

查看 Pycharm 版本方式：

打开 Pycharm 软件，点击菜单栏中的 “Help”（如果是 Mac 系统，则点击 “PyCharm”），在下拉菜单中选择 “About PyCharm”，在弹出的窗口中即可看到当前 Pycharm 的版本信息。

服务器 SSH 服务开启

在 Linux 服务端，需要确保 SSH 服务已经开启。

大多数 Linux 发行版默认安装了 OpenSSH 软件包，如果没有安装，可以使用包管理器进行安装，例如在 Debian 或 Ubuntu 系统上，使用命令sudo apt-get install openssh-server ；

安装完成后，使用以下命令启动 SSH 服务：sudo systemctl start sshd

可以通过以下命令查看 SSH 服务状态，确保其正常运行：sudo systemctl status sshd

若显示 “active (running)”，则表示 SSH 服务已成功启动。如果希望 SSH 服务在系统启动时自动启动，可以执行以下命令：sudo systemctl enable sshd

Windows 客户端配置详细流程

新建项目或打开已有项目

打开 Pycharm 软件，如果你要创建一个新项目，点击 “Create New Project” ，在弹出的窗口中，选择项目类型（如 Python Interpreter），然后设置项目的存储路径和名称，点击 “Create” 即可创建一个新项目。如果你有已经存在的用于远程开发的项目，点击 “Open”，在文件浏览器中找到项目所在的文件夹，选中并点击 “OK” 即可打开该项目。

进入部署配置界面

在 Pycharm 菜单栏中，依次点击 “File” -> “Settings”（如果是 Mac 系统，则点击 “PyCharm” -> “Preferences”），在弹出的设置窗口中，展开 “Build, Execution, Deployment” 节点，然后选择 “Deployment” ，进入 Deployment 配置页面。

新增 SFTP 连接配置

在 Deployment 配置页面中，点击右上角的 “+” 按钮，选择 “SFTP” 。在弹出的配置窗口中，填写以下信息：

Name：可以自定义一个连接名称，方便识别，比如 “Linux Server” 。

Host：填写 Linux 服务器的 IP 地址。本地服务器外网连接可使用内网穿透，详见笔者另一篇笔记。

Port：SSH 服务的端口号，默认为 22，如果服务器的 SSH 端口有修改，需要填写对应的端口号。

Username：登录 Linux 服务器的用户名。

Password：登录 Linux 服务器的密码（如果使用 SSH 密钥认证，可以选择 “SSH authentication type” 为 “Key file”，并选择相应的密钥文件）。

填写完上述信息后，点击 “Test Connection” 按钮测试连接是否成功。

如果连接成功，会弹出提示框显示 “Connection successful” 。接着，在 “Root path” 中设置远程服务器上项目的根目录，比如 “/home/user/projects/my_project” 。

在 “Mappings” 选项卡中，设置本地路径和远程路径的映射关系，“Local path” 选择本地项目的路径，“Deployment path” 选择远程服务器上项目的路径，确保两者对应正确。

配置远程 Python 解释器

在 Pycharm 菜单栏中，依次点击 “File” -> “Settings”（或 “PyCharm” -> “Preferences”），在设置窗口中，展开 “Project: [你的项目名称]” 节点，选择 “Python Interpreter” 。

点击 Python Interpreter 设置页面右上角的齿轮图标，选择 “Add...” ，在弹出的窗口中，选择 “SSH Interpreter” ，然后在 “Existing server configuration” 下拉框中选择刚才配置的 SFTP 连接。

接下来，Pycharm 会自动检测服务器上的 Python 解释器路径，如果检测到多个 Python 解释器，可以根据项目的需求选择合适的解释器路径。

选择完成后，点击 “Next”，然后点击 “Finish” 完成远程 Python 解释器的配置。

Linux 服务端的必要设置

检查 Python 环境

登录到 Linux 服务器后，打开终端，输入python --version命令，查看当前系统默认的 Python 版本。

如果系统中安装了多个 Python 版本，例如同时存在 Python 2 和 Python 3，并且你的项目需要特定版本的 Python，那么你可能需要使用which python命令查看 Python 解释器的路径，以确认当前使用的 Python 版本是否符合项目需求。

如果不符合，你可以通过修改环境变量或者使用版本管理工具（如conda）来切换或创建符合需求的 Python 环境。

权限设置

在 Pycharm 远程开发过程中，如果出现权限不足导致无法访问或操作文件的情况，就需要在 Linux 端调整文件或目录权限。

在 Linux 系统中，每个文件和目录都有对应的权限设置，分别对应所有者、所属组和其他用户的读（r）、写（w）、执行（x）权限。假设你的项目文件位于/home/user/projects/my_project目录下，而你当前登录的用户对该目录没有写权限，无法在 Pycharm 中进行文件修改保存等操作。

这时，你可以使用chmod命令来修改权限，例如赋予所有者读写执行权限，所属组和其他用户只读权限：

chmod u=rwx,g=r,o=r /home/user/projects/my_project

或者使用数字表示权限，将上述命令简化为：

chmod 744 /home/user/projects/my_project

其中，数字 7 表示所有者权限为读写执行（4 + 2 + 1），4 表示群组和其他用户权限为只读。如果要修改整个目录及其子目录和文件的权限，可以加上-R选项，例如：

chmod -R 744 /home/user/projects/my_project

这样就可以递归地修改整个项目目录的权限，确保 Pycharm 在远程开发时能够正常访问和操作文件。需要注意的是，修改权限时要谨慎操作，避免因权限设置不当导致安全问题。如果你不确定如何设置权限，可以先备份重要文件，然后逐步调整权限并测试，直到满足开发需求。

测试连接与使用验证

测试连接

完成上述配置后，回到 Deployment 配置页面，点击刚才配置的 SFTP 连接，然后点击右上角的 “Test Connection” 按钮，如果弹出 “Connection successful” 的提示框，则说明 Windows 客户端与 Linux 服务端连接正常。这一步很关键，它确保了后续代码同步和运行的基础连接是稳定的。如果连接失败，需要检查之前填写的 IP 地址、端口号、用户名和密码等信息是否正确，也可以检查服务器的 SSH 服务是否正常运行以及防火墙是否限制了该连接。

代码同步测试

在本地 Pycharm 项目中，新建一个 Python 文件，比如test.py ，在文件中随便写入一些代码，例如：

print("This is a test.")

保存文件后，切换到 Linux 服务端，进入之前设置的项目根目录，查看是否出现了新创建的test.py文件，并且文件内容是否与本地一致。同样，在 Linux 服务端修改test.py文件内容，比如将其改为：

print("This is a modified test.")

保存后，回到本地 Pycharm，观察test.py文件是否自动更新为修改后的内容。通过这样的双向测试，可以确认本地和远程文件的同步功能是否正常。

如果文件没有自动同步，可以检查 Deployment 配置中的 “Automatically upload files to the default server” 选项是否勾选，以及本地和远程路径的映射关系是否正确。

运行测试

在本地 Pycharm 中，右键点击test.py文件，选择 “Run 'test.py'” ，观察 Pycharm 的运行控制台输出。如果配置成功，应该可以看到在远程 Linux 服务器上执行test.py文件的结果，即输出 “This is a modified test.” 。

这表明代码不仅能够在本地进行编写和同步，还能在远程服务器上正确运行，实现了 Pycharm 远程开发的完整功能。如果运行过程中出现错误，需要检查远程 Python 解释器的配置是否正确，项目依赖的库是否在远程服务器上安装等问题。例如，如果项目依赖numpy库，而远程服务器上未安装，就会导致运行失败，此时需要在远程服务器上使用包管理器安装相应的库，如pip install numpy 。通过以上测试连接和使用验证的步骤，就可以确保 Pycharm 远程开发环境配置正确且能够正常使用，为后续的开发工作提供稳定的基础。

常见问题及解决办法

连接失败问题

在进行 Pycharm 远程开发时，连接失败是一个常见问题，可能由多种原因导致。

网络问题：可能是本地网络不稳定，或者服务器端网络出现故障，比如服务器所在网络的网关设置错误、网络接口故障等。可以先在本地使用ping命令测试与服务器的连通性，例如ping 服务器IP地址，如果出现大量丢包或者无法 ping 通，说明网络存在问题。解决办法是检查本地网络连接，如路由器设置、网线连接等，也可以联系服务器管理员检查服务器网络配置。

用户名密码错误：在配置 SFTP 连接时，填写的用户名或密码错误会导致连接失败。仔细核对输入的用户名和密码是否正确，注意区分大小写。如果忘记密码，可以联系服务器管理员重置密码。

防火墙阻挡：服务器端的防火墙可能会阻止 Pycharm 的连接。例如，默认情况下，防火墙可能只允许特定的端口进行通信，而 SSH 服务的默认端口 22 可能被防火墙限制。可以在服务器端检查防火墙规则，查看是否限制了 SSH 端口。如果是云服务器，还需要在云平台的安全组规则中添加允许 SSH 连接的规则。以 CentOS 系统为例，使用firewall-cmd --zone=public --add-port=22/tcp --permanent命令开放 SSH 端口，然后执行firewall-cmd --reload使规则生效。

代码无法同步

当出现代码无法同步的情况时，可从以下方面排查：

路径配置错误：在 Deployment 配置的 “Mappings” 选项卡中，本地路径和远程路径的映射关系设置错误，会导致代码无法正确同步。仔细检查 “Local path” 和 “Deployment path” 是否与实际项目路径一致，确保映射路径正确无误。

同步设置未开启：Pycharm 中如果没有勾选自动上传文件选项，代码修改后不会自动同步到远程服务器。在 Deployment 配置页面，确保勾选了 “Automatically upload files to the default server” 选项。如果还存在问题，可能是 Pycharm 版本问题，可以尝试更新到最新版本。

远程环境库缺失

当在本地能正常运行代码，但在远程服务器运行时提示库缺失，解决办法如下：

使用包管理器安装：如果项目使用pip作为包管理器，在远程服务器的终端中，激活项目对应的 Python 环境（如果使用了虚拟环境），然后使用pip install 库名命令安装缺失的库。例如，项目依赖requests库，在终端中执行pip install requests 。如果服务器上安装了conda，也可以使用conda install 库名命令进行安装。