包包和糖葫芦你有没有过这种经历：项目在本地写了一半，代码越堆越多，电脑一格式化全没了。或者想跟同学、同事协作开发，结果文件传来传去互相覆盖，改到怀疑人生。其实解决方式一直很成熟，就是 Git 加 Gitee 这套组合：Git 管版本，Gitee 管托管，本地写的每一版改动都能稳稳推上去，需要哪个版本随时拉回来。对于个人开发者、学生党、小团队来说，这几乎是上手最快、性价比最高的方案。
这篇就给你捋一遍 Git 本地仓库快速上传 Gitee 的完整流程，从装 Git、配环境、建仓库到推送、免密，再到日常拉取和分支管理，全是我自己踩过坑之后整理出来的实操记录。不管你是刚装好 Git 还不知道怎么用，还是第一次把项目推到 Gitee 上被各种报错劝退，照着做基本都能跑通。
1. 环境准备：Git 安装与基础配置
既然要操作 Git，第一步肯定是把环境装好。很多人卡在这一步是因为安装包下载慢、安完命令不识别、配置完发现用户名邮箱填错了，各种小问题叠在一起就耐心耗尽了。这里我把从下载到验证的完整过程讲透。
1.1 各平台 Git 安装与验证
Windows 用户直接去 Git 官网下载安装包就行，下载时注意选操作系统对应的位数（64位是主流）。安装过程没有特别需要改的选项，唯一建议是“Adjusting your PATH environment”这一步选择“Git from the command line and also from 3rd-party software”，这样 Git 命令可以在 CMD 和 PowerShell 里直接使用，免得后面打开终端发现找不到 git 命令。安装完成后打开 CMD 或 PowerShell，敲一句：
bash复制git --version
能显示 git version 2.x.x.windows.x 之类的版本号，说明安装成功。macOS 用户可以用 Homebrew 装：brew install git，Linux 用户用发行版自带的包管理器，比如 Ubuntu 执行 sudo apt install git，CentOS 执行 sudo yum install git。装完同样跑一下 git --version 验证。
我在给新电脑配环境时习惯顺手把 Git Bash 也打开测一遍，因为后面很多操作在 Git Bash 里执行比 CMD 更顺手，支持的命令更全。这里有两个细节容易踩坑：一是安装时别一路下一步把默认设置全跳过，特别是 PATH 那一项；二是安装完一定要重开终端窗口再用，不然环境变量不会立即生效。
1.2 配置用户名和邮箱：为什么不能省
Git 提交时，每一次 commit 都会记录提交者的名字和邮箱，这个信息挂在提交记录上，团队协作时用来区分谁改的代码。如果本地没配，Git 会默认用操作系统用户名生成一个奇怪的账号，提交记录看起来就不够规范。配置命令如下：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
--global 表示全局生效，也就是这台机器上所有仓库都用这个身份。如果某个特定项目想用不同身份，可以去掉 --global，在该项目目录下单独执行一次。
配置完成后可以用以下命令查看当前配置，确诊无误再继续：
bash复制git config --global --list
我自己的习惯是邮箱一定填 Gitee 注册用的那个，这样提交记录能关联上 Gitee 账号，推送时会显示头像和名字，一眼能认出是谁的提交。这里有个小坑：如果设置完发现之前提交记录里的邮箱不对，不影响后续推送，只是历史提交关联不上。想改历史记录的话操作比较繁琐，建议在第一次提交前就配好。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Gitee 仓库创建与本地仓库初始化
环境准备好之后，下一步是理清楚两端的关系。Gitee 是云端托管平台，用来存远程仓库；本地仓库是你在自己电脑上工作的目录。把本地代码推上去之前，需要先在 Gitee 建一个空仓库，再在本地把目录变成一个 Git 仓库。两个仓库之间通过地址建立连接。
2.1 Gitee 创建新仓库：关键选项怎么选
登录 Gitee 官网，进入右上角的“+”号，下拉选择“新建仓库”。这里有几个选项在第一次创建时容易纠结，我把我的选法列出来：
| 配置项 | 我的选择 | 说明 |
|---|---|---|
| 仓库名称 | 与本地项目名一致 | 方便识别，避免仓库多了对不上 |
| 路径 | 默认自动生成 | 会和仓库名称保持一致，也可以自定义 |
| 开源许可证 | 看情况，选 MIT 居多 | 想要别人能自由使用选 MIT，不想让别人用就选无许可证 |
| 初始化仓库 | 不勾选 README | 本地已有代码时选了会制造冲突 |
| 分支模型 | 默认即可 | 裸仓库就选默认，不用关心单目录/多目录 |
关于开源许可证，很多人纠结选什么。如果你只是想自己存代码，不打算开源，那就不选许可证，别人看到仓库也知道不能随意使用。如果你打算把项目分享出去，让更多人参与，我一般建议 MIT，协议内容短，限制少，大家都爱用。GPL 更适合希望衍生作品也保持开源的场景，但日常个人项目基本用不上。
新建仓库时千万别勾选“用 README 初始化仓库”。很多教程会让你勾上，但本地已经有一堆代码文件时，Gitee 生成的 README 会和本地提交的历史完全无关，首次推送时 Git 会认为两边都各自有提交，合并起来特别别扭。推荐的做法是本地先推代码，再在 Gitee 网页补充 README，两边不冲突。
2.2 本地仓库初始化：git init 到底做了什么
在本地项目的根目录打开终端，执行：
bash复制git init
这行命令会在当前目录生成一个隐藏的 .git 文件夹，里面记录着整个仓库的版本历史、分支信息、配置文件等等。这个文件夹是整个仓库的心脏，删掉它就等于丢失了所有版本记录，所以平时备份项目时要注意。
初始化之后可以执行 git status 查看仓库当前状态，如果显示类似“Untracked files”的提示，说明 Git 已经感知到目录里的文件了，只是还没开始管理它们的版本。这一步做完，本地仓库就算建起来了，跟 Gitee 上的空仓库之间还差一个“关联”操作，这个放到下一节讲。
3. 核心实操：首次推送完整流程
第一次推到 Gitee 是整个流程里坑最多的环节，命令本身只有几步，但每步之间藏着很多细节。我先按顺序列出完整命令，再逐个解释每行的作用和可能遇到的问题。
3.1 添加文件与提交：commit 信息别乱写
假设项目目录下已经有代码文件了，先加进版本控制：
bash复制git add .
git add . 表示把当前目录下所有未跟踪和修改过的文件加入暂存区。如果只想提交某个文件，可以把 . 换成具体文件名。继续执行：
bash复制git commit -m "初始化项目"
-m 参数后面带的是提交说明，说明里写清楚这次改动的内容。从第一次提交开始就养成规范习惯，后面翻历史记录时会非常省心。
提交说明怎么写？简单说就是“什么原因、改了什么、影响什么”。比如 fix: 修复登录接口超时问题 就比 更新 清晰得多。现在团队普遍用 Conventional Commits 约定，格式是 类型(可选范围): 描述，类型包含 feat（新功能）、fix（修 bug）、docs（文档）等。个人项目同样适用，因为三个月后你自己一样会忘记当时的改动意图。
这里有个新手最容易犯的错误：直接执行 git commit -m 发现报错 Please tell me who you are，这就是前面没配用户名和邮箱。回去跑 git config --global user.name 和 git config --global user.email 就行，不用重新 add 再 commit，直接再敲一次 commit 命令。
3.2 关联远程仓库：remote add 的正确姿势
Gitee 仓库创建好后，页面会显示仓库的 HTTPS 或 SSH 地址，复制下来。回到终端执行关联命令：
bash复制git remote add origin https://gitee.com/你的用户名/仓库名.git
origin 是远程仓库的默认名字，相当于给这个完整地址起了一个简短的别名。之后推送、拉取时就不需要每次输入一长串 URL 了。查看关联是否成功，用：
bash复制git remote -v
能看到 origin 对应的 fetch 和 push 地址就说明关联成功了。
我遇到过不少人在这里卡住，原因是复制地址时把仓库名前后空格也带进去了，或者地址里混入了多余字符，导致关联后推送失败。建议粘贴时先在记事本里清理一下再执行，避免肉眼不易察觉的坑。
3.3 推送并设置上游：首次 push 的参数详解
关联完成后，执行推送：
bash复制git push -u origin master
如果你的主分支是 main，就换成 git push -u origin main。这里 -u 是 --set-upstream 的简写，意思是把本地分支和远程分支关联起来，以后在本地该分支下直接执行 git push 和 git pull 就能自动对应到远程分支，不用再输入分支名。
首次推送时，如果本地分支名和远程分支名不一致，比如本地是 master，远程是 main，推送就会失败。解决办法是先把本地分支改名：
bash复制git branch -m master main
然后再执行 git push -u origin main。我自己一般会在 git init 之后立刻确认一下默认分支名，统一用 main，因为 Gitee 新建仓库默认分支也是 main，两边对齐能省掉很多麻烦。
推送过程中还会遇到首次连接提示确认主机指纹的情况，输入 yes 回车即可。接着如果配置了 HTTPS 方式，会要求输入 Gitee 用户名和密码，或者个人访问令牌。
到这里，一个本地仓库就成功推到 Gitee 了。整个过程总结成五句话：git init 建仓库、git add 加文件、git commit 写记录、git remote add 关联远程、git push 推上去。
4. 免密推送配置：SSH 密钥详解
推送成功后，接下来最影响使用体验的就是每次 push 都要输密码。这个重复动作看着小，实际用起来很恼人。Gitee 提供了两种免密方案：HTTPS 记住凭据和 SSH 密钥认证。我更推荐 SSH，一起看下为什么。
4.1 生成 SSH 密钥：参数说明与实操
SSH 密钥分公钥和私钥，公钥放在 Gitee 上，私钥留在本地，握手时通过密钥对完成身份验证。生成命令：
bash复制ssh-keygen -t rsa -C "你的邮箱" -b 4096
参数说明：-t 指定密钥类型，rsa 是通用性最好的选择；-C 是注释，建议用注册 Gitee 的邮箱，方便识别；-b 指定密钥长度，4096 位安全性更高，当然少数的旧系统对 4096 支持不好，一般用 2048 也行。
执行后终端会提示保存位置，直接回车用默认路径 ~/.ssh/id_rsa。接下来会要求设置 passphrase，这个相当于给私钥再加一层密码保护，可以留空，但为了安全我还是建议设一个。设置后每次使用 SSH 时输入一次，配合 ssh-agent 可以只在会话内输入一次。
生成完成后，Linux/macOS 可以用以下命令查看公钥内容：
bash复制cat ~/.ssh/id_rsa.pub
Windows 用户如果用的是 Git Bash，同样可以执行。如果 ~/.ssh 目录下已经有 id_rsa 和 id_rsa.pub，说明之前生成过密钥，不必重新生成，直接查看公钥即可。
4.2 将公钥添加到 Gitee 并验证连接
登录 Gitee，进入“设置” -> “安全设置” -> “SSH 公钥”页面，把 id_rsa.pub 文件里的内容完整复制粘贴进去，标题可以随意填，比如“我的电脑”，然后确认添加。
验证是否配置成功，执行：
bash复制ssh -T git@gitee.com
这里有一点要注意，Gitee 的 SSH 服务地址是 git@gitee.com，和 GitHub 的 git@github.com 不一样，别记混了。验证时会看到类似“Hi XXX! You've successfully authenticated, but GITEE.COM does not provide shell access.”的提示，这就说明 SSH 认证已经通了。
4.3 将 remote 地址切换为 SSH 并完成免密推送
添加公钥只是让 SSH 验证通过，真正的关键是仓库的 remote 地址要改成 SSH 格式。查看当前地址：
bash复制git remote -v
如果显示的是 HTTPS 地址（以 https:// 开头），改成 SSH 地址的命令：
bash复制git remote set-url origin git@gitee.com:你的用户名/仓库名.git
改完再执行：
bash复制git push
这次不会再提示输密码了。我举个例子方便理解：HTTPS 方式就像你每次去朋友家门口都要喊口令，SSH 方式是直接配了一把钥匙，第一次输入一次 passphrase，之后每次开关门直接推门就进。日常开发中顺手很多。
很多人在这一步踩坑，以为是生成密钥就完事了，结果 push 还是要求输密码，就是因为 remote 地址还是 HTTPS 格式。密钥解决的只是身份认证，地址没切过去等于白搭。
5. 日常使用：拉取、克隆与分支管理
推上去只是开始，真正用到日常开发的是后续的克隆、拉取和分支操作。很多教程讲到这里就结束了，但实操中你会发现，没掌握这些，用 Git 的效率会大打折扣。
5.1 克隆与拉取：从 Gitee 获取代码的两种方式
换一台电脑，或者团队成员要从 Gitee 拿代码，用克隆：
bash复制git clone git@gitee.com:你的用户名/仓库名.git
克隆会在当前目录创建一个与仓库同名的文件夹，并把完整历史记录一起拉下来。克隆之后进入项目目录，直接就是 Git 仓库状态，不需要再 git init。
如果代码已经在本地仓库，同事在 Gitee 上新增了提交，你想把最新代码拉到本地，就在对应分支下执行：
bash复制git pull
git pull 等价于 git fetch 加 git merge，先把远程最新提交抓到本地，再合入当前分支。这里有个坑：如果本地有未提交的修改，且修改的文件和远程更新的文件有重叠，pull 就会报冲突。解决方式是先把本地修改提交了（或 stash 暂存），再 pull。我个人的习惯是拉取前先用 git status 看一眼有没有未提交内容，有的话先 git stash，pull 完再 git stash pop 恢复，这样不容易打断工作流。
5.2 分支管理命名规范与切换
分支是 Git 的多维时空，让不同功能、不同实验互不干扰。Gitee 上新建仓库默认分支是 main，日常开发不要直接在 main 上改，拉一个分支出来干活更安全。
创建并切换新分支：
bash复制git checkout -b feature/登录模块
这条命令相当于 git branch feature/登录模块 加 git checkout feature/登录模块 两句合体。分支命名建议和 Conventional Commits 保持一致：feature/xxx（新功能）、fix/xxx（修复）、docs/xxx（文档）。这样做的好处是有分支名就能猜到这分支在干什么，发布时按分支合并，回溯也很清晰。
推送新分支到 Gitee：
bash复制git push -u origin feature/登录模块
在 Gitee 网页上可以看到新分支，还能发起 Pull Request 请求合并。日常操作中我基本遵循这个流程：从 main 拉分支，写完代码提交，推到远程，创建 PR，在 Gitee 上做代码评审，确认合并。这套流程对个人项目也适用，只不过省略评审环节，但分支的隔离价值仍然存在——在 main 上直接改动一旦写崩，恢复成本比分支高得多。
6. 常见问题与排查技巧实录
实操中总有各种意外，这里挑几个我被问得最多、自己也踩过的问题，逐一分析原因和解决办法。
6.1 git did not exit cleanly 报错
用 TortoiseGit（俗称小乌龟）或者部分 GUI 工具推送时，容易遇到 “git did not exit cleanly (code 1)” 之类的报错。这类报错本身信息量很少，因为 GUI 工具只是把 git 命令的输出原样展示出来，真正的原因要看它前面的详细输出。常见原因包括：
- 没有配置用户名邮箱
- remote 地址错误或仓库不存在
- 本地分支和远程分支无关联（首次推送没加
-u） - 远程仓库有本地没有的提交（比如 Gitee 上用网页新建了 README）
排查方式很简单：在项目目录打开终端，手动执行一次 git push，看真实报错。比如远程仓库有新增提交时，Git 会提示 “hint: Updates were rejected because the remote contains work that you do not have locally”，这时先 git pull --rebase 拉取合并，再推送。GUI 工具只是包装了一层，底层还是 git 命令，手动执行往往更容易定位问题。
6.2 ‘git’ 不是内部或外部命令
Windows 下敲 git 命令提示找不到，多半是安装时 PATH 没配置好，或者安装完没重开终端。检查方式：先到 Git 安装目录确认 git.exe 是否存在，再查看系统环境变量 PATH 中有没有把 Git 的 bin 目录加进去。安装包正常情况下会自动配置，如果被第三方安全软件拦截了，需要手动添加：
- 右键“此电脑” -> 属性 -> 高级系统设置 -> 环境变量
- 在系统变量里找到 Path，编辑并新增一行，填 Git 的安装路径，例如
C:\Program Files\Git\bin - 保存后重新打开终端
这个操作对我来说几乎没有遇到过，但帮别人排查时见过几次。安装 Git 时多留意 PATH 选项，就不会省事反费事。
6.3 推送时报权限问题（Permission denied）
推送时提示 Permission denied (publickey)，通常说明 SSH 私钥没生效或没有匹配的公钥。排查顺序：
bash复制# 1. 确认当前 remote 是 SSH 地址
git remote -v
# 2. 测试 SSH 连接
ssh -T git@gitee.com
# 3. 查看私钥是否被加载
ssh-add -l
如果 ssh-add -l 输出 “The agent has no identities”，说明 ssh-agent 没加载私钥。macOS/Linux 下执行：
bash复制eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
Windows Git Bash 类似。另外还有个容易被忽略的坑：.ssh 目录或私钥文件权限过大，SSH 会出于安全考虑拒绝使用。Linux/macOS 下执行：
bash复制chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
权限改完后再重新测试 ssh -T git@gitee.com。这套排查顺序基本覆盖了九成以上的权限问题。
6.4 误提交大文件导致推送失败
向 Gitee 提交一个超过 100MB 的单个文件，推送时会被拒绝。Gitee 对仓库体积有明确限制，单个文件过大是常见触发场景。解决方式是先把大文件从版本历史中剔除，再推送。但这里有个很难受的现实：如果这个大文件在历史提交里，后续提交也无法绕过服务端校验，除非用 git filter-branch 或者 BFG 工具重写历史，步骤相当复杂。
更实用的做法是从源头避免：不要把依赖包、编译产物、数据集这类大文件放仓库里，而是在项目根目录创建 .gitignore，把这些路径忽略掉。.gitignore 的基本写法：
gitignore复制# 依赖目录
node_modules/
target/
# 编译产物
dist/
build/
# 日志与临时文件
*.log
.DS_Store
.gitignore 要放在仓库根目录，提交时生效。已经误提交的文件，即使写了 .gitignore 也不会被自动忽略，需要先用 git rm --cached 从暂存区移除再重新提交。我自己新建项目的第一步永远是先写 .gitignore，这比事后清理省心太多。
6.5 Gitee Pages 没了怎么办
搜 Gitee 相关话题时，经常能看到有人问“Gitee Pages 是不是不能用了”。Gitee Pages 的功能策略时有调整，个人项目的静态托管不时出现服务状态变化。这里不展开讨论具体政策，只是说一句：如果你之前用 Gitee Pages 做个人站点，遇到服务不可用时，可以先把静态站托管到本地测试，再找其他可替代的静态托管方案。Gitee 仓库本身存代码的能力不受影响，Git 推送、拉取、分支等功能照常使用。
6.6 大文件与 LFS 选型
项目里出现几百 MB 的大文件，比如美术资源、数据集，就算没超限制，每次克隆都会变慢。Gitee 提供 LFS（Large File Storage）支持，可以把大文件单独存储，仓库里只保留指针文件，克隆时按需拉取。如果项目有此类需求，可以在仓库设置里开启 LFS，然后本地安装对应 LFS 客户端，将大文件路径纳入 LFS 跟踪。不过这属于进阶用法，如果项目里大文件不多，优先考虑 .gitignore 排除，避免引入额外复杂度。
7. 项目托管习惯：从上传到协作
把所有坑踩完、命令跑顺之后，我想分享几个自己的日常用法，让这套 Git + Gitee 的组合真正提升效率。
第一，频繁提交。 不要等到一个功能写完才 commit。每完成一个可编译、可运行的小步骤，就提交一次。commit 信息写清楚这一步做了什么。这样回滚时可以精确到细粒度操作，而不是只能回到“上次完整功能”这个粗粒度节点。
第二，用分支隔离风险。 我试过在 main 上写新功能，写着写着发现方案不对，想抛弃改动却发现和之前的提交混在一起，不好分离。后来改成从 main 拉 feature 分支，实验代码放在 feature 分支上，main 始终保持可发布状态，方案废弃就删 feature 分支，干净利落。这个习惯在多人协作时尤其重要，在个人项目里也能避免很多自我干扰。
第三，善用 Gitee 的 issue 和 PR。 个人项目虽然用不到严格的评审流程，但 issue 记得记一下待办事项、已知 bug、优化点，比写在本地 TODO 文件里强。PR 功能则可以帮你看到自己分支和 main 的差异，回顾改动时特别直观。我在做稍大一点的项目时，即使只有一个人在开发，也会走“分支开发 + PR 合并”这套流程，等于给关键节点留了个审查存档。
第四，定期拉取保持同步。 如果同时在多台电脑上开发，每天开始工作前先 git pull，结束时记得 git push。这个习惯看似简单，但真正坚持下来，能避免绝大多数合并冲突。冲突不是不可解决，但能避免就避免，毕竟解决冲突的时间本来可以拿去写代码。
第五，给提交打标签。 项目发布版本时，在 Gitee 上可以给提交打 release 标签。标签像时间胶囊，标出“这个节点是 v1.0.0”“这个节点是 v2.1.3”，后续想比对版本差异时直接看标签范围。执行命令：
bash复制git tag v1.0.0
git push origin v1.0.0
打标签的本质是给特定提交一个易于记忆的名字，配合 git diff v1.0.0 v2.1.3 可以清晰看到两个版本之间改了什么。
个人体会是，Git 的入门门槛并不高，核心命令就那几条，真正需要的是“持续使用 + 遇到问题能自己排查”的能力。Gitee 作为国内仓库托管平台，速度、稳定性对国内用户都很友好，对个人开发者来说完全够用。把基础流程跑通之后，再逐步进阶到 rebase、cherry-pick、submodule 这些高级操作时，你会发现一切都建立在理解“本地仓库和远程仓库如何交互”这个基本模型之上。希望这篇指南能帮你少走弯路，顺利把第一个仓库推上去，然后放心大胆地开始用版本管理写代码。