把 PyCharm 里的项目传到 GitHub 上是我见过新手操作里最容易被细节卡住的事。不是你不会写代码而是整个过程被拆成了装 Git、配账号、建仓库、提交、推送这几个环节哪一步断了都走不下去。而且网上不少教程上来就是git init、git add一串命令行很多人看着就头大。其实在 PyCharm 里这些操作都有对应的图形界面入口鼠标点一点就能完成。这篇文章就是专门给第一次用 PyCharm 往 GitHub 传项目的人写的。我会按实际操作顺序把从安装 Git、登录 GitHub 账号、建立本地仓库、创建远程仓库再到推送成功的完整流程捋一遍。每一步都会说清楚点什么菜单、填什么内容、遇到什么报错该怎么处理。这篇文章用的是图文对应的描述方式你打开 PyCharm 对照着一步步看基本不会迷路。看完之后你不仅能顺利把项目传上去以后日常改代码、同步更新的流程也能一起搞定。1. 准备工作先把三样东西备齐在开始点任何按钮之前先把环境确认好。大多数人在 PyCharm 里折腾半天传不上去不是因为操作不对而是基础环境少了东西或者版本不对。这里我按顺序列一下你必须准备好的三样东西。1.1 安装 Git版本管理的地基PyCharm 本身不自带 Git 功能它只是把 Git 的命令封装成了图形界面。就好比 PyCharm 是个遥控器真正干活的是 Git 这个“电视盒子”。所以第一步是确保电脑上已经装了 Git。Windows 用户去 Git 官网下载安装包下载后一路 Next 安装即可。有一个地方需要留意安装过程中会问是否把 Git 加入系统 PATH一般默认选项已经勾上了保持默认就行。如果你当初安装时取消了这个选项PyCharm 会找不到 Git 程序后面配置时会很麻烦。macOS 用户一般自带 Git或者装 Xcode Command Line Tools 时会给装上。装好后打开终端Windows 是 CMD 或 PowerShell输入git --version如果能看到类似git version 2.39.2.windows.1的输出说明 Git 已经就绪。看不到的话检查安装步骤或者重启一下电脑。我见过不少人是装完 Git 忘了重启结果 PyCharm 怎么都识别不到重启一次就好了。1.2 注册 GitHub 账号并准备访问令牌GitHub 是代码托管的平台相当于给项目找了个云端的“家”。你需要先注册一个账号这个不用多说。但这里有个非常关键的细节现在 GitHub 已经不再支持用账号密码直接做 Git 操作了推送代码时需要用 Personal Access Token个人访问令牌来当密码用或者配置 SSH 密钥。很多新手在这里卡住是因为还在试图输入自己的 GitHub 登录密码结果怎么都是认证失败。这不是你记错了密码而是 GitHub 的规则变了。生成 Token 的路径是GitHub 网页右上角头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token。生成时勾选repo权限这是推送代码所必需的最小权限范围。Token 生成后只会显示一次务必先复制保存好关掉页面就再也看不到了。1.3 确认 PyCharm 版本与内置插件PyCharm 社区版免费和专业版都支持 Git 和 GitHub 集成不区分版本。打开 PyCharm 后进入 File → Settings → Plugins搜索 Git 和 GitHub 两个插件确保它们是启用状态。一般这两个插件默认就是启用的几乎不用手动操作。但如果你的 PyCharm 是某些精简版或者非官方渠道下载的插件可能被阉割了那就需要先在这里补上。到这里准备工作就齐了。接下来要做的是把 PyCharm 和 GitHub 账号连接起来。2. 在 PyCharm 里完成 Git 和 GitHub 配置很多人以为装完 Git、注册完账号就可以直接用了其实中间还差一步“搭桥”。这一步是在 PyCharm 里告诉它你的 Git 程序在哪、你的 GitHub 账号是谁。配置完成后PyCharm 和 GitHub 才算真正连上。2.1 指定 Git 可执行文件路径打开 PyCharm 的设置界面Windows 是 File → SettingsmacOS 是 PyCharm → Preferences在搜索框输入 Git进入 Version Control → Git 页面。右侧第一项就是 Path to Git executable也就是 Git 可执行文件的路径。如果安装 Git 时勾选了加入 PATHPyCharm 一般会自动识别到路径。如果没有自动识别点击旁边的文件夹图标手动找。Windows 上常见的安装路径是C:\Program Files\Git\bin\git.exe。选好之后点击 Test 按钮PyCharm 会弹窗显示 Git 版本信息看到版本号就说明路径没问题。这一步经常被忽略但非常关键。之前遇到一个朋友Git 装了账号也注册了就是在 PyCharm 里一直报找不到 Git最后发现是他安装时手动改了安装目录PyCharm 默认路径找不到。手动指定一下就解决了。2.2 关联 GitHub 账号用 Token 登录同样在 Version Control 设置页面切换到 GitHub 选项卡。点击 Add account选择 Use Token 方式。把刚才保存的 Token 粘贴进去点击 Add 即可。添加成功后当前账号的显示名会出现在列表里。选 Token 而不是密码登录这里再强调一下原因GitHub 在 2021 年 8 月之后就彻底废除了密码认证的 Git 操作方式现在唯一支持 HTTPS 协议的方式就是 Token。Token 本质上是给 Git 操作单独发的“临时钥匙”你可以给不同类型的 Token 设置不同的权限范围用起来比密码更安全。如果 Token 过期了或者失效了推送代码时会报Authentication failed错误。解决办法很简单去 GitHub 后台重新生成一个 Token然后在 PyCharm 的 GitHub 设置里把旧账号删掉重新添加一次就好。2.3 配置本地身份信息还有一个容易忽略的地方提交代码时Git 需要用用户名和邮箱来标识“这次提交是谁做的”。如果没配置提交时可能报错或者提交成功后 GitHub 上显示的作者名字是乱的。你可以在 PyCharm 的终端Terminal 窗口PyCharm 自带里执行git config --global user.name 你的名字 git config --global user.email 你的邮箱--global表示全局生效即这台电脑上所有 Git 项目都默认使用这个身份。如果只想给当前项目单独设置身份去掉--global再执行一次即可。这里建议邮箱填 GitHub 注册邮箱这样提交记录能正确关联到你的 GitHub 账号上。身份配置是整个流程里最不起眼却又影响观感的一步。如果有人看到你的 GitHub 仓库提交记录里作者叫一堆乱码大概率就是漏了这一步。3. 本地仓库建立与第一次提交配置部分完成后才真正开始操作项目。这一步的目标是在你的项目目录里建立一个 Git 本地仓库并把当前代码做一次“快照”存档。快照这个动作在 Git 里叫 Commit是整个版本管理的核心操作。3.1 用 VCS 功能启用版本控制打开你准备上传的 PyCharm 项目。如果项目还没有任何版本控制信息PyCharm 顶部菜单栏会出现一个 VCS 入口。点击 VCS → Enable Version Control Integration弹窗里选择 Git点击 OK。操作完成后项目里的文件颜色会发生变化红棕色的文件表示这是新建的、未被 Git 跟踪的文件绿色表示新加入但还没提交的文件白色表示已提交过的文件。如果你之前从没接触过 Git看到文件变红不用慌这是正常状态代表 Git 已经接管了这个目录只是还没有把你当前的文件记录进版本历史。选 Git 而不是别的版本控制工具是因为 GitHub 本身是基于 Git 的两者是原生匹配。PyCharm 也支持 SVN 等方式但那跟 GitHub 没关系我们这里不需要。3.2 添加 .gitignore把垃圾文件挡在门外项目目录被 Git 接管之后有一个东西必须立刻处理那就是.gitignore文件。这个文件的作用是告诉 Git“忽略哪些文件”被忽略的文件不会进入版本控制更不会上传到 GitHub。以 Python 项目为例项目里通常会有venv或.venv虚拟环境目录、__pycache__缓存目录、.ideaPyCharm 的项目配置目录、.env环境变量文件等。这些文件有一个共同特点跟项目代码本身无关是本地环境的产物。如果你不把它们排除它们会被一起传上 GitHub轻则让仓库变得臃肿重则把本机路径、密钥等敏感信息暴露出去而且别人拉取你的项目后会因为路径差异直接跑不起来。在 PyCharm 里创建.gitignore文件非常方便右键项目根目录 → New → File文件名输入.gitignore然后写入常见内容。Python 项目可以参考下面的配置# 虚拟环境 venv/ .venv/ env/ # Python 缓存 __pycache__/ *.pyc *.pyo # IDE 配置 .idea/ .vscode/ # 环境变量与密钥 .env # 测试与构建产物 dist/ build/ *.egg-info/如果你用的是其他语言比如 Java忽略target/、Node.js忽略node_modules/方法完全一样只是忽略的文件名不同。这里多说一句为什么.gitignore这么重要。Git 的设计理念是记录“源码”而不是“产物”。虚拟环境里的依赖库本来就可以通过requirements.txt或Pipfile重新装回来node_modules也可以用package.json重新还原。把能再生的东西传上去相当于搬家的时候把垃圾袋也一起搬到了新家费空间不说还显得很业余。3.3 完成首次提交 Commit现在可以把代码提交到本地仓库了。右键项目根目录 → Git → Commit Directory或者直接在左侧项目文件上右键选择 Commit。PyCharm 会打开一个提交窗口上半部分是文件列表勾选你要提交的文件下半部分是 Commit Message提交信息输入框。提交信息是你给这次提交写的“备注”。新手阶段不用写得多花哨但一定要写清楚这次干了什么。常用的格式有两种一种是精简型直接写“新增用户登录接口”一种是带前缀的规范型比如feat: 新增用户登录接口feat表示新功能fix表示修复 bugdocs表示文档变更。这个习惯养成之后回头看历史版本会非常省力。点击 Commit 按钮后PyCharm 会把当前文件状态记录成一个快照。注意这一步是完全在本地完成的不会往 GitHub 上传任何东西。很多人以为点了 Commit 就等于传上去了直到打开 GitHub 发现空空如也这是对“本地提交”和“远程推送”两个概念没有区分。两者的关系可以这么理解Commit 是你在电脑上给代码拍了一张照片Push 才是把这张照片洗出来贴到 GitHub 上。如果没有配置 Git 身份点击 Commit 时会弹出警告提示没有设置 author 信息。按上一节说的先在终端里配置好 user.name 和 user.email再回来提交。4. 创建 GitHub 远程仓库并推送本地仓库建好、代码也提交了接下来这步就是把代码真正送到 GitHub 上。这里需要先在网页端创建一个远程仓库然后在 PyCharm 里把本地仓库和它关联起来最后执行推送操作。4.1 在 GitHub 网页端新建远程仓库打开 GitHub 网站并登录点击页面右上角的加号图标选择 New repository。仓库名称Repository name建议全小写、用连字符分隔单词比如my-python-project尽量避免空格或中文。描述Description可以填一句话说明项目是干什么的。创建页面底部有一项 “Initialize this repository with a README file”这里建议先不要勾选。原因是如果远程仓库已经有了 README而本地仓库还没有任何提交记录第一次推送可能会因为两边的历史不相关而报错需要额外处理冲突。新手阶段最省事的方式是勾掉这个选项让 GitHub 创建一个完全空的仓库。README 文件完全可以等代码推上去之后在本地新建再提交推送这样最顺畅。创建完成后GitHub 会显示一个页面上面有仓库的地址。我们一般用 HTTPS 地址格式是https://github.com/你的用户名/仓库名.git。4.2 在 PyCharm 里添加远程仓库地址回到 PyCharm顶部菜单栏选择 Git → Manage Remotes第一次会弹窗问你是否要添加远程仓库。这里要填的是远程仓库的“家庭住址”让本地 Git 知道该往哪里推。点击加号Name 填originURL 粘贴刚才复制的 HTTPS 地址点击 OK 保存。origin是 Git 里对“主远程仓库”的默认约定名称不是必须的但所有文档和教程都默认这个叫法建议不要改。填好之后点 OK本地仓库和 GitHub 远程仓库就建立了联系。这步操作等同于命令行里的git remote add origin 地址只是用图形界面做更直观。4.3 Push 推送第一次在 GitHub 看到自己的代码关联好远程仓库后执行推送。顶部菜单栏选择 Git → Push或者按快捷键 CtrlShiftKWindows / CmdShiftKmacOS。PyCharm 会弹出一个推送窗口显示当前要推送的分支一般是 master 或 main和提交记录。第一次推送时重点看一下窗口下半部分如果提示当前分支没有设置 upstream上游分支勾选或者点一下“Set upstream”相关选项。这个操作的意思是告诉本地分支“你的默认推送目标就是 origin 的这个分支”这样以后推送就不用每次手动指定。点击 Push 按钮后如果配置的是 HTTPS 方式PyCharm 会弹窗要求输入 GitHub 的用户名和 Token。用户名填你的 GitHub 账号名密码框里填 Token 而不是登录密码这点再强调一次。看到进度条走完没有报错你的代码就已经成功推送到 GitHub 上了。推送成功后可以直接打开 GitHub 仓库页面看到项目文件都在上面那种成就感还是很踏实的。到了这一步完整的“上传项目到 GitHub”就已经完成了接下来就是日常更新和问题处理了。5. 日常更新与常见问题排查第一次推送成功之后后面就会顺手很多。但日常使用中你还会遇到一些新的场景改了代码怎么上传别人改了远程代码怎么同步推送失败是什么原因这一节我把最常见的情况和坑都列出来建议收藏备用。5.1 改完代码后如何更新到 GitHub日常修改代码后更新到 GitHub 的最简步骤是三步先更新本地Pull、再提交Commit、再推送Push。Pull 的作用是把远程仓库的最新代码同步到本地。如果项目只有你一个人在开发远程代码一般不会比自己本地新但养成先 Pull 再 Push 的习惯非常有必要尤其是以后多人协作时这能避免掉大量冲突。操作路径是 Git → Pull或者点界面右上角的更新图标。然后按第 3 章的方法执行 Commit 和 Push。在 PyCharm 的设置里还可以勾选“提交时自动推送”选项这样每次 commit 完直接 push省一步操作。不过新手阶段我不太建议这样先手动走完完整流程熟悉了各个按钮的作用再让 PyCharm 帮你简化。5.2 从 GitHub 拉取别人的项目换个场景你可能需要把一个 GitHub 上的开源项目拿到本地来看或修改。这个操作叫 Clone跟上传正好是反方向。在 PyCharm 的欢迎页面点击 Get from VCS或者在 File → New → Project from Version Control 里输入项目的 Git 地址选择本地存放目录点击 Clone 即可。克隆下来的项目自带版本控制信息你可以直接查看历史记录、切换分支也可以修改后推送。如果你没有那个项目的修改权限推送会被拒绝这时候可以把项目 Fork 到自己账号下再克隆自己 Fork 出来的仓库修改后推送到自己的仓库这是 GitHub 开源协作的标准玩法。5.3 常见报错速查表我整理了我自己踩过、以及带新人时他们反复遇到的几类典型问题做成一张速查表遇到报错直接对照处理。报错信息或现象常见原因解决办法git not found或找不到 Git 可执行文件Git 未安装或安装时未加入 PATH重新安装 Git 并勾选加入 PATH然后重启 PyCharmAuthentication failed输入的密码不是 Token或 Token 过期在 GitHub 重新生成 Token在 PyCharm 里更新账号信息Push rejected: failed to push some refs远程仓库有本地没有的提交先执行 Git → Pull把远程代码拉下来合并后再推送remote origin already exists远程仓库地址重复添加在 Git → Manage Remotes 里删掉旧地址重新添加提交记录里作者不是自己未配置 user.name / user.email在终端里执行 git config --global 配置身份GitHub 网页访问很慢或打不开网络环境问题稍后重试或切换一个网络环境更稳定的网络这里有一个很多人都中过招的场景值得单独说远程仓库如果初始化时勾选了 README本地仓库第一次推送时会大概率遇到non-fast-forward之类的拒绝错误。原因很简单远程仓库存在一个本地没有的提交那个初始化的 README两边历史没有关联。解决办法就是先 PullPyCharm 会问你是否允许合并两个无关历史选择允许即可然后再 Push 就成功了。5.4 几个切实有用的实操建议如果你已经成功走通了一次流程下面这几个习惯可以帮你以后玩得更顺手。第一提交间隔要短。不要攒一周的改动一次性提交那种提交信息根本没法写清楚回滚也不知道该回滚到哪。每完成一个小功能、每修完一个 bug就提交一次。提交信息跟着这次改动的内容走尽量写清楚动词和对象比如“修复登录接口空指针异常”而不是一句笼统的“update”。第二养成先看 Git 工具栏的习惯。PyCharm 右下角的分支名称旁边的图标表示当前分支是否落后于远程、是否有未提交的修改。推送之前扫一眼心里有数再动手。第三.gitignore越早创建越好。如果项目已经提交了一堆不该提交的文件比如.idea、venv现在补救还不算晚。把对应规则写进.gitignore然后执行一次git rm -r --cached .之类的清理命令让这些文件从 Git 跟踪中移除再提交一次推送上去仓库就干净了。注意--cached的意思是只移除 Git 的跟踪记录不会删除本地文件正规仓库里都会维护一个干净的.gitignore这会直接影响别人对你的第一印象。另外多说一句如果你推代码到 GitHub 之后发现项目里有什么敏感信息比如数据库密码、API 密钥不要以为删掉再推一次就万事大吉了。Git 的历史记录里还留着旧版本任何能看到仓库的人都能翻出来。正确做法是立刻去对应平台把密钥作废重置然后清理历史记录。新人阶段最好从一开始就把.env这类文件写进.gitignore从源头上避免这个麻烦。把 PyCharm 项目传到 GitHub 这件事本质上就是一个“本地 Git 操作 远程平台对接”的过程。你不需要把 Git 的所有命令背下来只要理解了本地提交、远程推送、先 Pull 再 Push 这几个核心概念PyCharm 的图形界面会让你操作得很顺手。这套流程走通一次后面不管是更新自己的项目还是参与开源协作底层的逻辑都是一样的。