先说个我最近常遇到的场景本地项目在 IDEA 里编译运行一点问题没有结果到了要提交交付的时候团队的人说“把代码传到码云仓库”不少同学就卡在第一步。只记了一句git push后面跟着就是认证失败、分支对不上、远程仓库比本地多文件等各种状况。如果你也是第一次用 IntelliJ IDEA 往 Gitee码云上传项目这篇就是按我实际操作的顺序写的照着点一遍基本能通。这篇文章适合三类人刚接触 Git 的实习生、平时用 SVN 想切到 Git 的开发者、以及在 GitHub 和 Gitee 之间来回切换但经常被密钥搞晕的人。我聊的不只是“点几个按钮”还会把每一步背后的原因说清楚比如为什么要配 SSH、为什么第一次推送会被拒绝、怎么处理 master 和 main 分支的差异。这样你遇到报错时也能自己判断问题出在哪一层。1. 先弄明白参与上传的几个角色少踩一半的坑1.1 一次“上传项目”实际是三个角色在对话很多人把“上传项目到码云”理解成一个简单动作把文件夹拖进去。真实情况是这个动作牵扯到四个角色本地工作目录你正在写的 IDEA 项目文件夹里面是源码和配置文件。Git 本地仓库在本地项目目录下通过git init生成的.git隐藏目录它记录所有版本变更历史。Gitee 远程仓库码云上创建的那个空仓库本质是放在服务器上的另一个 Git 仓库。IDEA一个带图形界面的 Git 客户端它替你把add、commit、push这些命令包装成了菜单和按钮。搞清楚这个模型之后很多报错一下就明白了。比如push被拒绝不是 IDEA 坏了而是 Git 发现远程仓库和本地仓库的历史对不上比如一直要用户名密码是因为你没有配 SSH 密钥走的还是 HTTPS 用户口令认证。1.2 IDEA 相比纯命令行省在哪里命令行git push不难难的是在报错时没人给你解释。IDEA 的优势在于把所有 Git 状态可视化文件是绿色新增、蓝色修改、红色未跟踪一眼就知道哪些改动还没提交。Commit面板里可以直接看 diffLog面板能看到完整的提交图。尤其是第一次做“上传项目”这种完整流程时IDEA 的图形化能把“先 add 再 commit 然后 push”这条链路拆开每一步做完都有反馈不会像在终端里连续敲三条命令敲错了也不知道是哪个环节出的问题。所以这篇文章我以 IDEA 操作为主线但会附带对应的 Git 命令方便你在服务器环境或终端里复用。1.3 “上传”和“发布”不是一回事还有个小概念值得点一下把代码推送给 Git 仓库不等于把代码“发布”出去让别人能运行。Gitee 仓库分公开和私有公开仓库任何人都能 clone私有仓库只有被你加为成员的人能看。第一次练习时建议建私有仓库就算代码写了一半也不尴尬等稳定了再改成公开。2. 环境准备Git、IDEA、Gitee 账号一次性配齐2.1 确认 Git 已安装并且让 IDEA 能找到它IDEA 本身不自带 Git它只是调用你电脑上的 Git 程序。Windows 上常见的问题是 Git 装了但是 IDEA 里显示的路径是空的导致所有按钮都是灰的。检查步骤打开 IDEA进入File - Settings - Version Control - GitmacOS 是IntelliJ IDEA - Preferences。看Path to Git executable这一栏。Windows 通常是C:\Program Files\Git\bin\git.exeMac 通常是/usr/bin/git。如果空白或报错点右侧的Test按钮IDEA 会弹出 Git 版本号比如git version 2.39.2.windows.1。如果没有安装 Git去 Git 官网下载对应系统的安装包安装时有个选项提示“Adjusting your PATH environment”默认选择推荐的配置即可。装完后重新启动 IDEA再回到上面这个页面测试一次。注意不要图省事把 Git 装在中文路径或带空格的目录里IDEA 调用时偶尔会出奇怪问题。默认安装路径是最稳的。2.2 配置全局用户名和邮箱这是提交记录的身份 ID很多新手第一次 commit 成功但到了 Gitee 上看提交记录头像和用户名是乱的或者根本不显示。原因是 Git 不知道“你是谁”。这个信息写在本地全局配置里用终端执行git config --global user.name 你的Gitee用户名 git config --global user.email 你注册Gitee的邮箱注意这里的用户名和邮箱最好和 Gitee 账号保持一致这样推送过去的提交记录才能关联到你的 Gitee 头像。如果之前配过别的值可以用下面命令检查git config --global --list顺便多说一句这个配置是“全局的”影响你电脑上所有仓库。如果你同时用 GitHub 和 Gitee而且想用不同的用户名提交那就别配全局改成在具体仓库目录下执行不带--global的同款命令这是 Git 留出的后门。2.3 在 Gitee 上创建仓库时的几个选项登录 Gitee 后点右上角“”号选择“新建仓库”。这里有几个选项在一开始就影响后面操作选项我的建议仓库名称全小写字母和数字用中划线-连接单词不要用大写和中文是否开源练习阶段选私有等代码可公开后再改初始化仓库暂时不勾选“初始化仓库”也就是不用 README、.gitignore、开源许可证关键就在“初始化仓库”这一项。如果你勾选了Gitee 会帮你在远程仓库里生成README.md、.gitignore、LICENSE中的某几个文件。这些文件在你第一次 push 时会变成冲突来源因为远程仓库的历史里已经有一条“Initial commit”和你本地完全是两个孤立的根。后面我会专门讲这个问题的解法。Gitee 开源许可证选什么也是搜索引擎上高频词其实只在你真的要把代码开源时才需要考虑。个人练习选MIT最省事它基本只要求保留版权声明如果不想别人拿去商用选GPL-3.0更合适但这就属于法律范畴了我不过度展开。3. 认证链路SSH 密钥和 HTTPS 怎么选3.1 两种远程连接方式的区别往 Gitee 推送代码远程地址有两种写法https://gitee.com/用户名/仓库名.gitgitgitee.com:用户名/仓库名.gitHTTPS 方式第一次 push 时会要求输入 Gitee 用户名和密码以后在 IDEA 里可能反复弹窗SSH 方式只要把公钥配到 Gitee 一次之后所有操作都不需要再输密码而且传输走的是加密通道安全性更高。我的建议是以后长期用 IDEA 操作 Gitee直接用 SSH。虽然生成密钥显得麻烦但一劳永逸尤其是公司电脑和个人电脑来回用的时候配一次就省去后续很多沟通成本。如果只临时传一次文件HTTPS 也可以但要做好心理准备凭据过期或密码策略变动时又要折腾一遍认证。3.2 生成 SSH 密钥并添加到 Gitee打开 IDEA 自带的终端Terminal或者任意终端窗口执行ssh-keygen -t ed25519 -C 你的Gitee邮箱 -f ~/.ssh/id_ed25519_gitee这里解释下参数-t ed25519指定密钥算法比老的 RSA 更快也更安全-C是注释一般填邮箱方便识别-f指定生成的文件名。我刻意把文件名写成id_ed25519_gitee是为了和多账号场景区分下面会展开。执行过程中会提示设置 passphrase也就是私钥口令。建议直接回车留空否则以后每次连远程都要输入口令你很快就会烦。接着用命令查看公钥内容Windowstype C:\Users\你的用户名\.ssh\id_ed25519_gitee.pubmacOS / Linuxcat ~/.ssh/id_ed25519_gitee.pub复制输出的整行字符以ssh-ed25519开头。然后登录 Gitee进入头像 - 设置 - SSH公钥把内容粘贴进去标题随便填比如home-pc。添加成功后终端测试ssh -T gitgitee.com如果返回类似Hi 你的名字! Youve successfully authenticated的信息说明链路已经通了。有个细节容易忽略IDEA 的 Terminal 和系统终端用的可能是不同的 SSH 客户端。Win10 以上系统自带的 OpenSSH 和 Git 自带的 SSH 都行。只要ssh -T通过IDEA 推送时一般也能通过因为 IDEA 默认使用系统 SSH 工具。如果连接失败且报错里出现端口 443别慌那不是网络问题是需要检查你的密钥是否真的在~/.ssh下以及 Windows 的known_hosts中是否有旧记录。可以删除~/.ssh/known_hosts后再试一次这是低成本的重置手段。3.3 同时使用 GitHub 和 Gitee多账号密钥共存热搜词里有一条特别典型“本地全局设置了 gitee 和 github 两个库冲突怎么设置并且解决”。很多人都栽在这里。原因简单Git 默认会用~/.ssh/id_rsa或id_ed25519这个固定文件去连接所有 SSH 服务器如果你给 GitHub 生成了一个密钥又给 Gitee 覆盖生成到同一个文件那两边必有一边失联。正确做法是每个平台一个独立密钥文件然后通过~/.ssh/config告诉 SSH 哪台服务器用哪个密钥。在.ssh目录下新建一个无扩展名的 config 文件写入Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee IdentitiesOnly yes Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes保存后测试ssh -T gitgitee.com和ssh -T gitgithub.com两边都能认证成功就不冲突了。IdentitiesOnly yes这行很关键它强制 SSH 只使用你指定的密钥文件而不是把当前目录下所有密钥都试一遍。4. 上传操作全流程从本地工程到码云远程仓库4.1 第一步启用版本控制并把文件加入 Git我假设你已经在 IDEA 里打开一个真实存在的项目而不是在 Gitee 上先建仓库再 clone 下来的那种情况。这是“上传已有项目”最常规的场景。打开项目后点顶部菜单VCS - Enable Version Control Integration弹窗里选择Git。此时 IDEA 会执行git init把当前目录变成一个本地仓库左下角会出现一个“Git”工具窗口文件颜色也会发生变化。紧接着在项目根目录上右键选择Git - Add也可以直接按快捷键CtrlAltA一次把全部新文件都标记为跟踪状态。Add 操作对应命令git add .它的意思是“告诉 Git 这些文件进入暂存区”还没形成历史记录。到这一步你看到的文件颜色会从红色变成绿色代表已经纳入 Git 管理。如果你在.gitignore里写了某些目录它们会保持灰色或不可见状态。如果还没有.gitignore建议现在就补一个至少把target/、out/、.idea/workspace.xml这类编译产物和个人配置排除掉否则第一次提交会把一堆无意义文件打包进历史。4.2 第二步Commit 提交信息别乱写Add 之后点菜单Git - Commit Directory...或快捷键CtrlK进入提交界面。左边是待提交文件列表中间可以写提交信息下方 Show Diff 可以看到具体修改内容。提交信息的格式我个人的习惯是第一行用一句不超过 50 字的话概括做了什么比如feat: 初始化项目结构或fix: 修正登录接口的查询参数如果有必要再加空行后写详细说明。不要提交空信息那对以后回溯没有任何帮助。提交界面上有几个可勾选项比如“Optimize imports”“Reformat code”“Analyze code”。建议勾上Optimize imports和Reformat code它会自动整理代码格式。分析代码那个选项在项目大时会拖慢速度第一次可以关掉。点击Commit后本地就有了第一条提交记录。此时项目还在本地阶段和 Gitee 没有任何关系。很多同学走到这里以为“已完成”这只是把代码提交给了自己。4.3 第三步添加远程仓库 remote接下来要让 IDEA 知道“我要把代码推到哪个远程地址”。打开Git - Manage Remotes点加号名称填originURL 填你在 Gitee 仓库页复制的地址。这个地址在仓库首页右上角可以切换 HTTPS 和 SSH 两种格式因为我们前面配了 SSH这里就选 SSH 格式的地址。填好后点 OKIDEA 会把这条远程配置写进本地仓库的.git/config里。对应命令也很简单git remote add origin gitgitee.com:你的用户名/仓库名.git这时你可以用git remote -v查看能看到 fetch 和 push 两条记录说明本地已经知道远程仓库在哪了。注意如果项目最初是git clone下来的远程仓库已经自带不需要手动添加。判断方式就是Git - Manage Remotes里有没有origin。4.4 第四步Push 推送以及第一次推送后的分支检查现在执行最后的动作点菜单Git - Push或快捷键CtrlShiftKIDEA 会弹出推送对话框。第一次推送时分支选择很重要。你要确认左侧的本地分支是master还是main目标远程分支就是你本地分支的同名分支。打开“Push”弹窗下方的“Git”日志你会看到类似master - master的对应关系。如果没问题点Push。对应命令是git push -u origin master-u参数意味着把本地分支和远程分支绑定以后在这个分支上直接push或pull就不需要再指定分支名。推送成功后登录 Gitee 打开仓库页面应该能看到你的项目文件和刚才的提交记录。如果页面上写“仓库为空”但你明明 push 成功了多半是推送到了另一个分支名这个在下一章详细说。5. 上传现场最常见的几类翻车附排查顺序5.1 身份认证失败Authentication failedHTTPS 方式推送时最典型。弹窗里输入 Gitee 用户名和密码但死活报认证失败。这里有个隐藏机制Gitee 对 HTTPS 操作不总是接受账号密码。配合个人访问令牌会更稳在 Gitee 的设置 - 安全设置 - 私人令牌里生成一个把令牌作为密码填进去用户名还是你的 Gitee 用户名。如果每次 push 都弹这个窗口说明 IDEA 的凭据管理器里没有保存凭据或者保存了旧密码。Windows 用户在控制面板 - 凭据管理器 - Windows 凭据里可以找到gitee.com相关条目直接删掉重新 push 再输入一次就能刷新。排查链路我建议按这个顺序走确认远程地址是否写错比如把 SSH 地址填到 HTTPS 里。确认现在用的是 HTTPS 方式且用户名密码正确不对的话生成私人令牌。确认 Gitee 账号邮箱是否已验证未验证的账号有时会触发登录限制。5.2 推送被拒绝! [rejected] master - master (fetch first)这是“新建仓库时勾选了初始化仓库”后最典型的结果。远程仓库里有一条自动生成的初始提交本地仓库也有自己的初始提交两边历史完全不相干Git 默认禁止这种合并式推送。解法有两种我说清楚区别第一种如果远程仓库里的那些自动文件README、LICENSE你根本不需要可以在第一次推送时强制覆盖git push -u origin master -f强制推送会丢弃远程仓库的所有历史用本地历史覆盖上去。空仓库场景下没有损失但如果远程已经有别人的代码千万别这么干。第二种如果远程那些初始文件你确实想保留先拉取再合并需要允许不相关的历史git pull origin master --allow-unrelated-histories git push origin master对应到 IDEA可以先在Git - Pull里执行 pull如果弹窗出现“Allow unrelated histories”选项勾选它再 push 就正常了。这种场景新手容易慌其实只是 Git 在保护远程数据不被覆盖不是把你的代码弄坏了。5.3 分支名称不一致master 与 main 的差异GitHub 2020 年之后把初始分支从master改成了main但 Gitee 新建仓库默认主分支仍然叫master。如果你本地的 Git 版本比较新git init时可能默认生成main分支那么推送后 Gitee 仓库里会出现一个独立的main分支而不是master看起来就是项目“推上去了但仓库主页是空的”。最简单的处理办法是在推送前统一分支名。如果你已经生成main执行git branch -m master main这会把本地分支重命名为 main。如果你希望所有新仓库都用main可以设置全局默认git config --global init.defaultBranch mainIDEA 里查看当前分支在右下角状态栏能直接看到main或master字样。推送之前先确认一下右下角的分支名和 Gitee 仓库页面显示的主分支名一致基本就不会空仓库。我个人的建议是不要纠结于用哪个词团队内部定一个然后所有人统一。个人项目就看你习惯反正重命名只是本地操作远程也可以随时改默认分支。5.4 反复弹窗要用户名密码换 SSH 解决这个问题的最优解就是上面提到的 SSH 方式。配置 SSH 之后IDEA 推送时不再弹认证窗口因为 SSH 密钥已经完成了身份确认。如果配好了 SSH 还在弹用户名密码检查一下远程地址是不是https://开头且没有更新为git。还有一个容易忽视的地方IDEA 的Settings - Version Control - Git - SSH executable默认是Native它会直接调用系统 SSH。如果你在 Windows 上用 Git 自带的 SSH遇到识别问题可以在这里把选项切到Native并重启 IDEA。多数情况下Native最稳。6. 推上去之后拉取更新、分支和回滚的基础操作6.1 Pull 和 Fetch 到底在拉什么上传完成只是开始。之后你会需要把远程仓库的最新代码同步到本地IDEA 里有两个功能经常被混淆。Fetch只从远程下载最新提交信息到本地“缓存”不改动工作区文件也不会被你的提交操作影响。Pull相当于Fetch Merge会把远程分支的更新合并进当前分支。日常协作直接点Git - PullIDEA 会弹出更新策略选择Merge还是Rebase。初次接触建议用 Merge它的缺点是多出一些合并提交但历史更直观Rebase 能保持线性历史但理解成本高而且多人协作有改写历史的风险等熟悉了再用。如果 Pull 时出现冲突文件会变成红色IDEA 会打开合并工具左边是本地版本右边是远程版本中间是合并结果。逐行选择保留哪些改动完成后标记为 resolved再 commit 一次即可。遇到冲突不必害怕说明你改的恰巧和别人重合挑一个合理的组合就好。6.2 在 Gitee 上开分支本地同步推送分支是团队协作的基础。比如你要开发新功能不想影响主分支可以在 IDEA 右下角分支按钮上点New Branch输入分支名比如feature-login选中“checkout”然后创建。开发完成需要把这个分支推送到 Gitee 时直接CtrlShiftK推IDEA 会提示远程没有同名分支问你是否要创建。确认后远程仓库就能看到这个新分支了。对应命令git push -u origin feature-login之后在 Gitee 网页上可以用这个分支发起 Pull Request 或 Merge Request请团队成员审查后再合并回主分支。这是比直接在 master 上开发规范得多的协作模型。6.3 提交错了怎么办用 revert 而不是硬重置推送完才发现某条提交里面带了不该提交的密码文件或者改错了代码这时候不要慌。IDEA 的Log面板里右键某条提交记录有两个选项Revert Commit生成一条新的提交把这条提交的改动“反向”撤销一遍保留历史。Reset Current Branch to Here直接把分支指针拉回到某个历史节点。如果这条提交已经推送到远程而且多人共用建议用Revert。它会创建一个对抗提交不会改写远程历史别人 pull 时也不会遇到强制推送带来的冲突。如果项目只有你一个人而且你确定没有别人拉过这个分支用Reset然后强推也可以但我仍建议保守操作。上线系统里的历史比代码本身更值钱回滚手段越“软”越好。最后分享一个实操中很顺手的习惯我在 IDEA 里用 Git 好几年后最大的体会是把 90% 的操作都放到 IDEA 的Commit面板里完成而不是左边 Log 窗口看一圈、右边终端再敲命令。每次提交前花十秒钟看一下 diff把不该提交的临时文件点掉是这个习惯最值钱的部分。如果你是项目里第一个往 Gitee 推代码的人建议顺手在仓库页面的管理 - 分支设置里把默认分支设成大家约定好的那个再写清楚 README 的前几行项目干什么用的、需要什么环境、怎么启动。这一步比想象中重要因为后来 clone 项目的人第一眼看到的就是 README。以后在 IDEA 里拉取项目副本时直接File - New - Project from Version Control填仓库地址就能把远程仓库完整地拿到本地上传和拉取整个闭环就都顺畅了。把 IDEA 和 Gitee 这条链路理顺之后你会发现版本控制本身并不难难的是每次卡在认证、分支、冲突这些固定环节时能不能快速定位到是哪一个角色出了问题。按我上面给的顺序排查一遍绝大多数上传问题十分钟内都能解决。