1. 为什么你需要一个“Gitee使用大全”？
如果你刚开始接触代码协作，或者刚从GitHub转战国内环境，面对Gitee（码云）时，可能会有点懵。网上教程很多，但要么是零散的“如何创建仓库”，要么是深奥的“Git原理剖析”，很少有把从零到一、从基础操作到进阶技巧、从个人使用到团队协作串起来讲的。结果就是，你看了十篇教程，还是搞不定一次完整的代码提交，或者在团队协作时踩了权限、分支合并的坑。
我用了Gitee好几年，从个人项目到带领几十人的团队进行代码管理，几乎把能踩的坑都踩了一遍。今天这篇内容，就是把我这些年的实战经验，结合全网最常被搜索的问题，给你揉碎了、掰开了，整理成一份可以直接“抄作业”的指南。这不是官方文档的复述，而是一个老司机告诉你，在真实项目里，哪些命令最常用，哪些配置能救命，哪些界面按钮藏着关键功能。我们的目标很简单：让你看完这一篇，就能自信地使用Gitee进行日常开发和团队协作，再也不用东拼西凑地找资料。
2. 万丈高楼平地起：环境准备与核心概念扫盲
在动手敲命令之前，我们必须把地基打牢。很多人学Git和Gitee觉得难，不是因为命令复杂，而是没搞清楚几个核心概念之间的关系，操作起来自然云里雾里。
2.1 Git、Gitee与GitHub：理清关系
首先，我们要分清楚三个东西：Git、Gitee和GitHub。
- Git：这是一个版本控制系统，是一个安装在你自己电脑上的软件。它的核心工作是记录你文件（主要是代码）的所有历史变化，就像一台时光机。你所有的
git add,git commit命令都是在和本地的Git打交道。 - GitHub和Gitee：它们都是基于Git的代码托管平台。你可以把它们想象成“网盘”，但专门为Git设计。你把本地Git仓库“推”到这些平台上，就可以实现代码的远程备份、多人协作、在线查看等。GitHub是国际主流，Gitee是国内对标产品，访问速度快，更适合国内团队，并且提供了私有仓库免费等对开发者更友好的策略。
所以，你的工作流通常是：在本地用Git管理代码 -> 将本地仓库同步到Gitee远程仓库 -> 团队成员从Gitee克隆仓库到各自本地。
2.2 安装与配置Git：一步都不能错
这是所有操作的起点，配置错了后面全是坑。
1. 下载与安装Git：
- 前往Git官网下载对应系统的安装包。安装时，有几个关键选项需要注意：
- 选择默认编辑器：新手建议选
Use Visual Studio Code as Git's default editor，当然你也可以选Vim或Nano，但需要熟悉其操作。 - 调整PATH环境：务必选择
Git from the command line and also from 3rd-party software。这会把Git命令添加到系统PATH，让你能在任何命令行窗口（如CMD、PowerShell、终端）中使用git命令。 - 配置行尾转换：这是跨平台协作的大坑！Windows和Unix/Linux系统的换行符不同。为了协作顺畅，强烈建议选择
Checkout Windows-style, commit Unix-style line endings。这样，在你签出代码时转换为Windows风格（CRLF），提交时统一转换为Unix风格（LF），避免文件因换行符问题显示为全部修改。
- 选择默认编辑器：新手建议选
2. 至关重要的初始配置：安装完成后，打开命令行（CMD或Git Bash），进行全局配置。这两行命令决定了你每次提交记录的作者信息，必须设置。
git config --global user.name "你的用户名" git config --global user.email "你的邮箱"这里的用户名和邮箱最好与你在Gitee上注册的账号一致，这样提交记录就能正确关联到你的Gitee账户。
3. 生成SSH密钥（远程协作的通行证）：使用HTTPS链接每次推送都要输密码，非常麻烦。SSH密钥才是高效协作的标配。
ssh-keygen -t rsa -C "你的邮箱"连续按三次回车，采用默认设置（不设密码）。完成后，在用户主目录（通常是C:\Users\你的用户名\.ssh或~/.ssh）下，你会找到两个文件：id_rsa（私钥，绝不可泄露）和id_rsa.pub（公钥）。
用记事本打开id_rsa.pub，复制全部内容。然后登录Gitee，进入设置 -> SSH公钥，将公钥内容粘贴进去，标题会自动生成，点击确定。至此，你的本地机器就获得了免密访问Gitee仓库的权限。
3. 单人开发流水线：从本地到Gitee的完整操作
假设你现在要开始一个新项目，我们走一遍最标准的流程。
3.1 场景一：本地已有项目，想托管到Gitee
这是最常见的情况。你已经在电脑上写了一些代码，现在想把它放到Gitee上备份并开始版本管理。
第一步：在Gitee上创建远程仓库
- 登录Gitee，点击右上角“+”号，选择“新建仓库”。
- 填写仓库名称，选择“私有”或“开源”。对于个人学习项目，可以选“私有”。
- 初始化设置这里有个关键点：既然你本地已有代码，那么千万不要勾选“使用Readme文件初始化这个仓库”。如果勾选了，Gitee会创建一个带有README文件的初始提交，这会导致你本地仓库和远程仓库的初始提交历史不一致，在第一次推送时需要进行复杂的合并操作。所以，直接点击“创建”即可。
第二步：在本地项目根目录初始化Git仓库打开命令行，进入到你的项目文件夹。
cd /path/to/your/project git init这个命令会在当前目录创建一个隐藏的.git文件夹，所有版本信息都存储在这里。
第三步：将本地代码纳入版本管理
git add .这个点.代表当前目录下所有新增和修改的文件。它会将文件的变化放入“暂存区”（Staging Area）。暂存区是一个中间区域，你可以理解为快递打包台，git add就是把要寄走的物品放上去。
第四步：创建提交（Commit）
git commit -m "这里写你的提交说明，如：初始化项目，添加用户登录模块"-m后面跟的是提交信息，务必认真填写。好的提交信息应该简洁明了地说明这次提交做了什么，比如“修复了首页图片无法加载的bug”、“新增了用户注册API接口”。模糊的“更新代码”会给日后查历史带来巨大麻烦。
第五步：关联远程仓库并推送现在需要告诉本地仓库，远程仓库在哪里。
git remote add origin git@gitee.com:你的Gitee用户名/仓库名.git这里的origin是给这个远程仓库起的一个别名，习惯上用origin。地址可以从Gitee仓库页面的“SSH”标签下复制。
最后，将本地的提交推送到远程：
git push -u origin master-u参数是--set-upstream的简写，它建立了本地master分支与远程origin/master分支的追踪关系。设置好后，下次在这个分支上只需要输入git push即可。
3.2 场景二：从Gitee克隆现有项目到本地
如果你想参与一个已有项目，或者换一台电脑继续开发，就需要克隆。
git clone git@gitee.com:项目所有者用户名/仓库名.git这个命令会做三件事：1. 在当前目录创建以仓库名命名的文件夹；2. 初始化一个Git仓库；3. 将远程仓库的所有代码和历史记录完整地下载下来。之后你就可以进入这个文件夹开始开发了。
3.3 日常开发循环：Add, Commit, Push
日常工作中，你会反复进行这个循环：
- 修改代码。
git add .或git add 文件名：将特定文件加入暂存区。git commit -m “提交信息”：创建一个本地提交。git push：将本地提交推送到Gitee。
实操心得：养成“小步快跑”的提交习惯。每次提交只完成一个小的、完整的功能或修复一个具体的bug，并写好清晰的提交信息。这比攒了一周代码做一次大提交要清晰得多，回滚和排查问题也更容易。
4. 团队协作核心：分支、合并与Pull Request
单人开发掌握上一节就够了，但团队协作才是Git和Gitee价值的真正体现。其核心模型是功能分支工作流。
4.1 为什么一定要用分支？
想象一下，如果所有人都在master分支（通常代表稳定、可上线的版本）上直接修改，那么正在开发中的、半成品的功能代码就会污染主线，导致主线永远处于不稳定状态。分支的作用就是为每一个新功能、每一个修复创建一个独立的“平行宇宙”，在这个宇宙里你可以随意修改，而不会影响主宇宙（master分支）。
4.2 功能分支工作流实战
假设你要开发一个“支付功能”。
第一步：基于master创建功能分支首先，确保你本地master分支是最新的。
git checkout master # 切换到master分支 git pull origin master # 拉取远程master的最新代码然后，创建并切换到一个新分支。
git checkout -b feature-payment-b参数表示创建并切换。分支名最好具有描述性，如feature-*,fix-*,hotfix-*。
第二步：在新分支上进行开发你现在就在feature-payment分支上了，所有add,commit操作都只影响这个分支。开发完成后，将分支推送到Gitee。
git push origin feature-payment第三步：发起Pull Request (PR)在Gitee仓库页面，你会看到提示“您的分支 feature-payment 最近有推送，可以创建 Pull Request 进行代码合并”。点击它，或者主动进入“Pull Requests”标签页创建。
- 源分支：选择你刚推送的
feature-payment。 - 目标分支：选择要合并进去的
master。 - 填写信息：详细描述这个PR做了什么，解决了什么问题，测试情况如何。这是团队沟通的重要环节。
- 指派评审员：可以指派给团队的同事，让他们来审查你的代码。
第四步：代码审查与合并评审员会在PR页面查看代码变更，提出评论或修改建议。你可以根据反馈在本地分支继续修改、提交并推送，PR会自动更新。 当所有讨论完成，代码审查通过后，拥有合并权限的人（可能是你，也可能是项目管理员）可以点击“合并”按钮。Gitee提供了几种合并方式：
- Merge（合并提交）：创建一个新的合并提交，保留分支历史。最常用，历史清晰。
- Squash（压缩合并）：将PR中的所有提交压缩成一个提交后合并到目标分支。适合分支提交琐碎，想保持主线历史整洁的场景。
- Rebase（变基合并）：不创建合并提交，而是将PR的提交“嫁接”到目标分支的最新提交之后。能得到一条线性的历史，但操作复杂，对公共分支有风险，新手慎用。
合并完成后，这个功能分支的使命就结束了。你可以在本地和远程删除它，以保持仓库整洁。
# 切换回master分支 git checkout master # 删除本地分支 git branch -d feature-payment # 删除远程分支 git push origin --delete feature-payment4.3 不可避免的冲突：如何解决？
当多个人修改了同一文件的同一区域时，冲突就会发生。例如，你和同事都修改了utils.js文件中的同一个函数，Git无法自动决定保留谁的修改。
冲突产生的典型场景：
- 你在
feature-A分支修改了file.txt的第10行。 - 同事将他的
feature-B分支合并到了master，也修改了file.txt的第10行。 - 当你尝试将
master分支合并到你的feature-A分支以同步最新代码时，冲突就出现了。
解决冲突的步骤：
- 尝试合并时，Git会提示
CONFLICT。 - 打开冲突文件，你会看到类似这样的标记：
<<<<<<< HEAD 这是你当前分支的修改内容 ======= 这是来自master分支的修改内容 >>>>>>> master - 这是需要你人工介入决策的地方。你必须和同事沟通，决定是保留你的修改、保留他的修改，还是进行整合，形成一段新的代码。删除
<<<<<<<,=======,>>>>>>>这些标记，并保留最终确定的内容。 - 解决完所有冲突文件后，使用
git add .将解决后的文件标记为已解决。 - 最后，完成这次合并提交：
git commit。
避坑指南：减少冲突的最好方法是频繁地从主分支（如
master）合并更新到你的功能分支，以及将大功能拆分成小任务。同时，在团队内约定代码风格和文件职责，也能有效降低冲突概率。
5. Gitee的进阶武器库：不止于代码托管
Gitee不仅仅是个Git服务器，它围绕软件开发生命周期提供了许多提升效率的工具。
5.1 Issues：需求与缺陷跟踪
Issues是项目管理的神器，可以用来记录Bug、提出新功能需求、分配任务。
- 创建Issue：在仓库页面进入“Issues”标签，写清楚标题和描述。描述可以用Markdown格式，贴图、贴代码都很方便。
- 标签与里程碑：为Issue打上标签（如
bug,enhancement,help wanted），关联到里程碑（版本计划），可以极大地提升管理效率。 - 关联提交：在提交信息中，可以写上
fix #1或close #2，这样当提交被合并到默认分支时，可以自动关闭对应的Issue，实现跟踪闭环。
5.2 Wiki：项目文档的最佳归宿
每个仓库都自带一个Wiki系统，用于编写项目说明、API文档、部署指南等。它同样支持Markdown，并且有独立的版本历史。把文档放在Wiki里，而不是写在项目的README里，可以让README更简洁，文档结构更清晰。
5.3 Gitee Pages：免费的静态网站托管
这是Gitee一个非常实用的功能。你可以将仓库中的特定分支（如gh-pages或master分支下的docs目录）自动发布成一个静态网站，用于托管项目文档、博客或个人主页。
- 在仓库“服务”菜单中开启“Gitee Pages”。
- 选择源分支和部署目录。
- 点击“启动”，稍等片刻，就会生成一个专属的
你的用户名.gitee.io/仓库名的访问链接。
注意事项：Gitee Pages需要手动点击“更新”才能部署最新内容，不如GitHub Pages自动化程度高。且对动态内容支持有限，主要用于静态站点。
5.4 Webhook与集成：自动化流水线触发器
Webhook允许你在仓库发生特定事件（如推送、PR创建、Issue更新）时，向一个你指定的URL发送一个POST请求。这是实现自动化部署（CI/CD）的关键。 例如，你可以配置一个Webhook，当代码推送到master分支时，自动触发你服务器上的一个脚本，这个脚本拉取最新代码、运行测试、构建并部署到生产环境。常见的CI/CD工具如Jenkins、GitLab CI都可以通过Webhook与Gitee轻松集成。
6. 高效团队管理：仓库设置与成员协作
当项目从个人转向团队时，合理的仓库设置是高效协作的保障。
6.1 仓库基础设置
进入仓库的“管理”页面，有几个关键设置：
- 默认分支：通常设为
master或main。你可以保护这个分支，比如设置“合并请求时需要审查”、“禁止强制推送”，确保代码质量。 - 提交合并设置：建议开启“合并请求中必须关联Issues”，让每次代码变更都有据可查。
- 仓库可见性：根据项目阶段，在“私有”、“开源”之间切换。
6.2 成员权限管理
Gitee提供了清晰的成员角色：
- 访客：只能克隆和查看，不能推送。
- 报告者：可以克隆、查看、创建Issue和Pull Request。
- 开发者：拥有报告者所有权限，此外可以推送到非保护分支，创建和删除自己的分支。
- 管理员：拥有项目的最高权限，可以管理成员、修改仓库设置等。
根据团队成员的实际职责分配权限，遵循最小权限原则。通常，核心开发者为“开发者”，项目负责人或架构师为“管理员”，其他协作者或测试人员为“报告者”。
6.3 保护分支规则：团队质量的守门员
这是防止代码被意外破坏的关键功能。你可以为重要分支（如master,release）设置保护规则：
- 禁止强制推送：强制推送（
git push -f）会覆盖历史，是团队协作的灾难，必须禁止。 - 禁止直接推送：要求所有代码必须通过Pull Request合并，确保有审查流程。
- 要求Pull Request通过代码审查：可以设置必须有一定数量的管理员或指定人员批准后，才能合并。
- 要求状态检查通过：可以关联CI/CD流水线，只有测试、构建等状态检查全部通过后，才允许合并。
这些规则共同构成了团队代码入库的质量防线。
7. 常见疑难杂症与效能提升技巧
即使掌握了基本操作，在实际使用中还是会遇到一些棘手问题。这里分享几个高频问题的解决思路和提升效率的技巧。
7.1 经典问题排查
问题1：git push被拒绝，提示“非快进式推送”
- 原因：远程分支有你本地没有的新提交。通常是因为别人已经往远程推送了代码。
- 解决：先执行
git pull origin 分支名将远程最新代码拉取下来并合并到本地，解决可能出现的冲突后，再执行git push。
问题2：提交了错误文件或写了错误的提交信息
- 情况A：仅修改最后一次提交（提交还未推送）：
# 修改文件后 git add . git commit --amend # 这会进入编辑器让你修改提交信息，保存退出即可覆盖上一次提交。 - 情况B：需要回退到某个历史版本：
git log --oneline # 查看提交历史，找到要回退到的提交的哈希值（前7位即可） git reset --hard <commit-hash> # 硬重置，本地工作区和暂存区都回到该版本警告：
git reset --hard会丢弃所有之后的更改，且如果已经推送到远程，强制推送（git push -f）会影响他人，需极其谨慎，最好在个人分支操作。
问题3：想下载仓库中的单个文件，而非克隆整个仓库Gitee网页版提供了直接下载单个文件的功能。如果需要用命令，可以借助svn（如果仓库支持）或使用git archive配合远程命令，但更简单的方法是：在仓库文件页面点击“原始数据”获取文件的直链，然后用wget或curl下载。
7.2 提升效率的Alias配置
在~/.gitconfig文件中添加以下别名，可以极大减少敲命令的时间：
[alias] co = checkout br = branch ci = commit st = status pl = pull ps = push lg = log --oneline --graph --all --decorate last = log -1 HEAD --stat配置后，git st就相当于git status，git lg能输出一个非常直观的图形化提交历史。
7.3.gitignore文件：让仓库保持干净
这个文件定义了哪些文件或目录应该被Git忽略，不纳入版本管理。比如编译产物（node_modules/,*.class）、IDE配置文件（.idea/,.vscode/）、系统文件（.DS_Store）等。 你可以在项目根目录创建一个名为.gitignore的文件，并在Gitee创建仓库时选择对应的模板（如Java、Python）。一个良好的.gitignore习惯，能避免将无关的、庞大的文件提交到仓库。
从环境配置、日常操作到团队协作、效能提升，Gitee的整个使用脉络已经清晰。工具的价值在于熟练运用，现在就去创建一个仓库，把第一个项目推上去，在实践中遇到具体问题再回头查阅，这才是最快的学习路径。记住，版本控制的核心思想是“记录变化，协同工作”，所有的命令和流程都是为这个目标服务的。当你理解了这一点，这些操作就不再是冰冷的命令，而是你管理代码世界的得力助手。
