“很多人学 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 Gits 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 gitCentOS/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 而不是 HTTPSGitee 支持两种远程仓库协议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 gitgitee.com首次连接会提示确认指纹输入yes回车。如果看到 “Hi xxx! Youve 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 gitgitee.com这次就应该通了。3.5 SSH 认证失败的排查顺序我把常见失败情况列成一个顺序表遇到问题按这个顺序查基本能定位Permission denied (publickey)—— 公钥没匹配上。先确认公钥是否贴到了 Gitee再确认~/.ssh/config里的IdentityFile路径对不对。Connection refused或Connection timed out—— 网络或端口问题。Gitee 一般默认端口 22如果公司网络封了 22 端口可以试试 443 端口ssh -T -p 443 gitgitee.com同时把 config 里的Port也改成 443Git 命令就都能走 443 了。确认你复制的是.pub公钥而不是私钥内容。确认没有把其他平台的公钥粘到 Gitee 上——我见过有人把 GitHub 的公钥粘到 Gitee自然连不上。macOS/Linux 下检查私钥文件权限chmod 600 ~/.ssh/gitee_ed25519权限太宽 SSH 会拒绝使用。这一关过了后面推送就一路畅通了。4. 本地项目纳管初始化、关联远程与首次推送4.1 先判断你的场景本地项目纳管最常见的就两种场景场景 A本地已经有一堆代码想交给 Gitee 管理。场景 BGitee 仓库已经建好可能勾选过 README要把仓库内容拉到本地再把项目代码放进去。两种场景的操作路径不同很多教程混在一起讲新手容易绕晕。下面分开说。4.2 场景 A本地已有项目的完整流程进入项目目录执行cd 你的项目目录 git init git add . git commit -m feat: 初始化项目 git branch -M main git remote add origin gitgitee.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 场景 BGitee 仓库已有内容怎么处理如果你创建仓库时勾选了 README 或许可证Gitee 仓库不是空的。此时如果你还用上面的流程git push会报错提示远端有当前分支没有的提交让你先拉取。处理方式有两个。第一个是创建仓库时什么都不初始化让仓库彻底为空然后走场景 A 的流程这是最省心的方式。第二个是仓库已经初始化了需要先把远端内容拉下来合并git init git remote add origin gitgitee.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 gitgitee.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修复 bugdocs文档变更style代码格式调整refactor重构不改变外部行为test测试相关chore构建/工具/依赖等杂项示例feat(login): 增加短信验证码登录。写描述的核心是写为什么改而不是只写改了什么。比如fix: 修正分页查询空指针异常比fix: 修改代码有用十倍。提交信息是写给未来的自己看的包括你自己在内的所有协作者都会感谢你写清楚。5.2 git commit --amend修正上一次提交的正确姿势如果刚提交完就发现注释写错了、某个文件漏提交了、或者想合并两次小提交而且这个提交还没有推送到远程就可以用 amendgit 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 仓库建好了但代码推不上去”把这篇文章转给他多半就能少走很多弯路。