1. 项目全貌从零到一跑通 Gitee 托管流程这个项目虽然看起来只是几个命令的组合但它其实是每个开发者都必须掌握的核心基本功在 Gitee 远程仓库上完成托管代码的完整闭环。从注册账号、配置 SSH 公钥、新建远端仓库到初始化本地仓库、git push、git pull这一整套流程跑通了你才真正拥有了与远程仓库协作的能力。先说说这套流程能解决什么问题。代码放在本地最大的风险就是电脑坏了、文件误删了、或想在其他设备上继续开发时抓瞎。而放到 Gitee 远程仓库之后代码有了云端备份团队协作也有了统一的中转站。无论你是 solo 开发者想给自己留个备份还是刚进团队需要提交代码的新人这套流程都是必修课。我见过不少朋友第一次上手时心态是这样的知道 Git 很重要但不知道从哪一步开始跟着网上的教程敲了几条命令不是这里报错就是那里 403好不容易 push 上去了pull 的时候又闹出冲突。这其实非常正常因为这些操作背后有一套逻辑和约定不了解这些约定命令就像咒语一样难记又难调。所以这篇文章不打算只把命令列一遍就完事。我会把每一步都拆开讲清楚为什么要这样做、底层发生了什么、常见的坑在哪、出现了报错怎么排查。读完你不会只是“照着敲了一遍”而是真正理解了这套工作流下次遇到问题自己能判断和解决。整篇文章适合三类读者。第一类是刚接触 Git 的初学者可以按顺序从头到尾跟着操作。第二类是已经在用但偶尔犯迷糊的开发者可以直接跳到“常见问题”和“实操心得”部分很多坑都是我实际踩过的。第三类是想给团队规范工作流的同学文末会讲分支命名、提交信息规范等进阶内容可以直接拿来落地。2. 环境准备与基础配置先把地基打好2.1 注册 Gitee 账号并完成实名认证去 Gitee 官网注册账号这一步没什么难度但有几个细节会影响后续的使用体验。注册时填写的用户名会出现在你的仓库地址里比如gitgitee.com:用户名/仓库名.git这个用户名最好跟你日常使用的 ID 一致不然日后在多个系统之间切换容易混。邮箱建议填自己常用的邮箱它会被用来关联提交记录。很多新人会随手填一个临时邮箱结果后续无法接收平台的通知或者提交记录跟账号对不上保存好登录凭证。注册完成后进入“设置 - 安全设置 - 实名认证”把认证做了否则新建仓库等操作会比较麻烦。2.2 安装 Git 并完成用户信息配置Gitee 账号注册好之后本地要装 Git。Linux 装包、macOS 用 Homebrew、Windows 直接下载安装包这些基础操作就不展开了。装完以后打开终端先验证版本git --version接着配置用户名和邮箱。注意这里配置的用户名和邮箱是为了让 Git 在生成提交记录时知道“这行代码是谁写的”跟 Gitee 账号的用户名和邮箱不一定完全一致但最好保持一致这样 Gitee 能把提交记录正确关联到你的账号上。我基本上会用同一个邮箱避免后续统计 contribution 时出现找不到人的情况。git config --global user.name 你的用户名 git config --global user.email 你的邮箱配置完成后可以用下面命令确认git config --global --list2.3 为什么优先选择 SSH 方式而不是 HTTPS这个项目标题里明确提到了“配置 SSH 公钥”说明走的是 SSH 协议。很多人会有疑问HTTPS 方式不也可以 push 吗为什么非要配 SSH这背后的考量值得多说几句。HTTPS 方式每次 push 都需要输入 Gitee 的用户名和访问密码。如果开了双重认证密码还需要换成私人令牌Personal Access Token体验比较繁琐。SSH 方式的核心优势在于当你把公钥放到 Gitee 账号之后本地再 push、pull、clone 时就不需要反复输入账号密码了身份验证由密钥对自动完成。日常开发中高频操作就是 commit、push、pull少输一次密码就会少很多摩擦。另外从原理层面说SSH 是一种加密网络传输协议它用一对密钥来保证连接的安全性私钥保存在本地注意不要泄露给任何人公钥可以公开放到 Gitee 服务器上。客户端发起连接时服务器会验证你有没有对应的私钥验证通过才允许操作。这比明文发送账号密码的方式更安全也更适合自动化任务和脚本调用。提示如果你的网络环境比较特殊SSH 默认的 22 端口可能连不通这种情况可以把 SSH 服务端口改为 443 或 80 再试细节在后面的常见问题里展开。3. SSH 公钥配置核心中的核心卡住最多人的一步3.1 检查是否已有 SSH 密钥对很多人一上来就生成新密钥结果把原来的密钥覆盖了后面其他平台跟着遭殃。生成之前先检查本地有没有现成的密钥ls -la ~/.ssh如果看到id_rsa和id_rsa.pub说明已经存在密钥对。id_rsa是私钥id_rsa.pub是公钥。也可以把已有的公钥内容直接加到 Gitee 上不需要重新生成。如果之前生成密钥时设置了 passphrase那么在 Gitee 上使用时会提示输入这个密码用的也是原密码。如果目录为空或者没有这两个文件那就需要生成新的密钥对。生成时建议用邮箱做注释标识这样以后在多个平台、多台设备之间可以轻松认出这把钥匙是谁的ssh-keygen -t rsa -b 4096 -C 你的邮箱执行后系统会询问保存位置和 passphrase。保存位置保持默认按回车就行。passphrase 是给私钥再加一道密码保护如果设置了每次使用私钥都要输入一次每次 push 时会比较烦。个人电脑这种私密环境可以留空公司电脑或公用电脑建议设置安全第一。我的做法是个人笔记本留空工作电脑设置 passphrase安全和便利各取一半。3.2 查看并复制公钥内容生成完成后查看公钥内容cat ~/.ssh/id_rsa.pub输出通常类似ssh-rsa AAAAB3NzaC1.... 你的邮箱这么一串。复制的时候要用鼠标完整选中不要多选空格也不要漏掉最后的邮箱部分。Windows 上可以用type %USERPROFILE%\.ssh\id_rsa.pub查看macOS 可以用pbcopy ~/.ssh/id_rsa.pub直接复制到剪贴板非常方便。3.3 在 Gitee 后台添加公钥登录 Gitee进入“设置 - SSH 公钥”把刚才复制的公钥粘贴进去标题可以自定义比如“我的笔记本”、“公司电脑”。给你一个关键的建议在不同的设备上使用不同的标题这样哪天某个密钥泄露或者你想撤销某台设备的权限可以在后台单独删除不需要把全部密钥都换掉。添加成功之后Gitee 会提示“公钥添加成功”。此时不要急着克隆仓库先在终端测试一下连接ssh -T gitgitee.com如果是第一次连接终端会提示确认远程主机的指纹输入yes回车即可。之后如果看到类似Welcome to Gitee.com, 你的用户名!的提示说明 SSH 配置已经通了。这一步成功后面所有操作都会顺畅很多。注意如果本地存在多个密钥对或者 config 配置文件里没指定用哪个私钥可能会出现“连接时自动用默认私钥但默认私钥不是 Gitee 的那把“的问题表现为连接失败但公钥明明添加成功。多密钥管理的方法看后面的常见问题。4. 新建远端仓库与初始化本地仓库两边的仪式感都要有4.1 在 Gitee 网页端创建远程仓库登录 Gitee点击右上角的“”选择“新建仓库”。这里有几个选项需要仔细填仓库名称这个名字同时也是远程仓库地址的一部分建议用短横线分隔的英文比如my-blog或api-server不要用中文和空格。路径默认会跟仓库名保持一致一般不用改。仓库介绍可以简单写一下这个项目是干嘛的。是否开源公开仓库别人可以看到私有仓库只有自己和被邀请的成员能看到。Gitee 对私有仓库的数量在实际使用中比较宽松但如果是团队内部项目建议直接用私有。初始化仓库可以勾选“使用 Readme 文件初始化这个仓库”也可以“选择 .gitignore 模板”和“选择开源许可证模板”。这里有个新手容易踩的坑我先说明如果你已经在本地有了代码并且准备用git push推上去千万别勾选“使用 Readme 文件初始化”否则远程仓库有了初始提交、本地仓库也有了初始提交两边都有各自的历史push 时会出现冲突和 “non-fast-forward” 的错误。正确做法是先不初始化任何文件创建好空仓库后从本地推上去。创建成功后会跳转到仓库主页页面上会显示远程仓库地址两种形式HTTPS: https://gitee.com/用户名/仓库名.git SSH: gitgitee.com:用户名/仓库名.git既然前一步已经配置好了 SSH这里果断用 SSH 地址。4.2 本地初始化的两种场景创建完远程仓库后本地有两种常见场景对应不同的操作路径。这个选择很多人搞不清楚我分开讲。场景 A本地已经有项目代码希望托管到远程仓库这是最常见的情况。假设本地已经有一个项目文件夹里面有源码、资源文件等在项目根目录执行git init执行后会在当前目录生成一个隐藏的.git文件夹这个文件夹就是 Git 的“数据库”记录所有提交历史、分支、配置等信息。接着把代码加入暂存区并完成第一次提交git add . git commit -m init projectgit add .会把所有未忽略的文件加入暂存区git commit把暂存区的快照保存为一次提交。这里有个提示提交信息建议写清楚这次提交的目的比如init project、feat: add login module、fix: fix null pointer issue不要写update、xxx这类没有任何信息量的内容。场景 B远程仓库已经有内容希望克隆到本地比如远程仓库里已经有 README 或团队其他人提交的代码你想把它下载到本地开发直接克隆git clone gitgitee.com:用户名/仓库名.git执行完会生成一个以仓库名命名的本地文件夹里面已经绑定了远程仓库地址。这时候不需要再git init也不需要手动添加远程地址一切都自动配好了。4.3 关联远程仓库并完成首次推送如果你走的是场景 Ainit 完仓库之后需要手动关联远程地址。查看当前是否已有远程关联git remote -v如果没有输出说明还没有关联远程仓库添加git remote add origin gitgitee.com:用户名/仓库名.gitorigin是远程仓库的默认别名你可以改成任意名字但按惯例大家都叫origin没必要特立独行。关联完以后确认一下git remote -v看到输出里有 fetch 和 push 两条记录说明关联成功。然后推送到远程git push -u origin master如果远程仓库顶端显示的是main分支而本地默认分支是master可以把命令里的分支名改一下或者先用下面命令把本地分支改名再推送git branch -M main git push -u origin main-u参数的作用是把本地分支与远程分支建立跟踪关系。之后你再执行git push或git pull的时候Git 就知道该往哪个远程分支推、从哪个远程分支拉不需要每次都写全origin 分支名。5. 核心实操git push 与 git pull 的完整工作流5.1 日常开发循环add、commit、push远程仓库配置好之后日常开发就是一个小循环改代码 -git add-git commit-git push。我见过很多初学者每次都要查这三个命令怎么敲其实关键在于理解它们的角色定位。git add是把文件的“当前版本”放进一个叫暂存区的地方。暂存区可以理解为购物车你可以往里面塞一个文件、几个文件或所有文件但塞进去不代表已经买单。git commit才是真正的“买单”执行完 commit 之后暂存区的内容被打包成一个不可变的快照并且记录到 Git 的时间线上。git push则是把本地已经生成的这些快照上传到远程仓库。举个例子来说明这个流程。你修改了index.html和style.css两个文件想分两次提交先提交index.html、再提交style.cssgit add index.html git commit -m update homepage structure git add style.css git commit -m refactor page style git push这样提交历史里就有两条清晰的记录以后回溯起来非常方便。如果你偷懒直接用git add .把所有改动一股脑打包提交历史就会变成一锅粥哪天要回滚某个功能就麻烦了。5.2 理解 pull 与 fetch 的区别git pull是从远程仓库拉取代码并自动合并到当前分支。它其实是两个命令的组合git fetch加git merge。git fetch只负责把远程最新的提交记录下载到本地并不动你的工作区文件git pull在 fetch 之后还会尝试把远程分支合并进你当前所在的分支。如果你想先看看远程改了什么、不想立刻合并就只执行git fetch然后手动查看差异再决定是否合并如果你确定要同步最新代码直接用git pull就行。日常最标准的同步姿势是git pull origin main拉取时会涉及远程分支的状态更新本地如果有未提交的改动而远程恰好也改动了同一个文件的同一行Git 会在 merge 时报告冲突。这时候 Git 会标记出冲突文件你需要手动打开文件找到类似下面这样的标记 HEAD 你本地写的代码 远程拉下来的代码 远程分支名你需要做的是把、、这些标记删掉保留最终想要的内容然后重新 add、commit、push。新手遇到冲突会慌其实它只是 Git 把两个不同版本的修改摆在你面前让你做裁决不是什么大事。5.3 分支管理与多人协作的基础约定单个人开发可以不分支一条线从头撸到尾。但进入团队协作之后直接在main或master上改代码风险太高。团队协作用得最多的是特性分支工作流每个功能分支从main创建开发完成后再合并回去。基本的操作流程是这样的git checkout -b feature/login # 在新分支上开发 git add . git commit -m feat: add login page git push -u origin feature/login推上去之后在 Gitee 网页端可以发起合并请求其他成员审核无误后合并到main。这个流程在 Gitee 上叫“Pull Request”合并请求可以设置审核人、关联任务、看到文件级别的 diff非常适合同步信息。分支规范上我建议遵循一套简单的约定main或master分支永远保持可发布状态不直接在main上提交。新功能用feature/功能名命名比如feature/user-center。修复问题用fix/问题描述命名比如fix/login-token-expire。废弃的分支合并完及时删除保持仓库干净。这套约定本身不复杂但它能有效避免“谁能改、改了啥、为什么改”这种三个哲学问题。5.4 .gitignore 的写法与管理范围git add .会把目录下所有非忽略文件加进去但不是所有文件都想交给 Git 管理。比如本地配置、日志文件、临时文件、依赖目录、编译产物这些东西每个开发者本地都可能不一样而且大得离谱放进仓库只会制造噪音和冲突。.gitignore文件就是用来告诉 Git “哪些东西不要管”的。一个比较通用的.gitignore示例node_modules/ dist/ build/ *.log .idea/ .vscode/* !.vscode/extensions.json .DS_Store创建.gitignore文件之后执行git status时这些路径就不会再出现在变更列表里。注意如果某个文件已经被 Git 跟踪了再把它写入.gitignore是无效的需要先执行git rm -r --cached 文件路径将它从 Git 的跟踪列表中移除但保留在本地磁盘然后再 commit。这个细节很容易踩坑我见过不少开发者在 .gitignore 里加了规则但死活不生效原因就是这个文件之前已经被 add 过了。6. 常见问题与排查技巧实录把这些坑都填平6.1 Permission denied (publickey)这是配 SSH 时最高频的报错字面意思是“没有公钥权限”。排查步骤按顺序走用ssh -T gitgitee.com测试看返回什么。确认~/.ssh/id_rsa.pub里的内容跟 Gitee 后台添加的完全一致。确认 ssh-agent 是否在运行私钥是否已加入。执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_rsa如果是公司电脑检查是否有全局 SSH config 把默认私钥指向了别的地方。大部分情况是第 2 步或第 3 步的问题要么公钥复制少了字符要么私钥没有被 ssh-agent 加载。还有一个经典问题有的开发者生成了密钥后又设置了 passphrase结果 push 时提示输入 passphrase 输错了几次被系统暂时拒了这时候需要检查 ssh-agent 的状态。6.2 多平台、多密钥混用的处理方案很多开发者在一台电脑上同时有 Gitee、GitHub 或其他代码托管平台的账号每个平台都想用 SSH。这时候不能在同一个~/.ssh下反复生成id_rsa因为覆盖之后其他平台的权限就丢了。正确做法是给每个平台生成独立的密钥对ssh-keygen -t rsa -b 4096 -C gitee邮箱 -f ~/.ssh/id_rsa_gitee ssh-keygen -t rsa -b 4096 -C github邮箱 -f ~/.ssh/id_rsa_github然后在~/.ssh/config文件里做映射Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_rsa_gitee Host github.com HostName github.com User git IdentityFile ~/.ssh/id_rsa_github这样 Git 连接不同域名时会自动选择对应的私钥互不干扰。注意.ssh目录权限和私钥文件权限需要适当收紧Linux/macOS 上私钥权限过宽也会被拒绝识别可以执行chmod 700 ~/.ssh chmod 600 ~/.ssh/id_rsa_gitee6.3 仓库存在却提示仓库不存在有时候 push 或 clone 时提示仓库不存在但你在 Gitee 网页端明明能看到这个仓库。出现这种情况80% 的原因是访问权限。如果你创建的仓库是私有的而当前 SSH 公钥关联的账号不是仓库成员或者你用错了公钥就会表现为 “repository not found”。另一个可能是仓库名拼写错误或者远程地址写错了用户名。排查方法先在 Gitee 网页端确认仓库的可见性和自己的账号角色然后把 SSH 地址复制出来仔细核对一遍。还有一种情况是公司内网的 Git 服务与 Gitee 的端口互相干扰这种时候换个网络环境再试往往会好。6.4 push 被拒non-fast-forward 与冲突解决第一次 push 前如果没有正确处理好两边历史的“共同祖先”最容易出现这个错误本地仓库有提交、远程仓库也恰好有提交比如网页端勾选了初始化 READMEGit 不知道如何合并。解决方式是把远程内容先拉下来合并再推上去git pull origin main --rebase # 解决冲突后 git push -u origin main--rebase会把本地的提交“垫”到远程提交的后面形成一条干净的历史线。如果在 pull 时遇到冲突按照上面“冲突解决”一节的方法手动处理即可。这里我再给个建议每次开始新任务前先执行一次git pull每次 push 前先git status看一眼工作区状态这两条看起来平平无奇但能帮你避开大量不必要的合并痛苦。6.5 中文乱码与提交信息编码问题Git 默认对文件内容的处理与提交信息编码可能不一致仓库路径或分支名含中文时偶尔会出现乱码。有一种规避方案就是仓库名、分支名、提交信息统一用英文这是最省心的。如果一定要在文件内部使用中文编译器一般会正常处理。如果git status显示中文文件名乱码可以设置git config --global core.quotepath false这样 Git 对非 ASCII 文件名会显示原始字符而不是转义序列。提交信息用中文配合支持 UTF-8 的终端一般也没问题。Windows 上务必确保 Git Bash 的编码和系统区域设置一致否则终端里看着是中文提交到服务器上就变成问号了。这个问题排查起来比较隐蔽我建议从一开始就养成英文提交信息的习惯不存在编码问题的同时跨团队时也不会因为语言差异产生误解。6.6 忘了为什么 push 不上梳理本地分支与远程分支的对应关系有时候 push 失败是因为本地分支和远程分支根本不对应。用下面命令查看所有分支和跟踪关系git branch -vv git remote -vgit branch -vv会显示本地分支以及它们跟踪的远程分支和各自领先、落后的提交数。看到类似main [origin/main] ahead 2 behind 1的提示意思是本地有两个新提交、远程有一个新提交没拉下来需要先 pull 再 push。很多新手看到 “ahead”“behind” 不知道什么意思其实它就是字面上的“谁走得快”合并之后再推即可。7. 进阶技巧与实操心得把工作流用得更顺手7.1 用心维护提交历史提交信息规范与粒度提交历史是项目的“日记”建议好好写。团队可以约定一套简单的规范比如用前缀区分提交类型feat:新功能fix:修复问题docs:文档变更style:代码格式调整不影响逻辑refactor:重构既不修 bug 也不加功能test:新增或修改测试chore:构建过程或辅助工具变动比如feat: add user registration api、fix: fix cart total calculation bug。这样以后查看历史时扫一眼就知道这个版本在干嘛配合git log --oneline时光线非常清晰。提交粒度上建议做到一个提交只做一件事。改了一个功能、删了一个文件、调了一个配置分别提交回滚时也能精准操作。7.2 巧妙使用标签管理与版本发布在 Gitee 上管理版本发布可以用 Git 的 tag 功能。发布 v1.0.0 时打一个标签git tag -a v1.0.0 -m release v1.0.0 git push origin v1.0.0之后可以通过git checkout v1.0.0切换到任意历史版本也可以在网页端看到“Tags”列表。标签和分支不同标签是不可移动的它更像在时间线上钉了一个图钉版本发布后不会因为后续提交而改变位置。线上系统出问题需要快速回退到上一个稳定版本时先找标签再切分支比在几百条提交里翻要快得多。7.3 搜索揪出责任人的三种姿势当线上 bug 出现时怎么快速找到是哪次提交、哪个人、改了什么导致的第一个命令是git log配合文件名筛选git log --oneline -- 文件名第二个是git blame它会按行显示某文件中每一行最后一次被谁修改git blame server.py第三个是git bisect在已知某次提交是好的、某次提交是坏的情况下用二分法快速定位引入 bug 的提交。这三个工具在排查问题时非常高效建议尽早学会。7.4 把常用命令封装成固定习惯最后分享一个我自己的习惯每天打开电脑的固定动作是git pull开始写一个功能前先git status确认工作区干净写完一批代码先git diff看一眼改动内容再 commit。这几条命令已经变成肌肉记忆不需要想就能敲出来。回到本文开头说的那句话配置 Gitee 远程仓库只是万里长征第一步真正让你省时间的是这套动作养成了习惯之后版本管理对你来说不再是一个需要“认真对待”的任务而是一件自然而然的事。等有一天你同时在几个分支之间切换、在几个仓库之间同步、甚至在遇到冲突时几分钟就处理完你就会明白这些基本功到底有多值钱。
