直接说结论如果你已经装了 PyCharm但代码还停留在“本地能跑”的阶段没有备份到 Gitee 或 GitHub 这类远程仓库那这篇文章就是给你准备的。很多新手第一次在 PyCharm 里折腾 Git卡在的不是写代码而是“到底从哪儿开始”网上教程要么只讲命令行、要么只讲某一个小环节很少有人把“装 Git → 建仓库 → 配 PyCharm → 首次 Push → 日常操作”整条链路一次讲清楚。我写这篇的定位很明确不要求你懂底层原理不考虑你之前有没有用过终端跟着流程点鼠标就能完成第一次代码上传。核心场景就是“把 PyCharm 里的项目推送到远程仓库”同时把日常开发最常用的提交、更新、分支操作一起讲掉最后附上我实际踩过的坑。适合刚接触 Python、刚打开 PyCharm 还很迷茫的同学也适合想从“只会手动复制代码”升级到“用 Git 管代码”的人。1. 准备工作装好 Git建好远程仓库1.1 为什么用 PyCharm 管理 Git而不是只敲命令先说一个经常被忽略的点PyCharm 自己并不包含 Git它是一个 Git 客户端真正干活的还是你电脑上安装的 Git 程序。所以严格来说你需要做两件事安装 Git 本体然后在 PyCharm 里告诉它“你的 Git 在哪”。很多人问我是不是用命令行人更专业其实作为新手完全没必要有这种负担。PyCharm 的可视化操作用起来非常顺手它底层也是帮你执行命令但好处是不用记命令、不用怕打错文件状态、分支切换、冲突解决都有图形界面辅助。先把图形化操作跑通等有感觉了再去碰命令行这是我认为对新手最友好的路径。1.2 Windows 下安装 Git 的完整步骤如果你是 Mac 用户可以在终端输入brew install git或者直接装个 Xcode Command Line Tools。但考虑到大部分初学者用的是 Windows我重点讲 Windows 下 Git for Windows 的安装。打开 Git 官网下载页面下载对应系统版本的安装包。注意选 64 位版本。双击安装包一路点 Next。这里面有几个选项容易让新手迷糊我逐个说明Select Components默认即可不需要改动。Adjusting your PATH environment默认选第二项 “Git from the command line and also from 3rd-party software”保持默认就好。如果这里误选了第一项 “Use Git from Bash only”后期 PyCharm 有可能识别不到 Git。Choosing HTTPS transport backend保持默认的 “Use the native Windows Secure Channel library”不用改。Configuring the line ending conversions默认选第一项Checkout Windows-style, commit Unix-style line endings这个对大多数人最稳妥尤其项目里如果还有其他人使用不同系统能避免很多换行符引发的奇怪问题。安装完成后按Win R输入cmd打开命令行输入git --version如果能输出类似git version 2.40.0.windows.1说明安装成功。如果提示“不是内部或外部命令”大概率是刚才 PATH 那个选项没选对重新走一遍安装流程即可。设置 Git 全局身份信息这一步很多人容易忽略但如果不做后面 commit 的时候 Git 会一直抱怨不知道“你是谁”或者弹窗提示你补填信息。在命令行里执行git config --global user.name 你的名字 git config --global user.email 你的邮箱这里填入的名字和邮箱不一定非得和 Gitee/GitHub 注册信息一模一样但建议保持一致这样代码提交之后仓库里的贡献记录能正确关联到你的账号。可以使用拼音无所谓。1.3 在 Gitee 上创建远程仓库远程仓库我以 Gitee 为例原因很简单国内访问速度快、界面中文、功能对新手足够而且代码托管平台的操作逻辑和 GitHub 高度一致。你熟练之后切换到 GitHub 是无缝衔接的。注册并登录 Gitee 后点击右上角的“新建仓库”进入仓库信息页面。有几项配置需要重点留意仓库名称建议写英文比如my-first-project。仓库名称会出现在远程地址里用英文和短横线最安全别用中文和空格。路径你填的仓库名称会自动生成路径一般不用管。是否开源私有仓库仅自己可见公开仓库所有人可见。新手只是自己同步代码选“私有”就行以后想开放再改。初始化仓库如果你是完全新开始的项目建议不要勾选“使用 Readme 文件初始化这个仓库”也不要添加 .gitignore 和开源许可证。因为你在本地已经有代码了远程创建了一个带初始提交的空仓库第一次 push 时很容易出现两边历史不相关的问题虽然能强制推送但没必要给自己添麻烦。让 Gitee 先创建一个完全空的仓库后面操作最顺。创建完成之后页面上会出现仓库地址一个 HTTPS 协议地址一个 SSH 协议地址形如https://gitee.com/你的用户名/my-first-project.git gitgitee.com:你的用户名/my-first-project.git这两个地址需要记住后面 PyCharm 里连接远程仓库时要用到。2. 在 PyCharm 里完成 Git 配置与本地仓库初始化2.1 让 PyCharm 找到 Git打开你写代码的项目进入顶部菜单栏File → SettingsMac 上是PyCharm → Preferences在弹出的设置窗口中左边目录找到Version Control → Git。这里有一个Path to Git executable输入框正常情况下 PyCharm 会自动检测到 Git 的安装路径比如C:\Program Files\Git\bin\git.exe。点击输入框右侧的Test按钮如果弹窗显示 “Git executed successfully”说明关联成功。如果没有自动识别就手动点击文件夹图标找到刚才安装 Git 的目录。如果你忘了装在哪可以在命令行输入where git看到完整路径。这里再强调一遍如果这一步一直失败检查重点就在 1.2 里说的 PATH 选项重装 Git 时选择第二项基本都能解决。2.2 初始化本地仓库别急着点 VCS很多教程上来就叫你直接点VCS → Enable Version Control Integration但新手容易忽略一个细节PyCharm 本身对 Git 风格的操作有个概念叫 “VCSVersion Control System”虽然菜单写的是 VCS但选项里选 Git 就行。点击VCS → Enable Version Control Integration弹窗里选择Git然后确认。完成之后你的项目文件会立刻出现颜色变化红色表示未跟踪文件还没被 Git 管理绿色表示新增文件已加入版本控制但还没提交蓝色表示修改过的文件。如果你的项目没有任何颜色变化那多半是初始化失败了回到 2.1 重新检查 Git 路径。这一步骤的本质是告诉 Git “这个文件夹是我的仓库”之后你在 PyCharm 里做的所有提交操作都会记录在这个文件夹下隐藏的.git目录里。注意不要把项目到处移动位置.git目录和项目文件是绑定在一起的移动或者改名不会出大问题但有可能影响 IDE 的识别。2.3 先写好 .gitignore和提交规则打招呼正式第一次提交之前有一件事我建议新手先做——创建.gitignore文件。这个文件的本质是告诉 Git“哪些文件我不准备交给远程仓库你直接无视它们。”为什么需要它因为一个 PyCharm 项目里除了你自己的代码还有大量 IDE 自动生成的配置文件和中间产物.idea/PyCharm 自己的工程配置目录里面是你的编辑器偏好、运行配置等这种东西每个开发者的电脑可能都不一样推到仓库纯属制造噪音。__pycache__/Python 运行时会生成缓存文件完全没必要提交又快又容易产生冲突。venv/或.venv/虚拟环境目录体积巨大别人克隆你的项目后需要自己创建环境。*.pycPython 编译缓存。在项目根目录下新建文件命名为.gitignore注意它没有文件名前缀就是点开头的。文件内容可以参考.idea/ __pycache__/ venv/ .venv/ *.pyc .DS_Store创建之后你会发现 PyCharm 对这些文件的状态标识立刻发生了变化比如之前红色的.idea文件夹现在可能直接变成灰色表示已被忽略。这个文件本身则会显示为未跟踪的待添加文件它也应该提交到仓库。顺便说一句如果你创建远程仓库的时候用的是 Gitee 自动初始化的模板它可能会自带一份巨长的 .gitignore但未必匹配你的技术栈自己创建反而更可控。3. 第一次从 PyCharm 推送到远程仓库3.1 添加远程地址HTTPS 还是 SSH现在进入核心环节。在 PyCharm 顶部菜单栏点击Git → Manage Remotes...弹窗里可以看到远程仓库列表一开始是空的。点击加号输入名字originURL 框里粘贴你之前在 Gitee 复制的仓库地址。这里要决定是走 HTTPS 还是 SSHHTTPS 地址新手最容易上手输入账号密码或者私人令牌即可。缺点是每次 push/pull 都要认证除非你额外配置缓存否则挺烦。SSH 地址只要配置一次密钥之后就不需要反复输密码了体验更顺。但首次配置密钥对新手来说多几个步骤。我的建议是第一次用它先体验完整流程直接用 HTTPS 地址。等到“提交—推送”的链路走通了再回头升级 SSH。3.2 如果你想用 SSH密钥生成与添加如果你决定一步到位用 SSH步骤如下。先在命令行执行ssh-keygen -t rsa -b 4096 -C 你的邮箱一路回车即可它会生成两个文件私钥id_rsa和公钥id_rsa.pub默认存放在用户目录下的.ssh文件夹里。私钥自己留着公钥需要交给代码托管平台。进入 Gitee 的“个人设置 → SSH 公钥”把.ssh目录里id_rsa.pub文件的内容完整复制粘贴进去标题随意。之后在 PyCharm 的远程地址里填 SSH 格式的地址第一次连接时如果提示是否信任主机选择 yes 即可。之后推送就不再需要输入账号密码了。3.3 Commit 和 Push 到底先点哪个这是新手最容易困惑的地方Commit 和 Push 是两个不同的动作。Commit把文件保存到本地仓库相当于给自己做一个“存档”只存在你的电脑里。Push把本地存档同步到远程仓库别人才能看到才算真正的备份。在 PyCharm 右侧工具窗口栏找到Commit窗口一般在左侧图标像一个对勾。打开后你会看到所有待提交文件默认全部打勾。第一次提交前检查一下有没有不该提交的垃圾文件比如.idea目录或__pycache__。如果你在 2.3 写了. gitignore它们不会出现在这里。在 Commit Message 输入框里写清楚这次改了什么。我第一次写的是init project简单明了。然后有两种选择点击Commit按钮只提交到本地。点击Commit and Push...按钮提交完直接进入推送弹窗。新手第一次操作可以直接点Commit and Push...一气呵成。如果点的是Commit后续需要再点击右上角的向上箭头图标Push或者菜单栏Git → Push。Push 弹窗里会显示要推送的分支和远程目标保持默认。点击Push按钮后如果是 HTTPS 地址会弹窗让你输入 Gitee 的用户名和密码如果一直弹出“认证失败”看下一部分大概率是密码输入问题。看到底部出现黑色的Push successful提示第一次推送就算完成了。3.4 刷新远程仓库确认代码上传成功推送完成之后回到 Gitee 的仓库页面刷新浏览器。正常情况下你会在文件列表里看到和本地一致的文件结构包括你的.gitignore。如果只显示.gitignore没有代码文件说明你刚才 Commit 时没有勾选 Python 文件回到 PyCharm 重新检查提交内容。有同学问过我远程仓库显示一堆“提交记录”是什么意思简单理解就是 Git 记录了你每次提交的快照信息点击进去可以看到这次提交改动了哪些文件。这个能力在你以后回滚代码、排查 bug 时非常有用所以 commit message 尽量写得有意义。4. 日常开发中的 Git 操作节奏4.1 Commit Message 怎么写才不算白写先说说提交信息这是我在 code review 时最看重的东西之一。新手常见的提交信息长这样update、修改、bug修复、123。说实话这些写完一个月后你自己都看不懂当时改了什么更别说合作者了。一个简单实用的格式是类型: 简述内容。比如feat: 添加用户登录接口 fix: 修复列表页加载超时问题 docs: 更新 README 使用说明 refactor: 重构订单状态判断逻辑其中feat表示新功能fix表示修 bugdocs表示文档变化refactor表示代码重构但不影响功能。这套规范叫 Conventional Commits很多团队直接沿用。新手就算不弄这么正式至少养成“每次提交只做一件小事写清楚做完了什么”的习惯。有了这个习惯你的提交记录就像一本清晰的开发日志哪天某个功能出了问题可以快速定位到是哪一次改动引入的。4.2 Pull 和 Push先拉后推避免冲突在你用 Git 管理代码一段时间后会遇到一个经典场景你在本地改了代码正准备推送结果 PyCharm 弹出一行红色提示Push rejected。原因是远程仓库里有你本地没有的记录——很可能是你在另一台电脑上提交过或者别人也推了代码。这时候不要慌也不要尝试去强制推送。先执行 Pull拉取。在 PyCharm 顶部Git → Pull把远程最新的提交拉下来。如果没有冲突它会被自动合并到你的本地代码里然后你再正常 Push 就成功了。如果出现冲突PyCharm 会弹出一个冲突解决界面左边是远程版本右边是本地版本中间是合并结果。你需要逐行决定保留哪边可以保留当前改动可以接受远程改动也可以手动编辑。新手看到冲突界面容易发怵其实没那么可怕冲突文件往往很少而且界面很直观。不过我有个经验建议在可能多人协作的项目里推送之前养成先 Pull 再 Push 的习惯能少掉八十%的冲突。4.3 分支别把所有改动都堆在主线上在 PyCharm 右下角可以看到当前分支名默认是main或master。点击它选择New Branch输入一个分支名字比如feature-login当前项目就会切换到新分支。之后你的所有提交都在这个分支上进行不会影响主线。为什么需要这个因为你在开发新功能时代码往往是半成品如果直接在主线上提交后续主线可能一直处于不可运行的状态。开一个功能分支把实验性改动都放进去等功能稳定之后再合并回主线这是一种非常健康的开发节奏。合并操作也不复杂先切换到目标分支比如主分支点击Git → Merge…选择你要合并进来的分支即可。如果没冲突一键完成。4.4 文件颜色代表的状态值得记住PyCharm 里文件颜色的变化是最直观的提示我建议新手先把它当成一种“第六感”来训练红色文件还没有被 Git 跟踪也就是新建之后还没 add 过。绿色文件已经处于暂存区等待提交。蓝色文件已被跟踪并且当前内容和上一次提交不同。灰色路径被 .gitignore 忽略。看到这些颜色你基本不用敲命令也能知道项目当前处于什么阶段。如果你改了某个文件但它一直没变蓝色检查一下是不是被其他窗口覆盖了PyCharm 默认是自动刷新的但偶尔需要File → Reload All from Disk强制刷新一次。4.5 克隆项目换电脑后怎么把代码拉下来假如你换了一台电脑或者想在公司电脑上继续写家里没写完的代码。这时候不用从头创建项目直接点 PyCharm 首页的Get from VCS版本控制系统获取选择 Git粘贴远程仓库地址选择本地保存路径点击 Clone 即可。克隆和推送是逆操作Clone是把远程仓库复制到本地Push是把本地改动送回远程。克隆时如果仓库是私有仓库同样需要认证HTTPS 输入账号密码/令牌SSH 则要求新电脑也配置了相同的私钥。5. 新手最常遇到的 5 个坑和排查方法5.1 Push rejected: Failed to push some refs这个报错出现的频率最高本质是远程和本地存在分叉。很多人的第一反应是不知道怎么处理甚至有人去搜索“强制推送”这非常危险会有覆盖线上代码的风险。正确做法是先Git → Pull让本地合并远程的改动再 Push。如果 Pull 时提示要写合并信息默认保存退出即可。5.2 Authentication failed 认证失败这个问题在 GitHub 上最典型因为在 GitHub 上已经不支持用账号密码直接 Push 了必须用 Personal Access Token个人访问令牌代替密码。Gitee 也陆续开启了类似的限制某些仓库要求使用私人令牌。解决办法去 Gitee 的“个人设置 → 私人令牌”生成一个新令牌复制这串字符串在 PyCharm 弹出密码输入框时粘贴令牌而不是注册密码。注意令牌只显示一次忘了就重新生成。如果你之前填错了PyCharm 会在Settings → Appearance Behavior → System Settings → Passwords里保存了旧的认证信息删除或清理后再试。5.3 Couldnt find Git installed这类提示一般是 PyCharm 找不到 Git 程序。检查一下 Git 是否真的安装了如果安装了但 PyCharm 还是提示就在Settings → Version Control → Git里手动指定 git.exe 路径。如果路径正确但仍然失败试试重启 PyCharm。重置大法在这里真的管用。5.4 fatal: detected dubious ownership in repository这个报错在 Windows 上偶发原因是 Git 认为当前目录的所有权和当前用户对不上它怀疑你可能被引导访问了别人的仓库。解决办法是在命令行里执行git config --global --add safe.directory *这是“信任该目录”的意思。如果等级更严重可以先检查这个目录是不是你自己创建的文件来源没有问题再添加信任。5.5 远程分支名和本地分支名对不上我见过不少新手在推送时右下角提示本地分支是master但远程仓库默认主分支叫main。推送时 PyCharm 弹窗里会自动匹配如果你点错选项可能推不上去。简单处理方法推送弹窗中手动把远程分支改成origin main或者在本地执行分支重命名git branch -m master main然后重新推送。这个坑我觉得值得提一下因为它不是代码错误纯粹是“分支命名习惯不一致”引发的。5.6 push 成功后代码在网站上不显示大概率是浏览器缓存没刷新因为 Gitee 页面不会自动实时更新尤其是文件列表页。强制刷新页面比如Ctrl F5基本就能看到。如果一直不显示回到 PyCharm 检查推送输出日志里是否真的成功别被“部分文件没推送成功”这种假象骗了。写在最后踩过几次坑之后我最大的体会是Git 难的不是命令而是概念——提交、分支、远程、本地这些心智模型一旦在脑子里串起来了剩下的一切都是查工具和练习。而 PyCharm 作为图形化客户端非常适合新手建立这种模型因为你能直观看到文件状态变化、分支切换、冲突合并的过程。我建议新手不要一上来就把所有功能都试一遍只做一件事把代码提交到远程仓库然后每天写完之后养成Commit and Push的习惯。这个习惯坚持两周你自然会感受到版本管理带来的安全感——代码不会轻易丢改坏了能回滚想开新思路就开分支。之后再去碰命令行、写高级玩法那都是水到渠成的事。