“很多人学 Git，第一步就是去 Gitee 注册个账号、点几下创建一个仓库，然后再在电脑上装一个 Git，接着就卡住了：本地项目到底怎么和远程仓库建立联系？我也卡过这一步。等我完整走了一遍才发现，整个流程的核心其实只有三段——网页端把仓库地址准备好、本地把 Git 环境配好、最后用几条命令把代码推上去。这篇就围绕 Gitee 仓库创建与本地项目纳管，把这套流程从头到尾写透，并把我踩过的一些坑一并说清楚。
1. 为什么选 Gitee：平台选择与创建仓库前的准备
1.1 先想清楚：你的仓库是给谁看的
不少新手第一次建仓库，脑子一热就选了“公开”，结果当天晚上代码就被搜索引擎收录了。虽然这不一定是坏事，但如果你只是练习、或者代码里有数据库密码、API Key，后续会很麻烦。我的建议是：学习阶段一律建私有仓库，等你真的想开源了，再在仓库设置里改成公开，或者重新建一个公开仓库。Gitee 的私有仓库完全免费，这一点对新手非常友好。
还有一个现实问题：访问速度。如果代码托管在境外平台，有些网络环境下 clone 和 push 经常超时，体验很不好。Gitee 是国内平台，访问速度稳定，中文界面，文档和社区也都是中文的，对刚接触 Git 的人非常友好。所以如果你在国内，把 Gitee 作为第一个托管平台是比较稳妥的选择。
1.2 注册、实名与账号安全设置
注册 Gitee 账号很简单，用手机号收个验证码就能完成。但有一个经常被忽略的关键步骤：实名认证。如果你以后想用 Gitee Pages 部署个人网站，实名认证是前置条件。虽然也可以先跳过，但我建议注册完就顺手做掉，不然后面要用的时候又得停下来等审核。认证一般几分钟就通过，基本不影响当天使用。
另外建议把邮箱也绑定好。Gitee 在“设置 → 邮箱管理”里允许你添加多个邮箱，本地 Git 提交时用的邮箱只要在这里登记过，提交记录就能关联到你的 Gitee 账号和头像。这个小细节很多人不知道，我一开始也没关联，提交记录上显示的是一个随机图标，后来才发现是邮箱没对上。
1.3 创建仓库：每个选项到底该怎么填
点击“创建仓库”后，你会看到几个选项。仓库名称最好是英文小写、用短横线分隔，比如my-first-project，不要用中文、不要用驼峰命名。这会影响 clone 地址的观感和后续路径的兼容性。描述随手写一句“做什么的”就行，不填也没关系。
然后是可见性，我前面说了，练习就选私有。下面有个“初始化的文件”区域，常见选项是 README、.gitignore 模板、开源许可证。我的建议很直接：如果不是特别清楚自己要什么，就什么都不要勾选，直接创建。原因后面第 4 章会详细讲——本地项目纳管时，远端仓库如果有 README，会和本地代码产生“合并不相关的历史”问题，新手处理起来很焦虑。空仓库创建完，后面所有操作都更顺。
1.4 开源许可证到底选哪个
很多人在创建仓库时卡在许可证这一项。我的选择逻辑很简单：不是律师就选最主流的。下面是几个常见许可证的核心区别：
| 许可证 | 宽松程度 | 主要约束/特点 | 适合场景 |
|---|---|---|---|
| MIT | 最宽松 | 几乎无限制，保留版权声明即可 | 个人项目、工具库、学习代码 |
| Apache-2.0 | 宽松 | 需保留声明，含专利授权条款 | 开源库/SDK、公司开源项目 |
| GPL-3.0 | 严格 | 衍生作品必须同样开源 | 希望代码永远保持开源的软件 |
| BSD-3-Clause | 宽松 | 类似 MIT，额外禁止用作者名义背书 | 学术/研究项目 |
如果你只是写自己的工具、练习代码，选 MIT 就够了。如果未来想被大公司用进商业项目，Apache-2.0 更合适。如果希望别人改完你的代码也必须开源，那就选 GPL-3.0。选错了也不用慌：许可证本质上是一个叫LICENSE的文件，直接在仓库里改掉、重新提交一次，新的版本就生效了，历史记录里保留着旧的，解释得清就行。
2. Git 安装：从官网下载到能跑通第一条命令
2.1 Windows 安装的关键选项
Windows 安装 Git 很简单，到 Git 官网下载对应版本的.exe，双击一路“Next”基本能装完。但有三个选项我建议认真看：
- 默认编辑器：如果电脑上装了 VS Code，建议选 “Use Visual Studio Code as Git's default editor”，比默认的 Vim 友好太多。不然后面写提交信息或改配置时弹出一个 Vim，新手很可能不知道怎么退出。
- PATH 环境变量：这个必须选第二项 “Git from the command line and also from 3rd-party software”。这样才能在 CMD、PowerShell 和 IDE 的终端里直接使用
git命令。 - 换行符转换：Windows 版默认会帮你把
LF换成CRLF，大多数教程也推荐默认。但我个人建议选 “Checkout as-is, commit as-is”，也就是不转换。团队协同时换行符问题很难排查，从一开始就统一用LF会省掉很多麻烦。如果你已经在默认模式下了，想改也可以，只是注意历史提交的换行符已经定型了，别回头去“修复”，水很深。
装完打开一个终端，输入git --version，能看到版本号就说明成功了。
2.2 macOS 和 Linux 的安装方式
macOS 可以直接用 Homebrew 安装：brew install git。如果你已经装了 Xcode 的命令行工具，系统自带 git，但版本比较旧，建议还是用 brew 装新版。Linux 的 Debian/Ubuntu 系用sudo apt install git，CentOS/RHEL 系用sudo yum install git。有的发行版软件源里的 Git 版本较老，如果你发现某些新命令不支持，就从源码编译或者添加官方 PPA 安装新版本，具体方法按系统查一下即可。
2.3 装完必须先做的一件事：全局身份配置
Git 的提交日志里会记录“谁在什么时候做了什么”，它读取的是你本地的user.name和user.email，跟 Gitee 账号没有自动绑定关系。所以装完 Git 第一件事是配置身份：
git config --global user.name "你的名字" git config --global user.email "你的邮箱"这里的邮箱建议用你在 Gitee 邮箱管理里登记过的那个。这样做的好处很明显：提交记录能在 Gitee 上正确关联到你的头像，看起来更专业，也能帮你追踪每次提交是谁做的。配置完了可以查看一下：git config --global --list，确认两项都对。
2.4 顺手处理一个 Git Bash 的报错
Windows 下偶尔会看到git open /dev/null or dup failed: no such file or directory，这个报错常见于 Git Bash 在某些终端环境下启动时文件句柄异常。处理方法一般是：重新打开 Git Bash、换个工作目录，或者以管理员身份运行一次。如果你是在 IDEA 里遇到这个报错，把内置终端从 Git Bash 切成 CMD 或 PowerShell 也能绕过。这个报错不影响仓库数据，不用慌。
3. SSH 密钥配置：免密推送的关键一步
3.1 为什么推荐 SSH 而不是 HTTPS
Gitee 支持两种远程仓库协议：HTTPS 和 SSH。HTTPS 的缺点是每次 push 都要输入用户名和密码（或者是私人令牌），虽然可以配置凭证管理器记住，但第一次配置也比较绕。SSH 的优势是一次生成密钥、配置好后永久免密。日常开发频繁推送，用 SSH 会舒服很多。而且 SSH 在部分网络环境下比 HTTPS 更稳定，不会总被某些认证弹窗打断。
3.2 生成密钥：一条命令解决
推荐用ed25519算法，安全性高、密钥短、生成快。命令如下：
ssh-keygen -t ed25519 -C "你的邮箱" -f ~/.ssh/gitee_ed25519参数含义：-t指定算法，-C是注释，一般写邮箱方便自己辨认，-f指定生成的文件名。如果不指定-f，默认会在~/.ssh/id_ed25519，如果你电脑上已经有别的平台的 SSH 密钥，我建议单独给 Gitee 生成一个gitee_ed25519，避免混用。生成过程中会提示设置密码短语（passphrase），直接留空回车即可。如果是旧系统或者某些网络环境不支持 ed25519，也可以用ssh-keygen -t rsa -b 4096 -C "你的邮箱" -f ~/.ssh/gitee_rsa。
生成完会在目录下看到两个文件：gitee_ed25519（私钥）和gitee_ed25519.pub（公钥）。私钥永远不要发出去，公钥随便给谁看都没事。
3.3 把公钥添加到 Gitee
先查看公钥内容：
cat ~/.ssh/gitee_ed25519.pub会显示一行以ssh-ed25519开头的内容，把这一整行复制下来。然后进入 Gitee → 头像 → 设置 → 安全设置 → SSH 公钥，标题写一个容易认的名字，比如 “我的Windows笔记本”，粘贴公钥后保存。Gitee 支持一个账号添加多个公钥，不冲突。
3.4 验证连通性和多密钥时的 config 配置
测试命令：
ssh -T git@gitee.com首次连接会提示确认指纹，输入yes回车。如果看到 “Hi xxx! You've successfully authenticated, but GITEE.COM does not provide shell access.”，说明配置成功。注意这个提示不是错误，是正常的，因为 Git 服务器本来就只接受 Git 命令，不提供 shell。
如果你按建议生成了单独的文件名（如gitee_ed25519），还需要在~/.ssh/config里告诉 Git 用哪把密钥访问 Gitee，否则 SSH 默认只会找id_ed25519或id_rsa，这就是很多人明明把公钥贴到位了却一直认证失败的真正原因。在~/.ssh目录下新建一个config文件（没有后缀名），写入：
Host gitee.com HostName gitee.com User git Port 22 IdentityFile ~/.ssh/gitee_ed25519保存后再跑一次ssh -T git@gitee.com，这次就应该通了。
3.5 SSH 认证失败的排查顺序
我把常见失败情况列成一个顺序表，遇到问题按这个顺序查，基本能定位：
Permission denied (publickey)—— 公钥没匹配上。先确认公钥是否贴到了 Gitee，再确认~/.ssh/config里的IdentityFile路径对不对。Connection refused或Connection timed out—— 网络或端口问题。Gitee 一般默认端口 22，如果公司网络封了 22 端口，可以试试 443 端口：
同时把 config 里的ssh -T -p 443 git@gitee.comPort也改成 443，Git 命令就都能走 443 了。- 确认你复制的是
.pub公钥，而不是私钥内容。 - 确认没有把其他平台的公钥粘到 Gitee 上——我见过有人把 GitHub 的公钥粘到 Gitee，自然连不上。
- macOS/Linux 下检查私钥文件权限，
chmod 600 ~/.ssh/gitee_ed25519，权限太宽 SSH 会拒绝使用。
这一关过了，后面推送就一路畅通了。
4. 本地项目纳管：初始化、关联远程与首次推送
4.1 先判断你的场景
本地项目纳管，最常见的就两种场景：
- 场景 A：本地已经有一堆代码，想交给 Gitee 管理。
- 场景 B：Gitee 仓库已经建好（可能勾选过 README），要把仓库内容拉到本地，再把项目代码放进去。
两种场景的操作路径不同，很多教程混在一起讲，新手容易绕晕。下面分开说。
4.2 场景 A：本地已有项目的完整流程
进入项目目录，执行：
cd 你的项目目录 git init git add . git commit -m "feat: 初始化项目" git branch -M main git remote add origin git@gitee.com:你的用户名/仓库名.git git push -u origin main逐步解释一下每条命令的作用：
git init：把当前目录变成一个 Git 仓库，会产生一个隐藏的.git目录，里面存放版本信息。只执行一次，不要重复执行。git add .：把当前目录下所有文件加入暂存区。要注意的是.代表当前目录，如果你有不该提交的文件（后面第 6 章讲.gitignore），这里就会一并加进去。git commit -m "..."：把暂存区内容提交成一次版本记录。提交信息我会在第 5 章细讲。git branch -M main：把本地分支重命名为main。因为 Git 默认初始分支可能是master，而 Gitee 新建仓库默认分支一般叫main，不改的话后面推送容易出问题。git remote add origin ...：给远程仓库地址起一个别名origin，以后用origin代替完整地址。执行一次就行，重复执行会报remote origin already exists。git push -u origin main：把本地main分支推送到远程，并用-u建立本地分支和远程分支的跟踪关系。以后直接执行git push就能推，不用再带参数。
推完之后，打开 Gitee 仓库页面刷新，代码应该已经出现在上面了。
4.3 场景 B：Gitee 仓库已有内容怎么处理
如果你创建仓库时勾选了 README 或许可证，Gitee 仓库不是空的。此时如果你还用上面的流程，git push会报错，提示远端有当前分支没有的提交，让你先拉取。
处理方式有两个。第一个是：创建仓库时什么都不初始化，让仓库彻底为空，然后走场景 A 的流程，这是最省心的方式。第二个是：仓库已经初始化了，需要先把远端内容拉下来合并：
git init git remote add origin git@gitee.com:你的用户名/仓库名.git git pull origin main --allow-unrelated-histories这里--allow-unrelated-histories允许 Git 合并两个没有共同历史提交的仓库（本地仓库和远端空仓库算“不相关历史”）。合并后可能会有冲突（比如 README 内容和本地已有的 README 不一致），手动解决冲突后，再git add . && git commit -m "merge: 合并远端初始文件" && git push -u origin main。
另外，如果 Gitee 仓库里已经有完整项目，你想要的全部是远端内容，那直接用 clone 把仓库拉到本地：
git clone git@gitee.com:你的用户名/仓库名.git cd 仓库名clone 之后，本地会自动建立好远程跟踪分支和 origin 地址，你只需要在项目目录里正常 add、commit、push 即可。IDEA 里新建项目时选 “Get from VCS”，本质也是在执行 clone，填入同样的仓库地址就行。
4.4 首次推送后必做的三件检查
第一次推送成功之后，别急着关终端，先做三件事：
- 在项目目录执行
git status，确认工作区是干净的（显示 nothing to commit, working tree clean）。 - 执行
git log --oneline，查看提交历史和刚写的 commit message 是否正确。 - 浏览器刷新 Gitee 仓库页面，确认文件、提交记录、时间都正常。
这三步能在问题刚出现时就发现，而不是等第二天同事告诉你仓库是空的。
5. 日常开发高频操作：提交、修正与分支协作
5.1 提交信息怎么写才不后悔
很多人的 commit message 清一色写着 “修改”、“更新”、“fix bug”，过两周再看根本不知道当时改了什么。我现在的习惯是遵循 Conventional Commits 的格式：
<type>(<scope>): <description>常用 type 含义：
| type | 含义 |
|---|---|
| feat | 新功能 |
| fix | 修复 bug |
| docs | 文档变更 |
| style | 代码格式调整 |
| refactor | 重构（不改变外部行为） |
| test | 测试相关 |
| chore | 构建/工具/依赖等杂项 |
示例：feat(login): 增加短信验证码登录。写描述的核心是写为什么改，而不是只写改了什么。比如fix: 修正分页查询空指针异常比fix: 修改代码有用十倍。提交信息是写给未来的自己看的，包括你自己在内的所有协作者都会感谢你写清楚。
5.2 git commit --amend：修正上一次提交的正确姿势
如果刚提交完就发现：注释写错了、某个文件漏提交了、或者想合并两次小提交，而且这个提交还没有推送到远程，就可以用 amend：
git add 漏掉的文件 git commit --amend --no-edit--no-edit表示不修改提交信息，只是补充内容。如果想改提交信息：
git commit --amend -m "feat: 新的提交说明"注意 amend 会用一个新的提交替换掉原来的提交，commit ID 会变。所以核心原则是：只 amend 自己本地没推过的提交。如果已经 push 到公共分支，就别用 amend 了，会让协作者的历史出现分叉，处理起来非常痛苦。
5.3 revert 与 reset：两种完全不同的回滚
回滚是新手最高频的诉求。推荐把这两条命令分清楚：
git revert：生成一次“反向提交”，把某次提交的改动撤销，但保留历史记录。它不删除提交，只是新增一条“撤销上一次”的提交。适合已推送到远程的分支，安全。git revert HEADgit reset：移动 HEAD 指针，把提交从历史上拿掉。适合本地还没推送的提交。有几种模式：git reset --soft HEAD~1 # 提交没了，但改动留在暂存区 git reset HEAD~1 # 默认模式，改动保留在工作区 git reset --hard HEAD~1 # 改动全部丢弃，危险
--hard会把未提交的工作区内容一起丢掉，执行前务必确认。我的建议是：公共分支用 revert，本地私人分支用 reset。这样既安全又灵活。
5.4 fetch 与 pull：很多人一直分不清
核心区别一句话：git fetch只把远端的新提交下载到本地，不会动你的工作区；git pull是fetch + merge，直接把远端提交合并到当前分支。大多数情况下你确实想用 pull，因为它一步到位。但当你只想看看远端有没有新东西、暂时还不想合并时，先git fetch再git log origin/main查看差异，是更稳妥的做法。
另外，很多人 pull 后会莫名其妙多一个 merge commit，这是git pull默认执行 merge 造成的。如果你希望历史干净一些，可以执行：
git pull --rebase这个命令的本质是先把本地提交“挪走”，拉取远端提交后再把本地提交重放上去，历史会是一条直线。团队协作中这个习惯比较实用。
5.5 merge 与 rebase：合并代码的两种思路
合并分支是日常开发躲不开的操作。git merge会把目标分支的提交和当前分支合并，产生一个 merge commit，保留分支分叉的结构。git rebase则是把当前分支的提交“摘下来”，整体重放到目标分支的最新提交之后，历史看起来是线性的。
我的使用经验：
- 个人功能分支：多用 rebase。比如开发到一半，发现主分支提交了新功能，执行
git rebase main，你的提交会干净地放在主分支最新提交之后，后期合并回来很清爽。 - 公共分支、需要保留真实合并线的场景：用 merge。比如你把 feature 分支合并回 dev 时，用
git merge feature，所有人看到的就是一次清晰的分支合并。
别再问哪个更好，核心准则是：共享分支不要 rebase，私有分支随便 rebase。在 IDEA 里合并分支的按钮，本质上执行的就是git merge，理解这一点后，命令行和图形工具对你来说就完全互通了。
6. 别让垃圾文件进仓库：.gitignore 写法和失效排查
6.1 没有 ignore 文件会怎样
如果你不做任何过滤，git add .会把当前目录下所有文件加进去。一个 Java 项目可能带target/目录，一个 Node 项目可能带node_modules/，一个 Python 项目可能出现__pycache__/。这些目录动辄几百 MB，一旦推上去，别人的 clone 速度会变得极慢，而且这些文件每次构建都会变，产生大量无意义的提交记录。
创建 Gitee 仓库时，初始化区域可以勾选.gitignore模板（里面按语言分类好了），但如果你已经创建了仓库，或者项目里混用了多种语言，还是自己写一个比较靠谱。
6.2 .gitignore 常用规则速查
# 忽略目录 node_modules/ target/ dist/ # 忽略特定类型文件 *.log *.tmp # 忽略根目录下特定文件（/ 表示从仓库根目录开始匹配） /.idea/ /.env # 例外规则：强制跟踪某个被忽略的文件 !important.log # 多级目录匹配 **/build/几个容易忽略的细节：规则中的/开头表示只匹配仓库根目录下的路径；目录名后面加/表示忽略整个目录；*表示任意字符但不跨目录，**可以跨目录。如果只是凭印象写，很可能出现“我想忽略根目录的 build，但把所有 build 都忽略了”的情况。
6.3 写了 .gitignore 却不生效的真正原因
这是新手最容易卡住的点：明明.gitignore里写了node_modules/，git status还是能看到它。原因在于：.gitignore只对未被 Git 跟踪（tracked）的文件生效。如果你的文件之前已经被git add提交过，Git 已经把它纳入了版本管理，之后写 ignore 规则是不会让它“消失”的。
解决办法是把这些文件从 Git 索引中移除，但保留在磁盘上：
git rm -r --cached node_modules git add . git commit -m "chore: 移除已跟踪的构建产物目录"之后node_modules/就会被正常忽略了。--cached是关键，它只从索引移除，不会删除你磁盘上的实际文件。合并代码前和写.gitignore后，最好各跑一次git status检查，别等到 push 之后才在 Gitee 网页上发现一堆不该存在的文件。
7. 提交之后还能玩什么：Gitee Pages 与仓库的进阶用法
7.1 Gitee Pages：把仓库变成可访问的网页
仓库代码推上去之后，Gitee 还有一个很实用的功能叫“Gitee Pages”，能把仓库里的静态文件部署成一个可访问的网站。前提是账号已完成实名认证。操作路径：仓库页面 → 服务 → Gitee Pages，选择部署分支和目录（一般是main分支、/根目录，或者你放静态文件的/docs目录），然后启动即可。
我常用它来做个人简历页面和项目文档站。如果你用 VuePress、Hexo、Hugo 这类静态站点生成器写博客，生成的静态文件推到 Gitee 仓库，也能通过 Pages 访问。要注意的是，免费版 Gitee Pages 在更新代码后，需要手动去页面点一下“更新”，不会自动触发重新部署。这个我一开始不知道，改了代码怎么都看不到效果，折腾了半小时才反应过来。
7.2 用 Issues 和 PR 把一个私有仓库变成开源项目
如果你把自己练习的一个小工具仓库改成公开，别人就能看到、Star、Fork、提交 Issue、发起 Pull Request。这套协作模式是 Git 托管平台的核心价值。Issue 用来报告 bug 或建议功能，PR 用来贡献代码。第一次收到陌生人的 PR 时还挺有成就感的，这也算把“仓库纳管”这件事从个人管理升级到了社区协作。
7.3 几个很实在的习惯
最后分享几个我长期使用下来的习惯：
- 本地和 Gitee 各保留一个备份：即使不是为了协作，把代码放到远端也能防本地磁盘损坏。
- 每个仓库写一个像样的 README：说明这个项目是什么、怎么运行、依赖什么，这不仅是给别人看的，也是给两个月后的自己看的。
- 提交前养成
git status的习惯：先看改动范围对不对，再git add，避免把不该提交的文件混进去。 - 定期
git remote -v检查远端地址：换了仓库地址后容易忘记 update，检查一下能少很多麻烦。
按这套流程走下来，你其实已经掌握了一个 Git 用户日常 90% 的操作。刚开始不熟悉的命令可以随时翻git help，或者用git status看提示，Git 的提示信息写得很清楚，出错了一般都会告诉你下一步该干嘛。
我自己的体会是，这套流程里最值得慢慢研究的其实是第 3 章的 SSH 配置和第 5 章的提交/回滚操作，这两个阶段直接决定了你之后用 Git 是顺畅还是难受。如果你身边也有人卡在“Gitee 仓库建好了但代码推不上去”，把这篇文章转给他，多半就能少走很多弯路。
