PyCharm配置Git远程仓库：从安装到SSH密钥推送完整指南

这篇就来聊聊 PyCharm 配置 Git 上传代码到仓库这件事。标题里这几个关键词——PyCharm、Git、仓库、配置——基本就是新手阶段最常卡住的四个环节。很多刚接触开发的朋友代码写得还行但一说到把代码传到远程仓库就一脸茫然Git 是什么PyCharm 里那个绿框框干嘛的为什么传个代码还有那么多报错这篇内容就是冲着这些问题来的。我会从 Git 安装、PyCharm 内部配置、远程仓库创建、SSH 密钥配置到最终用图形界面完成提交和推送整个流程全部走一遍。中间会穿插我实际使用中踩过的坑和验证过的解决方法。不管你是完全没接触过 Git 的新手还是已经能看懂一些报错但始终没搞明白完整流程的初学者这篇都值得你跟着做一遍。1. 为什么要在 PyCharm 里配 Git先搞清楚这套组合到底帮你解决了什么1.1 不懂版本控制的人生备份全靠改文件名回想一下你刚学编程时的样子。写了一下午的代码怕改出问题于是把文件复制一份命名为main_final.py。又改了一轮再复制一份变成main_final_v2.py。等晚上再看你文件夹里已经躺着五六个长得差不多的 py 文件根本分不清哪个是当前要用的版本。Git 解决的就是这个痛点。它帮你在每个关键节点给代码拍一张快照想回到哪个状态就回到哪个状态不需要手动复制文件。配合远程仓库比如 Gitee、GitHub你等于有了一个保存在服务器上的备份本地电脑坏了也不怕丢代码。1.2 图形化集成到底省了哪些命令纯用命令行操作 Git 完全可行官方工具 Git Bash 里敲git add、git commit、git push这些命令写多了也不难。但如果你日常的主力开发工具是 PyCharm那完全没必要在终端和 IDE 之间来回切换。PyCharm 把 Git 的常用操作全部做成了按钮。文件右键就能提交界面底部有分支列表推送拉取有专门的弹出窗口冲突合并也有可视化的对比工具。这相当于把一堆 Linux 风格的命令翻译成了你鼠标点一点就能完成的操作。对于不熟悉命令行的新手来说学习成本低了一大截。One more thingPyCharm 自带的代码比对工具非常好用。你改了哪些文件、哪个文件的哪些行有改动左边旧版本右边新版本颜色高亮对比比在终端里敲git diff刷屏要直观太多。1.3 适合谁看看完能到什么水平这篇内容覆盖的流程特别适合这几类人刚装好 PyCharm、正打算系统学习开发的新手写过一些本地代码但不知道怎么传到 Gitee 或 GitHub 的学习者以及已经在用 Git 命令行、但想在 PyCharm 里把所有操作统一到图形界面的同学。跟着走完一遍你会掌握三件事第一把 Git 装好并在 PyCharm 里认出来第二在代码托管平台上创建仓库并配置好 SSH 密钥第三把本地项目完整推送到远程仓库并且能自己解决推送过程中最常见的报错。2. 环境准备先把 Git 本体装好再谈 PyCharm 集成2.1 去官网下载 Git而不是去第三方网站新手常犯的第一个错误就是从搜索引擎里随便找一个看起来很官方的下载站。结果下载下来要么是捆绑了一堆广告软件的旧版本要么干脆是盗版的绿色版装完就出各种莫名其妙的问题。Git 的官方下载地址是git-scm.com页面打开后点击 Downloads选择你自己的操作系统版本。Windows 用户记得下载 64 位的独立安装包文件签名和版本号都很清楚。下载速度如果比较慢也可以用国内镜像源但一定要确认镜像站是可信的。安装包拿到手后先看大小和数字签名正规包一般在 50M 左右过小或者文件来源不明的一律不用。2.2 安装过程中的关键勾选项Git 的安装界面虽然全是英文但真正需要你动脑子的选项不多。整个安装向导大概有十几步大部分保持默认即可。不过有几个选项建议你按下面这样处理。第一个是 Select Components选择组件这一步。默认会勾选 Git Bash Here 和 Git GUI Here这两个建议保留在资源管理器空白处右键就能快速打开 Git Bash后续很多命令行操作都要用到。第二个是 Choosing the default editor选择默认编辑器。默认是 Vim对新手来说 Vim 的操作逻辑过于反直觉。建议在这里选 Use Visual Studio Code as Gits default editor前提是你装过 VS Code如果没装就选 Notepad记事本也不会影响主流程反正 PyCharm 里不太需要手动走命令行编辑器。还有一个容易忽略的选项是 Adjusting your PATH environment调整 PATH 环境变量。默认选项 Git from the command line and also from 3rd-party software 会帮你把 Git 的路径加入到系统 PATH 中。当你看到 PyCharm 提示找不到 Git 的可执行文件时八成是这一步没有选对。一路 Next 到底等到 Configuring the line ending conversions 这一步保持默认的 Checkout Windows-style, commit Unix-style line endings 就好。这是为跨平台协作准备的以后你写的代码如果在 Windows 和 Linux 之间来回跑这个默认配置能减少换行符导致的乱码问题。2.3 安装完成后验证 全局身份配置装完之后先别急着打开 PyCharm先在命令行里验一下 Git 本体是否安装成功。按下Win R输入cmd或者直接打开 Windows Terminal敲下面这个命令git --version正常情况下你会看到类似git version 2.40.0的输出这就说明 Git 核心程序已经装好了。如果你输入命令之后提示 git 不是内部或外部命令那说明 PATH 没有配置成功最常见的原因就是安装时 PATH 那一步选错了。这种情况的处理方法我放在第 6 部分详细讲你先继续往下走。接下来配置全局身份。为什么需要这一步因为 Git 每一次提交代码都会自动记录作者信息也就是提交记录上显示的那一行 Author: 你的名字 你的邮箱。远程仓库也会拿这个信息来标记是谁推送的代码。在刚才的命令行窗口里依次输入两行命令git config --global user.name 你的名字 git config --global user.email 你的邮箱这里填的名字和邮箱不需要和代码托管平台注册时完全一致但强烈建议保持一致。因为 Gitee 或 GitHub 在判断提交者身份时主要看提交邮箱能不能匹配上你账号里的邮箱匹配不上你的提交记录在平台上就不会正确显示成你的头像。验证是否写进去可以再敲git config --global --list输出里会列出你刚设置的 name 和 email这就代表全局配置生效了。注意--global参数表示全局生效也就是说这台电脑所有的 Git 仓库都会使用这个身份。如果你同一台电脑上有多个账号那需要去掉--global在每个仓库里单独配置。新手阶段用全局配置就够了。3. PyCharm 里完成 Git 配置让 IDE 认识 Git3.1 在 Settings 里绑定 Git 路径打开 PyCharm进入设置页面。Windows 用户在菜单栏选File - SettingsMac 用户是PyCharm - Preferences。在设置窗口左上角的搜索框里直接输入 Git搜索结果里会出现Version Control - Git这一个条目点进去。右侧页面会有一个 Path to Git executableGit 可执行文件路径的输入框。正常情况下 PyCharm 会自动检测到 Git 安装路径比如C:\Program Files\Git\bin\git.exe。如果这个框是红色的或者旁边有个红色的提示说明没有自动检测到你需要手动点击右侧的...按钮去选择git.exe这个文件。我个人的经验是先在资源管理器里找到 Git 的安装目录确认git.exe存在再把路径填进去成功率最高。填好之后点击右侧的 Test测试按钮。如果路径正确会弹出一个显示 Git 版本号的窗口比如Git version is 2.40.0。看到这个提示就说明 PyCharm 已经正式认识 Git 了。3.2 检查集成设置避免误操作在同一个设置页面的下方还有一个下拉框 Update method更新方式默认是 Merge保持默认即可。旁边有个复选框 Auto-add files on commit提交时自动添加文件建议勾选上这样你提交时 PyCharm 会自动把新增的文件纳入版本控制不会漏掉。再往下翻是 SSH executableSSH 执行程序这里默认选内置的 Built-in 就好。PyCharm 自带 SSH 客户端不需要调用系统里的 OpenSSH避免路径冲突。在设置页面左侧再点开Version Control - Confirmation确认这里控制各种操作之前是否需要弹窗确认。新手建议把 When files are created, add them to VCS automatically新建文件时自动加入版本控制和 When files are deleted, remove them from VCS automatically删除文件时自动移出版本控制都选成 Show options before adding/removing操作前询问多一次确认就少一次误操作。等你熟悉了再改成全自动。3.3 一个小建议先确认仓库识别状态配置好 Git 之后你当前打开的项目可能还没有被 Git 管理PyCharm 里的文件会显示成普通文件的样式。怎么判断一个项目是否已经处于 Git 管理之下看文件名的颜色。一旦项目被 Git 接管未跟踪的文件通常会显示成棕红色已跟踪且未修改的文件是绿色或白色每个文件旁边还会显示版本状态。如果你打开的是一个已经带.git文件夹的项目PyCharm 会自动识别并切换到 Git 模式。右上角或底部状态栏会出现分支名文件的颜色也会跟着变化。如果这些都没有出现说明当前项目还只是一个普通的本地文件夹需要走第 5 部分的本地初始化或关联流程。4. 创建远程仓库并配置 SSH 免密认证4.1 在 Gitee / GitHub 上创建空白仓库代码托管平台你选哪个都行。国内推荐 Gitee因为服务器在国内上传下载速度快界面也是全中文对新手友好度最高GitHub 则更国际化开源氛围更浓。两个平台的创建流程基本一样这里以 Gitee 为例。登录 Gitee 之后点击页面右上角的 号选择 新建仓库New Repository。你会看到一个仓库设置表单需要填写的信息按下面的建议来仓库名称填一个简短、能描述项目用途的名字比如my-first-project。仓库名会直接体现在远程地址里不要用中文和空格。是否开源选 私有Private或 公开Public都可以。新手阶段建议选 私有防止代码内容被陌生人看到反正是你自己的练习不需要公开。初始化仓库这里可以勾选 使用 Readme 文件初始化这个仓库也可以不勾。如果你本地已经有项目了就不用勾选任何初始化选项比如 .gitignore、许可证因为一旦勾选远程仓库里就会多出一些文件你本地推上去的时候就可能出现冲突。新手建议远程仓库保持完全空白。创建完成后仓库主页面会显示一个远程地址。通常有两种形式HTTPS 地址https://gitee.com/你的用户名/仓库名.git以及 SSH 地址gitgitee.com:你的用户名/仓库名.git。这个地址在后面的推送流程中要用到。4.2 生成 SSH 密钥并配置到平台为什么要配 SSH 密钥因为用 HTTPS 推送代码时每次都要输入账号密码而且现在很多平台已经不支持直接用密码推送代码了要求用个人访问令牌Personal Access Token替代密码。对新手来说这个流程比较绕。相比之下SSH 密钥方式配置一次之后永久免密体验好很多。打开 Git Bash在任意文件夹空白处右键 - Git Bash Here输入下面的命令ssh-keygen -t ed25519 -C 你的注册邮箱这里的ed25519是目前推荐的加密算法兼容性也很好。回车之后会提示你保存路径默认是~/.ssh/id_ed25519直接回车即可。紧接着会提示输入 passphrase密码短语如果你想二次加密可以设置但新手阶段直接按两次回车保持空密码操作起来最省事。命令执行完毕后找到生成的公钥文件。Windows 用户在C:\Users\你的用户名\.ssh\目录下会看到两个文件id_ed25519私钥绝对不能泄露和id_ed25519.pub公钥。用记事本打开.pub结尾的文件里面的全部内容就是你的公钥。复制这一整段内容。回到 Gitee点击头像进入设置页面在左侧菜单里找到 SSH 公钥 或 安全设置 下的 SSH Keys点击添加公钥。标题随便填内容框粘贴你刚复制的公钥点击确定。输入一次登录密码验证身份就配置完成了。验证一下是否成功。回到 Git Bash 里输入ssh -T gitgitee.com如果配置成功会返回一段欢迎信息。注意这里如果提示 Are you sure you want to continue connecting输入yes回车即可这是第一次连接服务端时的指纹确认环节。4.3 为什么坚持建议用 SSH 而不是 HTTPS我和很多新手交流时发现他们配 HTTPS 也挺顺利但用不了几天就会回来问为什么我 push 的时候明明输入了账号密码还是说认证失败原因前面提过现在主流代码托管平台都逐步取消了纯密码认证要求使用个人访问令牌。你第一次输入用户名密码可能是在浏览器里登录的状态到了 Git 这里它不认识你的 token就会一直报错。而 SSH 方式的核心思路是一把钥匙配一把锁公钥存到平台上私钥留在本地电脑验证过程全自动不需要二次输入。配置一次之后你在 PyCharm 里的所有推送拉取操作都会变得很干净。5. 从零到一完整上传流程实操5.1 方式 A通过 PyCharm 直接克隆远程仓库开发这个方式适合 远程仓库已经存在、本地没有代码 的情况。在 PyCharm 的欢迎界面选择 Get from VCS从版本控制获取。如果你已经在项目窗口里通过File - New - Project from Version Control也能打开同样的界面。在 URL 输入框里粘贴刚才从远程仓库复制的 SSH 地址Directory 里选择你想要保存项目的本地路径点击 Clone 就会开始克隆。克隆完成后 PyCharm 会自动打开这个项目右下角可以看到当前分支名默认是main或master。从这一刻起这个项目就完全处于 Git 管理之下了你新建的任何文件PyCharm 都会自动标识状态。之后你的开发流程就变成写代码 - 右键点击项目目录 -Git - Commit Directory- 勾选要提交的文件 - 填写提交信息 - 点击 Commit - 再点击Git - Push- 选择远程分支 - 确认推送。整个流程完全是图形化操作。5.2 方式 B已有本地项目关联到新仓库这是最最常见的场景。你本地已经有一堆代码文件也许已经写了好几天现在想赶紧传到远程仓库备份。按照下面步骤来第一步在 PyCharm 里手动初始化 Git。点击顶部菜单VCS - Enable Version Control Integration在弹出的窗口里选择 Git点击 OK。此时项目底部会多出一个 Git 工具栏说明本地仓库已经建立。第二步把远程地址关联到本地仓库。这一步在 PyCharm 里有两种方式。一种是通过Git - Manage Remotes...打开远程仓库管理窗口点击加号添加。此时会让你填 Name默认 origin和 URL粘贴你远程仓库的 SSH 地址填完点 OK 保存。另一种方式是直接在 PyCharm 的 Terminal 里敲命令git remote add origin gitgitee.com:你的用户名/你的仓库名.git这两种方式效果完全一样。关联好之后你的本地仓库就已经有了一个名为origin的远程目标。第三步是最容易被新手忽略的动作拉取远程仓库内容或者说同步基线。前面提到过如果远程仓库是空白的这一步可以跳过。如果远程仓库已经有文件比如你勾选了初始化 Readme就需要先在 PyCharm 里执行Git - Pull把远程的main分支拉下来和本地合并否则直接推送会被拒绝。5.3 add / commit / push 的图形化操作完整拆解现在说说最核心的三个动作add添加到暂存区、commit提交到本地仓库、push推送到远程仓库。在 PyCharm 里这三个动作合在一起就是一次完整的 推送流水线。Add的时机是你新建了一个文件或者修改了一个文件PyCharm 里文件的颜色会变化。要让 Git 开始跟踪这个文件的改动需要把它加到暂存区。在 PyCharm 里这个动作通常在你 commit 的时候自动完成。你打开Git - Commit快捷键CtrlK或 Windows 下直接按CtrlK左侧会列出所有变更文件未跟踪的新文件会显示在 Unversioned Files 分组下。你只需要勾选要提交的文件PyCharm 会自动完成 add 这一步。如果你在设置里勾选了 Auto-add files on commit那未跟踪文件也会在你提交时被自动添加。Commit的时机是你想给当前这一批改动拍一张快照。按下CtrlK会打开提交窗口。提交窗口上半部分是要提交的文件清单下半部分是一个消息输入框。消息要填写清楚这次改了什么比如feat: 添加登录功能英文中文都可以关键是语义清晰。填完之后点击灰色按钮 Commit 或者 Commit and Push。Commit 只是在本地完成记录Commit and Push 则会直接进入推送步骤。Push的时机本地已经 commit 成功想同步到远程。点击Git - Push快捷键CtrlShiftK。PyCharm 会弹出推送窗口展示本次将推送的 commit、目标仓库和分支信息。点击 Push 按钮后如果配置正确且 SSH 密钥有效十几秒内就能看到推送成功的提示。我来放一张各按钮位置的文字示意方便你在 PyCharm 里对照着找打开的提交窗口右下角有两个按钮一个叫 Commit一个叫 Commit and Push菜单栏Git下拉菜单里Push 在 Commit 的正下方文件右键菜单里有一个 Git 子菜单里面所有操作都有。这算是我给你的一份 找不到按钮时的快捷目录。5.4 图形化操作与命令行操作的对照我在教新手的时候不主张完全放弃命令行。因为你在网上搜资料、看报错信息、或者和 AI 工具交流时大量问题描述都是命令行形式的。你能看懂命令行排错能力立刻上一个台阶。下面这张表格是我认为 PyCharm 图形化操作与命令行最核心的对应关系操作场景PyCharm 图形化操作等价命令行初始化仓库VCS - Enable Version Control Integrationgit init查看变更文件项目文件颜色、Git - Commit窗口git status提交到本地Git - Commit勾选文件填消息git add .加git commit -m 消息推送远程Git - Pushgit push origin main拉取远程Git - Pullgit pull origin main查看提交历史Git - Show Historygit log --oneline切换分支右下角分支列表点击切换git checkout 分支名建议你把这张表收藏起来图形化操作出问题时切到 Terminal 敲一下对应的命令看看具体报什么错再回来查解决方法。两边结合着用是新手往熟练工过渡最快的路径。6. 新手最容易踩的坑常见问题与排查技巧6.1 报错 git 不是内部或外部命令这个报错出现过无数次情况也很统一Git 已经装好了但是 PyCharm 里配置 Git 路径时找不到文件或者终端里敲git -v没反应。根源就是系统 PATH 环境变量里没有 Git 的路径。处理方式手动把 Git 的bin目录和cmd目录加进系统环境变量。Windows 系统搜索 编辑系统环境变量点 环境变量在下方的系统变量里找到Path点编辑新增两行C:\Program Files\Git\bin和C:\Program Files\Git\cmd。如果安装时改了目录就按照实际安装路径来。添加完成后重启 PyCharm 和终端问题就能解决。如果在 PyCharm 的 Settings 里手动指定路径也建议直接定位到git.exe所在的完整路径。PyCharm 对路径的解析没那么智能给它一个绝对路径最稳妥。6.2 Push rejected 和 Failed to push some refs推送被拒绝是最打击新手自信心的报错之一。报错信息通常是! [rejected] main - main (fetch first) error: failed to push some refs这个报错的原因几乎只有一种远程仓库里存在你本地没有的提交记录。比如你在创建仓库时初始化了 Readme或者团队里的其他人在同一个分支上推送过代码而你的本地仓库还没有拉取这些记录。Git 为了安全起见拒绝了你直接覆盖远程的操作。解决方法打开 PyCharm 的Git - Pull把远程代码拉下来。如果没有冲突拉下来之后自动合并成功再点 Push 就能推上去。如果拉取后提示有冲突PyCharm 会弹出冲突解决窗口左边是本地版本右边是远程版本下方是合并结果区域。手动保留你需要的代码行点 Apply 应用解决。我曾经带过一个学员连写了三周代码从来没有 pull 过。结果他所在的小组另一个成员提前推送了几行配置代码他推送的时候反复被拒差点想删了仓库重来。实际上只要做一步git pull那个困扰他一个多小时的问题就解决了。6.3 身份认证失败 / Permission denied (publickey)推送时如果提示Permission denied (publickey)大概率是 SSH 密钥配置出了问题。逐个排查下面几个点第一确认公钥有没有复制完整。公钥通常以ssh-ed25519开头前面不能有空格结尾不要带换行符。复制的时候用记事本打开全选复制粘贴到平台文本框时不要手输。第二确认密钥是不是放在默认位置。如果你生成密钥时改了保存路径PyCharm 不会自动识别需要通过ssh-add命令把私钥加到 SSH agent 里或者在你自定义的位置配置~/.ssh/config。新手建议直接默认路径。第三确认私钥权限是否正确。Windows 上私钥文件如果权限太开放会触发安全策略导致连接失败。你可以打开.ssh目录右键id_ed25519文件 - 属性 - 安全把除了当前用户之外的所有权限项都删掉只保留自己的读写权限。每次改完配置后在终端里重新执行ssh -T gitgitee.com验证。直到看到欢迎信息再回到 PyCharm 里推送。6.4 .gitignore 没配好把不该传的文件也传上去了细心的读者会发现创建仓库时平台会让你选 .gitignore 模板。如果你在远程仓库初始化时没选本地项目中也一直没有创建这个文件那么很容易在第一次推送时把一些本地环境相关的文件传上去比如 IDE 配置、虚拟环境目录、编译产物等。传上去之后这份污染会一直跟随仓库的历史记录清理起来很麻烦。正确做法是在第一次 commit 之前先在项目根目录创建.gitignore文件。PyCharm 里右键项目根目录 - New - File名称填.gitignore。文件里写入不需要托管的目录和文件比如 Python 项目至少要有下面这些__pycache__/ *.py[cod] .idea/ .vscode/ venv/ env/ .DS_Store当然具体写什么取决于你的项目类型。如果用的是 Gitee创建仓库时平台提供的 Python 模板就挺好用虽然它不会自动填充到已有本地项目里但你可以参考它的内容手动创建。有一点要特别注意.gitignore只对还没有被 Git 跟踪的文件生效。如果你在创建.gitignore之前已经 commit 过包含venv/的文件那么即使你后来在 .gitignore 里加了venv/Git 依然会继续跟踪它。这时候你是 允许 它被跟踪的状态需要执行一次移除操作才能生效命令是git rm -r --cached venv/这个命令的含义是把venv/从 Git 的记录中移除但保留本地文件。如果你在 PyCharm 里操作也可以通过文件右键 -Git - Remove并在弹窗里取消勾选 Delete locally 来达到同样效果。处理完之后 commit 一次后续的版本历史就不会再包含这个目录了。6.5 常见问题速查表我把新手阶段遇到频率最高的几个问题整理成了一张表你可以直接收藏。现象原因解决方法PyCharm 提示 Git is not installedGit 没装或路径没配置重新安装 Git在 Settings 里绑定 git.exe 路径命令行输入 git 提示不是内部命令PATH 环境变量缺失手动添加 Git 的 bin 和 cmd 目录到 PathPush 被拒绝远程有本地没有的提交先 Pull 再 PushPermission denied (publickey)SSH 密钥未生效或公钥粘贴错误重新生成密钥检查公钥内容配置到平台提交记录里头像不是自己全局用户名邮箱与平台不匹配用git config --global修改 name 和 email文件显示为红色/绿色/蓝色颜色代表各自 Git 跟踪状态红色未跟踪绿色已暂存蓝色已修改属正常情况改了代码之后发现撤回不了可能已经 commit 或 push通过Git - Show History查看版本记录找回每个问题的完整处理流程前面各个小节都已经展开了。你在排查时不需要一上来就全盘重来一步步定位问题出在哪一个环节再针对性处理比什么都快。最后说一点我自己的真实体会。我见过很多新手在配置环境这一关反复折腾最后放弃了 Git 或者干脆每次用网页手动上传文件。其实你只需要完整地走一次这个流程也就是把 Git 装好、密钥配好、pyCharm 里认出来、成功推送一次后面的操作基本就变成肌肉记忆了想忘都忘不掉。趁着刚读完这篇建议你现在就动手先建一个临时小程序项目按第 4 部分的流程配置好 SSH 密钥再回到第 5 部分用最笨的方式把代码推送到远程最后再看一眼第 6 部分的速查表。严格按照这个顺序走一遍大概率一次就能全部跑通。如果你在某个步骤卡住了欢迎带着具体报错信息再来看对应的小节。配置成功之后你会发现代码备份和版本管理这件事原来这么顺手。