妞妞牛波如果让我选一个新手最容易忽略、但对后续开发影响最大的习惯，我一定选：把 IDEA 项目第一时间提交到 Gitee 仓库。前段时间带一个刚入职的同事，他写了快两周的业务代码，全部放在本地 IDEA 的默认目录里，既没有接 Git，也没有建仓库。我当时就问了一句：这台电脑明天罢工，你的项目怎么办？他愣了几秒，然后开始冒汗。今天这篇文章，就围绕一个很具体的目标——把你的 idea 项目提交到 gitee 仓库去——把从环境准备、仓库创建、首次推送，到日常同步和常见报错处理的完整过程讲清楚。适合刚接触 IDEA 的同学，也适合本地代码从没被版本管理过、想做一次"保险"的老开发参考。
1. 为什么每个 IDEA 项目都值得尽早进 Gitee
1.1 没有远程仓库时，代码最常见的三种死法
我做技术这些年，见过太多本地代码"消失"的案例，基本可以归成三类。
第一类是硬盘物理损坏或系统崩溃。很多人以为"硬盘坏了送维修就行"，但对开发者来说，代码是逻辑资产，不是文件备份，维修成本远高于重写成本。尤其是一些改了很久的配置、环境相关的特殊调试代码，重写时根本想不起当初是怎么调通的。
第二类是误删和误覆盖。IDEA 的 Local History 只能恢复较短时间内的文件版本，如果哪天不小心把整个模块删了，或者一个重构改坏了所有文件，你回退起来会非常痛苦。我见过一个同事用"全选删除"清理代码，结果把整个 src 目录删了，当场脸都白了。
第三类是"代码只在某一台电脑上"。家里的台式机、公司的笔记本、临时借来的机器，三处代码各是各的版本，合并全靠网盘和 U 盘，最后哪个是最新的都分不清。真的，这种场景我遇到过不止一次，最后只能用最笨的办法逐行比对。
这些问题的根源只有一个：代码没有被纳入版本管理，而且没有一个可信的远程仓库作为"保险"。Git 本身已经解决了版本管理的问题，而 Gitee 恰好解决了"远程仓库放哪"的问题。
1.2 Gitee 在个人项目和团队协作里分别解决什么问题
如果只是个人项目，Gitee 提供的最核心价值就是异地备份与历史追溯。每次提交都是一个小快照，代码在任何一台机器上 pull 下来就能继续跑。这点对用 IDEA 做课程设计、个人博客、练手小项目的同学尤其重要，因为这类项目的代码量不大，但"丢了就很烦"。
团队协作场景下，Gitee 的价值就更明显了。所有人都从同一个仓库拉代码，通过分支和合并规范来推进功能，每个提交都能看到作者、时间和改动内容。新人接手老项目的时候，不用再问"这个模块是谁写的"，看提交记录和历史就能理清来龙去脉。还有 Issue、Pull Request、代码审查这些能力，虽然个人项目用不上，但团队一旦用起来，协作效率提升是肉眼可见的。
1.3 这个流程适合谁
这篇内容适合三类人。
第一类是完全零基础的新手，刚装了 IDEA，写过几个 demo，还不知道 Git 是什么。我会把每一步拆开讲，包括图形界面操作和命令行操作，你只需要跟着做。
第二类是本地有项目但从来没接版本管理的老开发，可能一直用复制文件夹的方式来"备份"，或者只是懒得配。这类人不用从头学 Git，只需要把"仓库创建 + 首次推送 + 日常同步"跑通，就能立刻摆脱裸奔状态。
第三类是要把自己的课程设计、毕设或开源小项目放到网上的学生和开发者。Gitee 是国内平台，访问速度快，创建私有仓库也没有限制，很适合作为个人代码资产的第一站。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 动手前的准备工作：装 Git、配 SSH、让 IDEA 认得 Git
2.1 安装 Git：Windows 和 macOS 都只要三步
IDEA 本身不内置 Git，它只是调用你系统里安装的 Git 命令。所以第一步是装好 Git。
Windows 用户直接去 Git 官网下载 Git for Windows，安装过程基本一路 Next。我要提醒几个容易被忽略的选项：安装向导里会问默认编辑器，建议选 Visual Studio Code 或者 Notepad++，别选 Vim，不然以后 commit 时需要填信息会卡住；"Adjusting your PATH environment"这一步要选中间那个 "Git from the command line and also from 3rd-party software"，保证 IDEA 和其他终端都能找到 git 命令；换行符转换保持默认的 "Checkout Windows-style, commit Unix-style line endings" 就行。
macOS 用户最简单的方式是打开终端，输入 git --version，如果系统提示没有安装，会弹窗引导安装 Command Line Tools，装完就有了。也可以用 Homebrew 执行 brew install git，版本会新一些。
装完以后，打开终端执行：
bash复制git --version
能输出版本号就说明装好了。
2.2 在 IDEA 里确认 Git 路径
IDEA 对新装的 Git 一般会自动识别，但偶尔也会出现识别不到的情况。打开 IDEA 的设置界面：
- Windows 路径：File → Settings → Version Control → Git
- macOS 路径：IntelliJ IDEA → Preferences → Version Control → Git
在 "Path to Git executable" 这一栏，确认指向了 git 的可执行文件。Windows 一般在 C:\Program Files\Git\bin\git.exe，macOS 一般是 /usr/bin/git。点击右边的 Test 按钮，如果弹出 "Git executed successfully" 就说明没问题。
这一步看起来很基础，但很多人第一次推送失败，原因就是 IDEA 根本找不到 Git，导致 VCS 菜单全是灰的。先把环境跑通，后面所有操作才顺。
2.3 注册 Gitee 并配置 SSH Key：一劳永逸的关键
去 Gitee 官网注册账号，这一步没什么好说的，邮箱一定要填常用邮箱，后面提交代码时要用。
注册好之后，配置 SSH Key。SSH 是一种安全的登录协议，配置好之后，本地和 Gitee 之间的通信就不需要每次都输账号密码了。原理是：本地生成一对密钥，公钥放到 Gitee 上，私钥留在本地，Gitee 通过公钥识别你的身份。
打开终端，执行：
bash复制ssh-keygen -t ed25519 -C "你的邮箱"
一路回车就行，会在 ~/.ssh/ 目录下生成两个文件：id_ed25519（私钥）和 id_ed25519.pub（公钥）。
然后查看公钥内容：
bash复制cat ~/.ssh/id_ed25519.pub
复制输出的整段内容。接着进入 Gitee 网站，右上角头像 → 设置 → 安全设置 → SSH 公钥 → 添加公钥，把内容粘贴进去，标题随意。
验证是否配好，执行：
bash复制ssh -T git@gitee.com
如果是第一次连接，会询问是否确认主机指纹，输入 yes 回车。看到类似 "Hi 用户名! You've successfully authenticated" 的提示就说明配置成功了。
2.4 为什么我强烈推荐 SSH 而不是 HTTPS
Gitee 仓库地址有两种形态：HTTPS 和 SSH。很多新手图省事直接复制 HTTPS 地址，但用下来会发现坑不少。
HTTPS 方式第一次 push 会要求输入 Gitee 的用户名和密码，如果开了两步验证还要用私人令牌，很麻烦。而且 IDEA 或系统凭据管理器保存的密码一旦过期，push 就会报认证失败，需要去删凭据、重新授权。SSH 方式只需要配置一次公钥，之后所有操作都是免密的。
我自己早期在 IDEA 里用过一段时间 HTTPS，后来换了 SSH，体验差别很大。如果做对比的话：
| 对比项 | HTTPS | SSH |
|---|---|---|
| 首次配置 | 简单，但需要输账号密码 | 需要生成并配置密钥，稍复杂 |
| 日常推送 | 可能被凭据过期打断 | 免密，稳定 |
| 安全性 | 账号密码有泄露风险 | 私钥本地保存，更安全 |
| IDEA 中配置 | 要在凭据管理器里维护 | 配好一次基本不用管 |
所以我的建议很直接：如果你打算长期用 Gitee 管理代码，一次性花五分钟配好 SSH，绝对值。
3. 在 Gitee 创建仓库时，这几个选项别乱选
3.1 仓库名称和路径决定你以后的推拉地址
登录 Gitee 后，点击右上角的加号 → 新建仓库，进入创建页面。仓库名称建议用英文小写加连字符，比如 springboot-demo、blog-manage-system。中文和空格虽然能创建，但会在 URL 里被转义，push 和 clone 的时候容易出事。
仓库的"路径"会自动根据名称生成，最终完整地址是 https://gitee.com/你的用户名/仓库路径.git（HTTPS 格式）或 git@gitee.com:你的用户名/仓库路径.git（SSH 格式）。这个地址后面推送时要原样复制，所以仓库名别起得太随意。
3.2 私有还是公开，想好再选
Gitee 创建仓库时有"私有"和"公开"两个选项。
公开仓库意味着所有人都能看到你的代码，可以 Clone、Fork、提 Issue。如果你的项目打算开源、放作品集、或者给别人参考，选公开没问题。但如果是课程设计、公司内部代码、或者你自己还在调试中的半成品，强烈建议选私有。私有仓库在个人的项目里是完全够用的，等代码稳定了、想开源了，再改成公开也来得及。
我见过有人为了"显得项目多"把所有仓库都设成公开，结果里面有数据库密码、API Key 这类敏感信息，后来被扫描工具扫出来，非常尴尬。所以这个选项要慎重。
3.3 是否勾选"初始化仓库"：本地已有项目时别勾
创建页面下方会有一个选项，问是否使用 Readme 文件初始化这个仓库。
如果你是一个全新的空项目，打算直接从 IDEA 里新建文件，那勾选初始化没问题。但你是想"把本地已有的 IDEA 项目推上去"，我的建议是：不要勾选任何初始化模板，让远程仓库保持一个完全空的状态。
因为一旦远程仓库有了 README 或 .gitignore 的初始提交，而本地项目又是一个全新的 Git 仓库，两边是两条互不相干的历史线，第一次 pull 就会出现 refusing to merge unrelated histories 的报错。虽然可以用参数强制合并，但对新手来说，凭空多一个坑完全没有必要。
远程保持空仓库，本地项目 git push 上去就是一条干净的历史线，这会省掉很多麻烦。
3.4 .gitignore 模板和开源许可证：能选就选上
如果你创建仓库时决定初始化，页面上通常会提供 .gitignore 模板的选项，里面有 Java、Maven、Spring Boot 等很多语言的选择。
这里的建议是：与其依赖网站的模板，不如在自己的 IDEA 项目里手动配一份更稳妥的 .gitignore。因为网站模板可能跟你实际用的构建工具、IDE 版本不完全匹配。而且如果你本地已经有项目，"初始化仓库"这个动作本身就会造成两段历史，还是那句话，能不勾就不勾。
至于开源许可证，如果你选公开仓库，建议了解一下 MIT、Apache 2.0、GPL 的区别。不想纠结的话，个人学习项目可以先不选，等真要开源了再补。选许可证属于开源合规领域的事，这里不展开了，但有一点要记住：许可证一旦加上，别人使用你的代码就受它约束，别乱选。
4. 在 IDEA 里把项目推到 Gitee 的完整操作链路
4.1 方式一：纯 IDEA 图形界面操作，适合快捷键党
这是最直观的一条路，全程不需要打开终端。
第一步，打开你的 IDEA 项目，点击顶部菜单 VCS → Enable Version Control Integration，在弹出的对话框里选择 Git，然后确认。这一步会为项目启用版本控制，此时 IDEA 会开始跟踪项目文件的变更状态，文件名会变成红色或绿色。
第二步，右键点击项目根目录 → Git → Add，把所有文件加到暂存区。此时文件名会变成绿色，表示已被跟踪。
这里我要特别强调：在 Add 之前，先把 .gitignore 文件创建好。不然会把 target/、.idea/ 这些不该上传的东西一并加进去。在项目根目录新建一个名为 .gitignore 的文件，把需要的排除规则写好，然后再 Add 和 Commit。如果你现在项目里已经有大量编译产物，也没关系，后面第 5.3 节我会专门讲怎么清理。
第三步，打开提交窗口。Windows 用 Ctrl+K，macOS 用 Cmd+K。在右侧面板里勾选要提交的文件，填写 Commit Message，比如 feat: 初始化项目，提交基础代码，然后点击 Commit。
第四步，推送。Windows 用 Ctrl+Shift+K，macOS 用 Cmd+Shift+K。IDEA 会弹出 Push 窗口，如果还没配置远程仓库，会看到 "Define remote" 链接，点击后把你在 Gitee 仓库页复制的 SSH 地址粘贴进去。然后点击 Push。
第一次 push 时 IDEA 可能会提示确认远程主机指纹，选择确认即可。推送完成后，IDEA 右下角会弹出 "Push successful" 的提示，去 Gitee 刷新一下仓库页面，就能看到代码了。
4.2 方式二：终端命令行的推荐流程，适合习惯敲命令的人
命令行方式并没有比图形界面更复杂，反而能让你看清每一步到底发生了什么。
打开 IDEA 内置终端（Terminal 面板，或者 Alt+F12），在项目根目录执行：
bash复制git init
这时候项目里会出现一个隐藏的 .git 目录，说明本地仓库初始化完成。
接着创建 .gitignore（如果项目里还没有），然后执行：
bash复制git add .
git commit -m "feat: 初始化项目，提交基础代码"
添加远程仓库地址：
bash复制git remote add origin git@gitee.com:你的用户名/你的仓库名.git
推送：
bash复制git push -u origin master
-u 参数的作用是建立本地分支和远程分支的关联关系，后面再执行 git push 或 git pull 时，就不用每次指定分支名了。
如果你的 Gitee 仓库是空的（采用了第 3.3 节建议），这一步会直接成功。如果仓库里有初始提交，那就先执行：
bash复制git pull origin master --allow-unrelated-histories
这个命令告诉 Git：允许合并两个没有共同历史的分支。合并完成后如果有冲突，解决冲突再提交，最后再 git push -u origin master。
4.3 推送之后怎么确认真的成功了
推送完成不是看 IDEA 不报错就完事了，建议做三个确认：
第一，打开 Gitee 仓库页面，看文件列表是否完整，src 目录、pom.xml 或 package.json 这些关键文件应该在。第二，看提交记录，最新的 commit message 应该能在页面上看到。第三，在 IDEA 的 Git 窗口（View → Tool Windows → Git）里查看 Log，应该能看到一条或多条提交记录，并且显示 origin/master 的位置和本地 master 一致。
这一步虽然简单，但我建议每次推送后都扫一眼。很多时候你以为推送成功了，实际上因为认证失败或远端冲突，只是 IDEA 把失败提示放在了右下角，你随手点掉了，代码压根没上去。
5. 第一次推送的翻车现场：五个高频报错的完整排查过程
5.1 "commit author is not ..."：提交者身份和 Gitee 账号对不上
这个报错在 Gitee 上非常常见。你 push 的时候，Gitee 远端会拒绝并提示类似 "commit author is not ..." 的信息，意思是：你本地提交记录里的作者身份，和 Gitee 账号关联的身份对不上。
我第一次遇到时也很懵，本地提交明明成功了，为什么远端不认？
排查链路应该是这样：先看报错的具体文案，Gitee 一般会提示 "提交者不存在" 或者 "并不是仓库成员"。这时候打开 IDEA 的终端，执行：
bash复制git config user.name
git config user.email
你会发现本地的 user.name 可能是你自己，但 user.email 可能填了一个跟 Gitee 注册邮箱完全不一样的邮箱。Gitee 是通过提交邮箱来关联账号身份的，邮箱对不上，它就认为这个提交不是你做的。
解决办法是，在项目仓库里单独设置正确的用户信息：
bash复制git config user.name "你的名字"
git config user.email "你注册Gitee的邮箱"
这里我用的是不带 --global 的写法，只对当前仓库生效，因为 Gitee 上一个账号用一个邮箱就够了，不会影响其他项目。
设置完成后，把刚才那条身份错误的提交修正一下：
bash复制git commit --amend --reset-author
然后重新 push。如果仓库里已经有多条身份错误的提交，直接用 git rebase -i 一个个改会比较麻烦，建议从源头开始保持正确。
5.2 "Push rejected" / "Authentication failed"：认证或权限出了问题
这类报错的表现有两种：一种是 IDEA 弹框提示 "Authentication failed"，另一种是终端里直接提示 "Push rejected"。
先看你自己用的远程地址。如果是 HTTPS，大概率是密码、私人令牌过期，或者仓库权限不足。如果是 SSH，报认证失败的相对较少，真出现了多半是公钥配置有误。
HTTPS 情况下的排查链路：先确认最近是否改过 Gitee 密码，或者是否开启了两步验证。IDEA 和 Windows 凭据管理器里保存的是旧密码，就会一直认证失败。解决办法是打开 Windows 的"凭据管理器"，找到 git:https://gitee.com 这条，点击删除，然后重新 push，IDEA 会再次弹出输入密码的窗口，输入新密码即可。
还有一个很容易忽略的点：如果你登录 Gitee 用的是手机号绑定的账号，而仓库又归属在主邮箱账号下，HTTPS 认证可能会因为账号不一致被拒绝。这也是我推荐 SSH 的原因，因为 SSH 只认公钥，不涉及密码和账号体系。
SSH 情况下如果报认证失败，可以重新执行 ssh -T git@gitee.com 测试，看返回的是哪个用户名。如果输出跟你预期不一致，说明公钥可能配在了另一个账号上，需要回 Gitee 设置里检查。
5.3 把 target 目录和 .idea 目录推上去了：.gitignore 没生效
这是另一个高频翻车点。很多 Maven 项目，本地编译一次就生成一个巨大的 target/ 目录，里面全是 class、jar、临时文件。如果你在 Add 之前没有建 .gitignore，这些东西就全被推上去了，仓库变得巨大且杂乱，别人 clone 下来还会看到一堆编译产物。
更尴尬的是，很多人发现问题后"补"了一个 .gitignore，但提交时发现 target/ 目录还在——因为已经被 Git 跟踪的文件，.gitignore 是管不住的。.gitignore 只对"尚未被跟踪"的文件生效，已经跟踪的文件需要先取消跟踪。
正确的清理方法是：
bash复制git rm -r --cached target
git rm -r --cached .idea
git rm -r --cached .iml
然后提交并推送，远程仓库里的这些目录才会被移除。
下面这份 .gitignore 模板，我个人一直在用，覆盖了 IDEA、Maven 和常见操作系统文件：
gitignore复制# IDEA
.idea/
*.iml
*.ipr
*.iws
# 编译输出
target/
out/
build/
# 日志和临时文件
*.log
*.tmp
.DS_Store
# 本地配置
application-local.yml
.env
注意最后两行，如果你的项目里有本地私有的配置文件，比如数据库密码、API Key，一定要写进 .gitignore 避免上传。至于 .idea/ 整个目录，有人会保留一部分共享配置，但为了省事，我的建议是开发环境配置尽量用 Maven 或 Gradle 管理，IDE 个人配置不入库也不影响项目构建。
5.4 "refusing to merge unrelated histories"：本地和远程是两条独立历史
这个报错通常出现在你创建 Gitee 仓库时勾选了"初始化仓库"，或者远程仓库本身已经有提交内容，而本地又是一个刚 git init 的全新仓库。两条历史没有共同的祖先，Git 默认拒绝合并。
排查链路走一圈：先确认远程仓库确实有提交记录，比如 README 或 .gitignore 已被初始化；再看本地仓库 git log，会发现只有你自己的本地提交。
解决方法有两种。
一种是直接拉取并允许合并不相关的历史：
bash复制git pull origin master --allow-unrelated-histories
合并后，如果 README 和本地文件有冲突，打开冲突文件手动处理，然后 git commit，再 push。这种方法的优点是简单，缺点是本地历史和远程初始化历史会合并成一条多叉历史，看起来不那么干净。
另一种是撤销本地的 Git 初始化，让 IDEA 项目直接基于远程仓库克隆出来。把本地代码先备份，然后删掉 .git 目录，再用 git clone git@gitee.com:用户名/仓库名.git 克隆一个干净仓库，把代码复制进去。这样历史从头就是一致的，不过步骤繁琐些。
对个人项目来说，第一种方法的成本最低，我推荐直接 --allow-unrelated-histories。
5.5 远程代码已经被人更新了，本地直接 push 被拒
这个场景在团队协作里特别常见。你在本地提交了代码，同事（或者你自己的另一台电脑）已经先一步把新代码推到了远程。你直接 push 会被拒绝，因为远程分支比本地分支领先。
很多人这时候会慌，其实解决思路很固定：先把远程的更新合到本地，解决冲突，再推送。
推荐的操作顺序是：先确保本地所有改动已提交，可以执行 git status 检查；然后拉取远程更新：
bash复制git pull origin master
或者用 IDEA 的 Update Project 按钮。如果代码有冲突，IDEA 会弹出冲突解决窗口，分成 Left（本地）、Right（远程）、Result（合并结果）三栏。逐项查看差异，保留或合并需要的代码，点击 Apply。
解决完冲突后，执行 commit 和 push。整个过程是先合后推，不要试图用 git push --force 强推，除非你明确知道自己在做什么，否则会直接覆盖同事的提交，属于团队协作中的危险操作。
6. 提交只是开始：提交信息、分支管理和日常同步的实操建议
6.1 用"看得懂"的提交信息替代 Update 三连
你在 Gitee 上看到的提交记录，本质上是一个项目的时间线。如果每条信息都是 "update"、"fix"、"aaa"，一个月以后你自己都看不懂当时改了什么。
我建议使用一套非常简化的提交信息规范，格式是：类型(范围): 描述。
常用的类型有这些：
feat：新增功能fix：修复缺陷docs：改文档style：代码格式调整，不改变逻辑refactor：重构，不改变功能test：改测试chore：构建工具、依赖等杂项
举个例子，同样是提交一次登录接口的修改：
- 差：
update - 好：
feat(auth): 新增用户名密码登录接口 - 好：
fix(user): 修复手机号校验失败时无提示的问题
范围不强制加，但加了会更清晰。commit message 是写给未来自己看的，每次提交前花十秒钟想清楚描述，长期收益非常大。
6.2 一个人开发也要有分支意识
很多人以为"我自己写项目，直接在 master 上提交不就行了？"可以，但等你项目慢慢变大，你会发现直接在主干上开发有几个问题：改到一半想回退某个功能，找不到节点；某天出现了严重 bug，想切换到上一个稳定版本，结果 HEAD 已经乱了。
我的个人习惯是：main（或 master）分支永远保留可运行的稳定版本，开发新功能时新建一个分支，比如 feature/xxx。功能验证通过后，再合并回 main。在 IDEA 里操作很简单：右下角分支按钮 → New Branch → 输入分支名创建；合并时切回 main → Git 窗口 → 找到待合并分支 → Merge into Current。
这个习惯在团队协作里是必备的，个人项目提前养成，以后自然就会用。
6.3 每天开工前先 pull 一次，收工前 push 一次
如果你是团队协作，或者同个项目在不同电脑间切换，这两个动作建议固定成习惯。
开工前执行 git pull，把远程最新的提交拉下来，避免在旧代码基础上写新功能；收工前执行 git push，保证今天的改动在远程有备份，不至于电脑出问题后白白丢失一天的工作。
如果你在 IDEA 里维护多个 Git 仓库，可以用同步窗口统一拉取。Windows 快捷键是 Ctrl+T，macOS 是 Cmd+T，或者点击菜单 VCS → Update Project。IDEA 会把更新来源、更新策略都处理好，比你手动敲命令更安全。
6.4 冲突解决的一个顺序建议
很多新手第一次遇到冲突，第一反应是"完蛋了，代码废了"。其实冲突本质上只是"同一块代码被两方都改了"，Git 不确定该听谁的。
我推荐的解决顺序是：先本地 commit，再 pull，然后在 IDEA 里逐个打开冲突文件。左边是本地版本，右边是远程版本，中间是合并结果。优先保留双方都能兼容的代码，涉及业务逻辑的冲突，要理解两边改动意图之后再合并，不要无脑保留一边。
解决完所有冲突后，IDEA 会生成 MERGE 状态，提交后就完成了合并，最后 push。
根据我自己的经验，冲突大多不是因为代码复杂，而是因为两个人同时改了同一行、同一个方法签名。日常提交频率高一点、每次改动范围小一点，冲突自然会少很多。
写了这么多，最后分享一个我自己的习惯：我喜欢把 IDEA 的 Push 快捷键记成"提交代码是 Ctrl+K，推送代码是 Ctrl+Shift+K"，并且会在每天离开工位之前按一下推送。很多人第一次配好 Gitee 就想把所有功能一次推上去，其实不必，小步提交、频繁推送才是更稳的节奏。等你真遇到硬盘挂掉、代码改坏、需要回退的那一天，你会感谢今天这几分钟建好的远程仓库。