最近几年我发现身边越来越多刚接触编程的朋友第一句问的基本都是同一句话“我写的代码到底要怎么传到网上去保存” 这个需求特别真实不管是写课程设计、个人博客还是在公司做项目协作代码都不应该只躺在自己电脑里。今天这篇保姆级教程我就直接把 VSCode 和 Gitee 这套组合掰开揉碎从注册账号开始一直到把本地代码成功推到远程仓库全部走一遍。关键是这篇文章不预设你已经具备任何 Git 基础只要你会用电脑打字跟着一步步做就能跑通整个流程。这套方案适合谁呢比如正在学校交课设的大学生比如准备把练习项目整理出来找工作用的转行者再比如小团队里想统一管理代码但不想折腾太复杂架构的开发者。Gitee 是国内访问速度极快的代码托管平台VSCode 则是目前生态最活跃的代码编辑器两个一配合你就能拥有一个“本地写代码 云端备份 团队协作”的完整工作流。这篇文章会把每一步的原理也讲清楚不光是让你照着抄还让你明白为什么要这么做。1. 内容整体设计与思路拆解1.1 为什么是 VSCode 加 Gitee 这个组合先聊一个很多人忽略的问题编辑器那么多为什么选 VSCode代码托管平台也不少为什么选 Gitee这套组合说白了就是“写代码的桌面工具 放代码的云端仓库”。VSCode 的优势在于它免费、开源、跨平台Windows、macOS、Linux 通吃而且插件生态极其丰富。安装一个 Python 插件就能写 Python安装一个 C/C 插件就能写 C 和 C不需要像以前那样换一个语言就换一套 IDE。Gitee 这边最大的优势是服务器在国内。早些年大家习惯去 GitHub 存代码但国内网络访问 GitHub 的速度经常不稳定推送一个大一点的项目可能要等很久甚至直接失败。Gitee 基本没有这种问题创建仓库、克隆、推送速度都非常快更适合国内用户日常使用。另外Gitee 免费用户也能创建私有仓库个人练习项目不想公开的话选私有就完全够用。还有一个容易被忽略的点Gitee 对新手非常友好。它的网页界面是全中文的仓库创建向导里各项字段解释得很清楚对“开源许可证”“README”这类概念还配了说明。相比之下GitHub 的界面和术语对英语不好的同学就有一点门槛。对于第一次接触代码托管的人来说先用 Gitee 把 GitHub 的操作逻辑弄明白将来再切换成本也不高。1.2 这套方案能帮你解决什么问题新手学代码时最常遇到的一个痛点是代码写了一堆但不知道怎么管理版本。比如有一天把程序改坏了想退回之前的能运行版本如果靠手动复制文件夹过几天就分不清哪个是最新的了。Git 的作用就是帮你记录每一次修改就像一个游戏存档系统你想回到哪一关都可以。但 Git 本身是命令行工具很多初学者看到黑底白字的终端窗口就压力山大。VSCode 的源代码管理面板把 Git 的常用操作都做成了可视化按钮鼠标点一点就能完成提交、推送、拉取等操作大大降低了学习门槛。我在带新人时经常跟他们说你不需要背几十个 Git 命令先掌握 add、commit、push、pull 这四个就够用了其余的命令用到的时候再查。再来说说“帮别人看代码”这个场景。以前你想让同学帮你看看代码哪里写错了通常是把整个项目打包成 zip 发过去对方改完再回传一个 zip一来二去版本就混乱了。有了 Gitee 远程仓库后你把代码推进仓库别人直接克隆或拉取最新版本改完再推送回来整个过程清清楚楚。这就是代码托管最朴素的协作价值。1.3 整体学习的路线规划我给这份教程规划的学习路线是“环境准备 → 密钥配置 → 仓库创建 → 本地操作 → 日常协作”。前两步属于一劳永逸的事做一次以后就不用再管。第三步是理解整个流程的关键节点知道代码到底存在哪里。第四步是核心操作学会之后你就能把所有项目都纳入版本管理。第五步属于进阶理解了之后你会知道为什么有些项目会出现代码冲突以及怎么解决冲突。每一部分我都会给出操作步骤和背后的原因遇到容易出错的地方还会专门提醒。学完这篇教程之后你再回头看那些“上传代码到 Gitee”的零散问答帖基本都能看懂了因为底层逻辑你已经通了。2. 新环境准备从零装好三件套2.1 VSCode 下载安装的细节与验证第一步自然是安装 VSCode。网上搜索“VSCode 官网”的时候要多留个心眼有些搜索结果点进去是下载站会捆绑各种乱七八糟的东西。认准官方域名一般是以code.visualstudio.com开头的那个。进入官网后首页会显示一个很明显的下载按钮它会根据你的操作系统自动推荐对应版本。Windows 用户选择 x64 版本的 User Installer 即可如果你是 Windows 7 系统注意看一下历史版本说明新版 VSCode 已经不支持 Win7 了需要去官方文档里找旧版本。下载完成后双击安装包开始安装。这个安装过程中有几个选项值得留意。第一建议勾选“添加到 PATH”也就是“Add to PATH”这个选项这样以后你想在终端里直接输入code命令打开当前目录就方便多了。第二建议勾选“通过 Code 打开”操作菜单里的选项比如“添加到‘打开方式’列表”这样在文件管理器里右键一个文件夹就能直接用 VSCode 打开。这些选项在安装时都可以通过勾选实现如果当初没勾也可以不改装直接在 VSCode 里用“文件—打开文件夹”也能解决问题。安装完成后第一次打开 VSCode你会看到英文界面。对完全不熟悉英文的同学来说可以直接先设置中文。按快捷键CtrlShiftP打开命令面板输入“Configure Display Language”选择“Install additional languages”在插件列表里搜索安装“Chinese (Simplified) Language Pack for Visual Studio Code”。安装完成后按提示重启界面就是中文了。2.2 安装 Git 并完成基础身份配置有了 VSCode 之后还需要装一个 Git。VSCode 只是一个编辑器和操作界面真正执行版本管理命令的还是 Git 这个工具本体。可以这么理解VSCode 是仪表盘Git 是发动机。去 Git 官网下载对应操作系统的安装包Windows 下是 Git for Windows下载完成后一路 Next 即可。安装完成后打开任意终端窗口Windows 下打开 PowerShell 或 CMD输入git --version如果看到类似git version 2.40.0的输出就说明安装成功。接下来要做一件事配置你的用户名和邮箱。这个信息会跟随每一次提交别人看仓库提交记录时能知道是谁改的。执行以下两行命令把名字和邮箱替换成你自己的注意这里建议使用和 Gitee 注册时一致的邮箱git config --global user.name 你的昵称 git config --global user.email 你的邮箱--global参数的意思是全局生效以后这台电脑上的所有 Git 仓库都会用这个身份提交。这一步很多人会漏掉结果第一次 commit 时报错Please tell me who you are其实就是没配身份。配完之后可以再执行git config --list检查一下配置是否生效。2.3 注册 Gitee 账号并完成实名认证然后去 Gitee 官网注册账号。Gitee 的注册流程和其他网站差不多邮箱或手机号都可以注册。注册完成后有一点值得花两分钟做一下实名认证。路径是个人头像 → 设置 → 账号资料 → 实名认证。为什么建议认证因为 Gitee 平台对代码托管有一定管理要求部分操作会限定在已实名账号下进行。认证之后后续创建仓库、推送代码时会少很多麻烦。需要说明的是如果只是个人学习使用不打算发布公开项目那么普通的个人账号权限已经足够实名认证也不涉及任何敏感操作纯粹是平台规则要求的步骤。到这里三件套就齐了VSCode 负责写代码Git 负责版本管理Gitee 账号负责云端存放代码。接下来最关键的一步是打通本机与 Gitee 之间的加密通道。3. SSH 密钥配置一次配置长久免密3.1 为什么一定要用 SSH 而不是 HTTPSGitee 上的仓库地址有两种形式一种是 HTTPS 地址形如https://gitee.com/用户名/仓库名.git一种是 SSH 地址形如gitgitee.com:用户名/仓库名.git。很多教程会直接让你用 HTTPS 地址克隆但实际用下来HTTPS 方式每次 push 都需要输入 Gitee 的用户名和密码非常麻烦。虽然有的环境会弹出窗口帮你记住密码但不同系统下记住密码的机制还不一样容易出问题。SSH 的原理是在本地生成一对密钥一个是私钥留在自己电脑上相当于你家的钥匙另一个是公钥放到 Gitee 服务器上相当于你上报给小区的门禁信息。以后本机和 Gitee 通信时双方通过这对密钥自动验证身份你不需要再手动输入账号密码。这就像小区门禁刷脸录过一次脸之后每次进门不用掏卡。3.2 生成 SSH 密钥的具体命令打开终端窗口Windows 下建议直接用 PowerShell 或 CMD输入以下命令ssh-keygen -t rsa -b 4096 -C 你的邮箱-t rsa指定密钥类型为 RSA-b 4096指定密钥长度为 4096 位。如果不加-b参数默认可能是 2048 位但 4096 位更安全。-C后面的内容是一个注释随便写邮箱或者昵称都行主要是方便自己认出这把钥匙是给谁用的。按回车后系统会询问要保存的位置默认是用户目录下的.ssh文件夹直接回车确认即可。接着系统会提示输入 passphrase密码短语这一步可以留空直接回车也可以设置一个密码短语。设置密码短语的好处是即使别人拿到你的私钥文件没有短语也打不开缺点是每次使用私钥都要输入短语。我个人建议本地个人电脑上留空方便日常使用如果是公司电脑建议设置一个。生成完成后在终端里执行cat ~/.ssh/id_rsa.pub这会把公钥内容打印在屏幕上。公钥是以ssh-rsa开头的一长串文本结尾通常是你刚才输入的邮箱。从ssh-rsa开头开始到邮箱结束全部复制下来。3.3 在 Gitee 后台粘贴公钥并验证连接登录 Gitee 网页端点击右上角头像进入“设置”在左侧菜单找到“SSH 公钥”或“安全设置”里的 SSH 公钥管理页面。点击“添加公钥”把刚才复制的公钥粘贴到大文本框里标题可以随便写比如“我的笔记本电脑”。确认添加。添加成功后回到本地终端执行验证命令ssh -T gitgitee.com第一次执行时会提示是否确认连接输入yes回车即可。接着如果看到类似 “Hi, 你的昵称! Youve successfully authenticated, but GITEE.COM does not provide shell access.” 的消息就说明 SSH 配置成功你和 Gitee 之间的通道已经打通了。这一步做完之后以后克隆和推送都不需要再输入密码。4. 创建 Gitee 仓库并克隆到本地4.1 新建仓库时各个字段怎么填打开 Gitee 首页登录后点击右上角的“”号选择“新建仓库”。这里有几个字段会让你填很多新手容易犹豫我一个个说。仓库名称必填项。建议全部用英文、小写单词之间用连字符-或下划线_连接。比如你想做一个个人博客就叫my-blog想放课程设计的代码就叫course-design。尽量避免中文、空格和大小写混用虽然 Gitee 技术上支持但后续在命令行操作时容易出现编码问题。路径一般会根据仓库名称自动生成可以修改仓库的访问地址里会用到这个路径。开源许可证这一步很多人会卡住。如果是私有仓库或仅自己使用的项目随便选“不使用”。如果要公开给别人用最常见的几种选择我给你们列个参考。MIT 许可证最宽松别人拿到你的代码可以随意使用修改甚至商用只要保留版权声明适合个人项目分享。Apache 2.0 类似 MIT但额外包含专利授权条款适合有一定规模的开源项目。GPL 则有传染性别人用了你的代码他的项目也必须开源适合你想强制“下游也开源”的场景。新手如果不确定公开项目直接选 MIT 一般没错。初始化仓库建议勾选“生成 README 文件”和“添加 .gitignore”。README 是项目的说明文档写清楚项目是干什么的、怎么运行别人通过 Gitee 页面第一眼就能看到。.gitignore 的作用是定义哪些文件不需要纳入版本管理比如 Python 项目里的__pycache__缓存文件夹、C/C 编译生成的 exe 文件、Node 项目里的node_modules依赖目录这些都该被忽略。选择分支模型一般默认即可现在 Gitee 默认主分支名通常是master有些新项目会提供main的选项。不管哪个第一次推送时注意匹配就行。填好之后点击“创建”仓库就建好了。创建完成后页面会跳到仓库主页你会在页面上方看到两种克隆地址一个 HTTPS一个 SSH。因为我们前面配好了 SSH这里直接点 SSH 地址旁边的复制按钮。4.2 克隆仓库到本地的两种方式在本地选择一个合适的目录打开终端。比如你想把项目放在D:\workspace下就执行cd D:\workspace然后执行克隆命令git clone 粘贴你复制的SSH地址执行后 Gitee 的仓库内容就会下载到当前目录下的一个文件夹里文件夹名就是仓库名。克隆完成后进入该文件夹cd 仓库名然后执行code .直接用 VSCode 打开当前文件夹开始写代码。也可以先打开 VSCode通过“文件—打开文件夹”选择刚才克隆下来的目录。克隆下来的目录里自带.git隐藏文件夹这个文件夹里记录着整个仓库的版本历史不需要手动管它。4.3 项目本地目录里有哪些东西需要理解新建仓库时如果勾选了初始化克隆下来后你会看到README.md文件和.gitignore文件。README.md是用 Markdown 语法写的说明文档可以用 VSCode 打开直接编辑。.gitignore 里已经预置了很多语言的忽略规则但它不是自动识别语言的是根据你选的语言模板生成的。建议在项目里新建一个测试文件试试手比如新建一个hello.py或index.html随便写几行内容后面我们用这个文件走一遍完整的上传流程。5. 使用 VSCode 完成第一次代码上传5.1 认识 VSCode 的源代码管理面板在 VSCode 左侧活动栏上找到“源代码管理”图标图标大概是一个带圆点的分叉形状快捷键是CtrlShiftG。我们刚才在项目里新建的文件在这个面板里会显示出来旁边会有一个字母U代表 untracked意思是这个文件还没有被 Git 追踪。这是 Git 世界的第一个重要概念工作区、暂存区、本地仓库、远程仓库。可以先做一个类比。工作区就是你电脑上能看到的文件夹。暂存区相当于一个“待提交清单”你从一堆改动的文件里挑出这次准备提交哪些把它们先加入清单。本地仓库是提交动作的落点一次提交会生成一个快照记录当前清单里所有文件的内容。远程仓库就是 Gitee 上的仓库把本地仓库同步上去的动作叫推送。5.2 git status 与 git add 的配合使用在源代码管理面板里看到新文件后建议还在终端里跑一次git status感受一下命令行和图形界面的对应关系。git status会列出当前仓库里所有改动的文件以及它们的状态。红色表示未添加到暂存区绿色表示已经添加。这时候你可以在源代码管理面板里找到文件那一行点击右侧的“”号就把文件添加到了暂存区也可以直接在终端里执行git add .注意git add .的意思是添加当前目录下所有改动过的文件包括新文件和修改过的文件。如果你是第一次提交整个项目这句话最省事。如果项目里有一些不想提交的文件务必要先写进.gitignore否则一个git add .会把所有东西都加进去。5.3 git commit给当前状态拍一张快照文件加入暂存区后VSCode 源代码管理面板顶部的输入框会变成可输入状态在这里输入本次提交的说明比如“第一次提交添加 hello.py”然后点击输入框上方的对勾按钮或者按CtrlEnter就完成了一次本地提交。终端操作则对应git commit -m 第一次提交添加 hello.py-m后面的引号内容是提交信息。提交信息是给人看的所以要写得清楚明白不要写“111”“aaa”这种没意义的内容。将来你回头看项目历史时全靠这些信息理解每一步做了什么。如果此时报错Please tell me who you are说明第二步的全局用户名邮箱没配好回去执行那两条git config --global命令再回来提交。5.4 git push把本地版本推送到 Gitee提交只是把快照保存在了本地仓库远端 Gitee 还看不到任何变化。接下来就是整个教程的关键动作——推送。在 VSCode 源代码管理面板上如果当前分支是master你会看到一个“发布更改”按钮点击它会自动执行推送。如果你更习惯终端执行git push -u origin master这里origin是远程仓库的默认别名master是本地分支名。-u参数的作用是建立本地分支与远程分支的关联这样以后执行git push或git pull时可以省略后面这些参数。如果你的仓库主分支名是main就把命令里的master换成main。推送成功后回到 Gitee 仓库网页刷新页面你会看到刚才本地提交的文件已经出现在网页上了提交记录里也能看到你的提交信息。从这一步开始你的代码就已经实现了云端备份。5.5 第一次推送时容易忽略的几个细节有几个细节我在带新人时反复提醒。第一个推送时如果遇到fatal: remote origin already exists说明这个本地目录已经关联过一个远程仓库需要先检查一下git remote -v看看关联的地址对不对不对的话用git remote set-url origin 新地址修改。第二个如果你在网页端创建仓库时勾选了“初始化仓库”本地又是用 git init 新建的项目两者之间可能没有共同的历史推送时会提示failed to push some refs解决办法是先执行git pull origin master --allow-unrelated-histories再推送。第三个我强烈建议新手第一次推送不要急着在网页端直接编辑 README 或其他文件。很多人喜欢在网页上顺手改个内容本地也改同一个文件下次推时就冒出冲突。刚入门时先统一习惯一切修改从本地开始最终都通过 push 同步到远端。6. 日常协作与更新pull、分支、冲突处理6.1 git pull每天开工前先同步最新代码当你换了另一台电脑或者和同学协作别人已经把代码推到远端了你本地还是旧版本。这时候直接改代码再提交大概率会遇到冲突。正确的习惯是每次开始写代码之前先执行一次git pull把远端最新的代码拉下来。git pull实际上包含两个动作先从远端下载最新的提交记录到本地然后把下载下来的改动合并到你当前的工作分支里。在 VSCode 里源代码管理面板右上角也有一个“同步更改”按钮点击后它会先 pull 再 push。我个人的建议是手动执行git pull看清楚输出结果确认没有冲突后再继续开发不要一键“同步”了事。如果 pull 之后终端输出了Already up to date说明本地已经是最新版本没有任何改动需要拉取。6.2 分支操作主分支别乱推分支才是日常主力版本管理进入团队协作阶段后最核心的概念就是分支。可以这样理解master或main分支是主干道是稳定的代码版本你可以从主干道上分出一条小路在分支上随便试验不会影响主干道。等分支上的代码稳定了再把小路合并回主干道。在终端里执行以下命令创建一个新分支并切换过去git checkout -b dev执行git branch可以查看当前所有分支当前所在分支前会有个星号。VSCode 左下角会显示当前分支名点击它可以直接在弹出来的列表里切换分支。在开发分支上完成代码修改后按我们之前学过的流程 add、commit然后推送git push -u origin dev推送分支时同样需要-u建立关联。推送完之后你想把 dev 分支合并回 main需要先切回 main再执行合并git checkout master git merge dev对于新手来说可能很长一段时间都用不到分支但哪怕是自己一个人写代码分支也是个保护伞。比如我想尝试重构某个模块但又怕把好好的代码搞坏就先开一个分支去改不行就删掉分支主分支毫发无损。6.3 代码冲突的本质以及解决思路冲突是很多新手最害怕遇到的情况但其实它并不可怕只要理解了原因解决起来就很简单。冲突的本质是你和某人同时修改了同一个文件的同一行内容Git 不知道该听谁的。Git 会尝试自动合并不同的改动但如果改动发生在同一个位置它就无能为力了只能请你人工裁决。发生冲突后终端会提示CONFLICT (content): Merge conflict in 文件名对应的文件在 VSCode 里也会标记出来。打开文件你会看到类似这样的内容 HEAD 这是本地的修改 这是远端拉下来的修改 origin/dev HEAD和之间是你本地当前分支的内容和之间是对方分支的内容。VSCode 针对冲突提供了几个快捷选项“接受当前更改”“接受传入更改”“接受两者更改”。如果两个改动是有先后关系的点“接受两者”最方便如果内容完全不同需要取舍就手动编辑把标记符号删除保留想要的内容。解决完文件内容后保存文件执行git add 文件名把它标记为冲突已解决然后git commit提交这次合并。整个过程中不必慌冲突不是错误它是版本管理帮助你规避代码覆盖的保护机制。7. 热词场景扩展环境配置、插件与常见实操需求7.1 用 VSCode 配置 C/C、Python 等开发环境热词里搜“VSCode 配置 C/C 环境”的人非常多这里顺带展开一下思路。VSCode 本身不包含编译器它只是编辑器所以配置 C/C 环境的关键是安装编译器。Windows 下最常见的是 MinGW-w64安装后把其中 bin 目录的路径配置到系统环境变量里然后 VSCode 安装 C/C 扩展再配置tasks.json和launch.json两个文件就能用 F5 键编译调试了。Python 简单很多装好 Python 解释器后在 VSCode 里安装 Python 扩展CtrlShiftP打开命令面板输入“Python: Select Interpreter”选中解释器就能直接运行 py 文件。需要特别提醒的是环境配置类教程非常容易过期因为工具版本更新快网上搜到的旧教程可能已经不适用。我的建议是遇到报错时先看错误信息里的关键词再针对性搜索而不是整个教程从头再走一遍。另外VSCode 里配置环境折腾来折腾去其实和 Gitee 推送不冲突不要因为环境没配好就影响代码托管学习。7.2 实用插件推荐哪些值得装哪些建议别装热门搜索词里关于“VSCode 插件”“插件推荐”的内容很多这里我说一些真正用得上的。中文语言包是必备的Git 相关的插件里 GitLens 能看到每行代码是谁写的、何时写的对理解项目历史帮助很大Git Graph 会把分支提交历史可视化理解分支操作时一目了然。写代码辅助类插件按需安装比如写 Python 的有 Python、Pylance写了 C/C 的有 C/C前端写 HTML/CSS/JS 的有 ESLint、Prettier。需要提醒的是插件不是越多越好。很多新手看到推荐列表就一股脑全装结果 VSCode 启动变慢、右下角频繁弹提示反而影响体验。我的习惯是先裸奔一段时间等真的觉得缺某个功能再去搜插件。这样你装插件时更清楚自己在解决什么问题。7.3 其他 IDE 与工具如何操作 Gitee热词里有不少关于“PyCharm 上传代码到 Gitee”“IDEA 提交代码到 Gitee”的搜索。这些 IDE 也是图形化操作 Git思路和 VSCode 源代码管理面板几乎一致。PyCharm 和 IDEA 通常在菜单栏里有 VCS 菜单选择“Share Project on Gitee”或“Share Project on GitHub”就能直接把项目共享到远端。不过两个 JetBrains 系 IDE 默认对 Gitee 的支持不如 GitHub 完善更常见的做法是先用 Git 命令git init和git remote add关联远端之后再用 IDE 的图形化按钮提交推送。这也是为什么我建议新手先学命令行操作的原因图形界面每换一个软件就变一套但思路一模一样。命令行学明白了换到任何一个 IDE 里你都会非常自然地找到对应的图形按钮。8. 常见问题与排查技巧实录8.1 高频报错对照速查表这一节我直接整理一个高频报错表每个问题都是实际带人时踩过无数次的坑。报错信息原因解决办法Permission denied (publickey)SSH 公钥没配置成功或本机没找到私钥检查 Gitee 后台是否已粘贴公钥执行ssh -T gitgitee.com验证确保公私钥文件在默认路径下Please tell me who you are没配置全局用户名和邮箱执行git config --global user.name、git config --global user.emailfatal: remote origin already exists当前项目已经关联过远程仓库执行git remote -v查看关联地址用git remote set-url origin 新地址修正failed to push some refs本地远程仓库历史不一致通常因为两边都做了初始化先执行git pull origin master --allow-unrelated-histories再 pushfatal: unable to access网络问题或克隆地址填错确认地址格式国内网络通常不需要额外处理重试一次中文文件名或内容乱码终端编码和 Git 配置不一致在 Windows 终端执行git config --global core.quotepath false确认文件本身是 UTF-8 编码8.2 实操中容易踩的细节坑有几个坑不是报错但比报错更容易消耗人的耐心。第一个是推大文件。Gitee 默认限制单文件不超过 100MB如果你的项目里塞了一个很大的视频或数据包push 时会失败。解决办法是确认哪些文件属于产物而不是源码把它们添加进 .gitignore或者考虑用 Git LFS 管理大文件。第二个是忘记 .gitignore结果本地把node_modules推上去了仓库瞬间变得又大又乱再想清理非常麻烦。正确做法是项目一开始就写好 .gitignore宁可先多写几条规则也不要在后期追悔莫及。第三个坑是“在网页端和本地同时改了文件”。新手在学习 Git 的早期阶段习惯在 Gitee 网页上修改 README本地也会经常编辑 README两边内容不一致下一次 pull 或 push 时就出现冲突。我的建议是初期阶段所有文件都从本地改网页端只负责浏览。等你熟练了 pull、merge 之后再随意在网页端操作也不迟。8.3 我给新手的几个实用操作建议最后分享几个我个人的使用习惯。第一个给常用命令做一张小抄贴在电脑旁边包括git status、git add .、git commit -m 说明、git push、git pull、git branch、git checkout -b 分支名、git log。每天用 Git 操作时先看小抄慢慢这些命令就刻在肌肉记忆里了。第二个每次 commit 不要攒一大堆文件才提一次。一个功能或一个修复对应一次提交信息写清楚这样将来排查问题能精确定位是哪一次改动引入了 bug。提交信息建议用简洁的动词开头比如“添加登录页面”“修复首页样式错乱”“重构数据库连接代码”。第三个遇到搞不懂的状态时先执行git status再看 VSCode 源代码管理面板两次的信息是同步的。对照着看能帮你把抽象的命令和具体的图形界面关联起来以后就不怕黑底白字了。结尾这套 VSCode 加 Gitee 的工作流陪我走过了写课程设计、做个人项目、小团队协作这几个阶段。刚入门那会儿我也觉得 Git 是一个很难学的庞然大物后来发现其实核心操作就那么几个。真正的进步不是背下全部命令而是在一次次 commit、push 中逐步理解了版本管理为什么存在、它能给你带来什么保护。代码不是写出来就结束了能把它管好、存好、协作好才是职业成长里很重要的一步。希望这篇保姆级教程能帮你迈出第一步。 VSCode与Gitee保姆级教程：从零配置到代码推送与团队协作
最近几年我发现身边越来越多刚接触编程的朋友第一句问的基本都是同一句话“我写的代码到底要怎么传到网上去保存” 这个需求特别真实不管是写课程设计、个人博客还是在公司做项目协作代码都不应该只躺在自己电脑里。今天这篇保姆级教程我就直接把 VSCode 和 Gitee 这套组合掰开揉碎从注册账号开始一直到把本地代码成功推到远程仓库全部走一遍。关键是这篇文章不预设你已经具备任何 Git 基础只要你会用电脑打字跟着一步步做就能跑通整个流程。这套方案适合谁呢比如正在学校交课设的大学生比如准备把练习项目整理出来找工作用的转行者再比如小团队里想统一管理代码但不想折腾太复杂架构的开发者。Gitee 是国内访问速度极快的代码托管平台VSCode 则是目前生态最活跃的代码编辑器两个一配合你就能拥有一个“本地写代码 云端备份 团队协作”的完整工作流。这篇文章会把每一步的原理也讲清楚不光是让你照着抄还让你明白为什么要这么做。1. 内容整体设计与思路拆解1.1 为什么是 VSCode 加 Gitee 这个组合先聊一个很多人忽略的问题编辑器那么多为什么选 VSCode代码托管平台也不少为什么选 Gitee这套组合说白了就是“写代码的桌面工具 放代码的云端仓库”。VSCode 的优势在于它免费、开源、跨平台Windows、macOS、Linux 通吃而且插件生态极其丰富。安装一个 Python 插件就能写 Python安装一个 C/C 插件就能写 C 和 C不需要像以前那样换一个语言就换一套 IDE。Gitee 这边最大的优势是服务器在国内。早些年大家习惯去 GitHub 存代码但国内网络访问 GitHub 的速度经常不稳定推送一个大一点的项目可能要等很久甚至直接失败。Gitee 基本没有这种问题创建仓库、克隆、推送速度都非常快更适合国内用户日常使用。另外Gitee 免费用户也能创建私有仓库个人练习项目不想公开的话选私有就完全够用。还有一个容易被忽略的点Gitee 对新手非常友好。它的网页界面是全中文的仓库创建向导里各项字段解释得很清楚对“开源许可证”“README”这类概念还配了说明。相比之下GitHub 的界面和术语对英语不好的同学就有一点门槛。对于第一次接触代码托管的人来说先用 Gitee 把 GitHub 的操作逻辑弄明白将来再切换成本也不高。1.2 这套方案能帮你解决什么问题新手学代码时最常遇到的一个痛点是代码写了一堆但不知道怎么管理版本。比如有一天把程序改坏了想退回之前的能运行版本如果靠手动复制文件夹过几天就分不清哪个是最新的了。Git 的作用就是帮你记录每一次修改就像一个游戏存档系统你想回到哪一关都可以。但 Git 本身是命令行工具很多初学者看到黑底白字的终端窗口就压力山大。VSCode 的源代码管理面板把 Git 的常用操作都做成了可视化按钮鼠标点一点就能完成提交、推送、拉取等操作大大降低了学习门槛。我在带新人时经常跟他们说你不需要背几十个 Git 命令先掌握 add、commit、push、pull 这四个就够用了其余的命令用到的时候再查。再来说说“帮别人看代码”这个场景。以前你想让同学帮你看看代码哪里写错了通常是把整个项目打包成 zip 发过去对方改完再回传一个 zip一来二去版本就混乱了。有了 Gitee 远程仓库后你把代码推进仓库别人直接克隆或拉取最新版本改完再推送回来整个过程清清楚楚。这就是代码托管最朴素的协作价值。1.3 整体学习的路线规划我给这份教程规划的学习路线是“环境准备 → 密钥配置 → 仓库创建 → 本地操作 → 日常协作”。前两步属于一劳永逸的事做一次以后就不用再管。第三步是理解整个流程的关键节点知道代码到底存在哪里。第四步是核心操作学会之后你就能把所有项目都纳入版本管理。第五步属于进阶理解了之后你会知道为什么有些项目会出现代码冲突以及怎么解决冲突。每一部分我都会给出操作步骤和背后的原因遇到容易出错的地方还会专门提醒。学完这篇教程之后你再回头看那些“上传代码到 Gitee”的零散问答帖基本都能看懂了因为底层逻辑你已经通了。2. 新环境准备从零装好三件套2.1 VSCode 下载安装的细节与验证第一步自然是安装 VSCode。网上搜索“VSCode 官网”的时候要多留个心眼有些搜索结果点进去是下载站会捆绑各种乱七八糟的东西。认准官方域名一般是以code.visualstudio.com开头的那个。进入官网后首页会显示一个很明显的下载按钮它会根据你的操作系统自动推荐对应版本。Windows 用户选择 x64 版本的 User Installer 即可如果你是 Windows 7 系统注意看一下历史版本说明新版 VSCode 已经不支持 Win7 了需要去官方文档里找旧版本。下载完成后双击安装包开始安装。这个安装过程中有几个选项值得留意。第一建议勾选“添加到 PATH”也就是“Add to PATH”这个选项这样以后你想在终端里直接输入code命令打开当前目录就方便多了。第二建议勾选“通过 Code 打开”操作菜单里的选项比如“添加到‘打开方式’列表”这样在文件管理器里右键一个文件夹就能直接用 VSCode 打开。这些选项在安装时都可以通过勾选实现如果当初没勾也可以不改装直接在 VSCode 里用“文件—打开文件夹”也能解决问题。安装完成后第一次打开 VSCode你会看到英文界面。对完全不熟悉英文的同学来说可以直接先设置中文。按快捷键CtrlShiftP打开命令面板输入“Configure Display Language”选择“Install additional languages”在插件列表里搜索安装“Chinese (Simplified) Language Pack for Visual Studio Code”。安装完成后按提示重启界面就是中文了。2.2 安装 Git 并完成基础身份配置有了 VSCode 之后还需要装一个 Git。VSCode 只是一个编辑器和操作界面真正执行版本管理命令的还是 Git 这个工具本体。可以这么理解VSCode 是仪表盘Git 是发动机。去 Git 官网下载对应操作系统的安装包Windows 下是 Git for Windows下载完成后一路 Next 即可。安装完成后打开任意终端窗口Windows 下打开 PowerShell 或 CMD输入git --version如果看到类似git version 2.40.0的输出就说明安装成功。接下来要做一件事配置你的用户名和邮箱。这个信息会跟随每一次提交别人看仓库提交记录时能知道是谁改的。执行以下两行命令把名字和邮箱替换成你自己的注意这里建议使用和 Gitee 注册时一致的邮箱git config --global user.name 你的昵称 git config --global user.email 你的邮箱--global参数的意思是全局生效以后这台电脑上的所有 Git 仓库都会用这个身份提交。这一步很多人会漏掉结果第一次 commit 时报错Please tell me who you are其实就是没配身份。配完之后可以再执行git config --list检查一下配置是否生效。2.3 注册 Gitee 账号并完成实名认证然后去 Gitee 官网注册账号。Gitee 的注册流程和其他网站差不多邮箱或手机号都可以注册。注册完成后有一点值得花两分钟做一下实名认证。路径是个人头像 → 设置 → 账号资料 → 实名认证。为什么建议认证因为 Gitee 平台对代码托管有一定管理要求部分操作会限定在已实名账号下进行。认证之后后续创建仓库、推送代码时会少很多麻烦。需要说明的是如果只是个人学习使用不打算发布公开项目那么普通的个人账号权限已经足够实名认证也不涉及任何敏感操作纯粹是平台规则要求的步骤。到这里三件套就齐了VSCode 负责写代码Git 负责版本管理Gitee 账号负责云端存放代码。接下来最关键的一步是打通本机与 Gitee 之间的加密通道。3. SSH 密钥配置一次配置长久免密3.1 为什么一定要用 SSH 而不是 HTTPSGitee 上的仓库地址有两种形式一种是 HTTPS 地址形如https://gitee.com/用户名/仓库名.git一种是 SSH 地址形如gitgitee.com:用户名/仓库名.git。很多教程会直接让你用 HTTPS 地址克隆但实际用下来HTTPS 方式每次 push 都需要输入 Gitee 的用户名和密码非常麻烦。虽然有的环境会弹出窗口帮你记住密码但不同系统下记住密码的机制还不一样容易出问题。SSH 的原理是在本地生成一对密钥一个是私钥留在自己电脑上相当于你家的钥匙另一个是公钥放到 Gitee 服务器上相当于你上报给小区的门禁信息。以后本机和 Gitee 通信时双方通过这对密钥自动验证身份你不需要再手动输入账号密码。这就像小区门禁刷脸录过一次脸之后每次进门不用掏卡。3.2 生成 SSH 密钥的具体命令打开终端窗口Windows 下建议直接用 PowerShell 或 CMD输入以下命令ssh-keygen -t rsa -b 4096 -C 你的邮箱-t rsa指定密钥类型为 RSA-b 4096指定密钥长度为 4096 位。如果不加-b参数默认可能是 2048 位但 4096 位更安全。-C后面的内容是一个注释随便写邮箱或者昵称都行主要是方便自己认出这把钥匙是给谁用的。按回车后系统会询问要保存的位置默认是用户目录下的.ssh文件夹直接回车确认即可。接着系统会提示输入 passphrase密码短语这一步可以留空直接回车也可以设置一个密码短语。设置密码短语的好处是即使别人拿到你的私钥文件没有短语也打不开缺点是每次使用私钥都要输入短语。我个人建议本地个人电脑上留空方便日常使用如果是公司电脑建议设置一个。生成完成后在终端里执行cat ~/.ssh/id_rsa.pub这会把公钥内容打印在屏幕上。公钥是以ssh-rsa开头的一长串文本结尾通常是你刚才输入的邮箱。从ssh-rsa开头开始到邮箱结束全部复制下来。3.3 在 Gitee 后台粘贴公钥并验证连接登录 Gitee 网页端点击右上角头像进入“设置”在左侧菜单找到“SSH 公钥”或“安全设置”里的 SSH 公钥管理页面。点击“添加公钥”把刚才复制的公钥粘贴到大文本框里标题可以随便写比如“我的笔记本电脑”。确认添加。添加成功后回到本地终端执行验证命令ssh -T gitgitee.com第一次执行时会提示是否确认连接输入yes回车即可。接着如果看到类似 “Hi, 你的昵称! Youve successfully authenticated, but GITEE.COM does not provide shell access.” 的消息就说明 SSH 配置成功你和 Gitee 之间的通道已经打通了。这一步做完之后以后克隆和推送都不需要再输入密码。4. 创建 Gitee 仓库并克隆到本地4.1 新建仓库时各个字段怎么填打开 Gitee 首页登录后点击右上角的“”号选择“新建仓库”。这里有几个字段会让你填很多新手容易犹豫我一个个说。仓库名称必填项。建议全部用英文、小写单词之间用连字符-或下划线_连接。比如你想做一个个人博客就叫my-blog想放课程设计的代码就叫course-design。尽量避免中文、空格和大小写混用虽然 Gitee 技术上支持但后续在命令行操作时容易出现编码问题。路径一般会根据仓库名称自动生成可以修改仓库的访问地址里会用到这个路径。开源许可证这一步很多人会卡住。如果是私有仓库或仅自己使用的项目随便选“不使用”。如果要公开给别人用最常见的几种选择我给你们列个参考。MIT 许可证最宽松别人拿到你的代码可以随意使用修改甚至商用只要保留版权声明适合个人项目分享。Apache 2.0 类似 MIT但额外包含专利授权条款适合有一定规模的开源项目。GPL 则有传染性别人用了你的代码他的项目也必须开源适合你想强制“下游也开源”的场景。新手如果不确定公开项目直接选 MIT 一般没错。初始化仓库建议勾选“生成 README 文件”和“添加 .gitignore”。README 是项目的说明文档写清楚项目是干什么的、怎么运行别人通过 Gitee 页面第一眼就能看到。.gitignore 的作用是定义哪些文件不需要纳入版本管理比如 Python 项目里的__pycache__缓存文件夹、C/C 编译生成的 exe 文件、Node 项目里的node_modules依赖目录这些都该被忽略。选择分支模型一般默认即可现在 Gitee 默认主分支名通常是master有些新项目会提供main的选项。不管哪个第一次推送时注意匹配就行。填好之后点击“创建”仓库就建好了。创建完成后页面会跳到仓库主页你会在页面上方看到两种克隆地址一个 HTTPS一个 SSH。因为我们前面配好了 SSH这里直接点 SSH 地址旁边的复制按钮。4.2 克隆仓库到本地的两种方式在本地选择一个合适的目录打开终端。比如你想把项目放在D:\workspace下就执行cd D:\workspace然后执行克隆命令git clone 粘贴你复制的SSH地址执行后 Gitee 的仓库内容就会下载到当前目录下的一个文件夹里文件夹名就是仓库名。克隆完成后进入该文件夹cd 仓库名然后执行code .直接用 VSCode 打开当前文件夹开始写代码。也可以先打开 VSCode通过“文件—打开文件夹”选择刚才克隆下来的目录。克隆下来的目录里自带.git隐藏文件夹这个文件夹里记录着整个仓库的版本历史不需要手动管它。4.3 项目本地目录里有哪些东西需要理解新建仓库时如果勾选了初始化克隆下来后你会看到README.md文件和.gitignore文件。README.md是用 Markdown 语法写的说明文档可以用 VSCode 打开直接编辑。.gitignore 里已经预置了很多语言的忽略规则但它不是自动识别语言的是根据你选的语言模板生成的。建议在项目里新建一个测试文件试试手比如新建一个hello.py或index.html随便写几行内容后面我们用这个文件走一遍完整的上传流程。5. 使用 VSCode 完成第一次代码上传5.1 认识 VSCode 的源代码管理面板在 VSCode 左侧活动栏上找到“源代码管理”图标图标大概是一个带圆点的分叉形状快捷键是CtrlShiftG。我们刚才在项目里新建的文件在这个面板里会显示出来旁边会有一个字母U代表 untracked意思是这个文件还没有被 Git 追踪。这是 Git 世界的第一个重要概念工作区、暂存区、本地仓库、远程仓库。可以先做一个类比。工作区就是你电脑上能看到的文件夹。暂存区相当于一个“待提交清单”你从一堆改动的文件里挑出这次准备提交哪些把它们先加入清单。本地仓库是提交动作的落点一次提交会生成一个快照记录当前清单里所有文件的内容。远程仓库就是 Gitee 上的仓库把本地仓库同步上去的动作叫推送。5.2 git status 与 git add 的配合使用在源代码管理面板里看到新文件后建议还在终端里跑一次git status感受一下命令行和图形界面的对应关系。git status会列出当前仓库里所有改动的文件以及它们的状态。红色表示未添加到暂存区绿色表示已经添加。这时候你可以在源代码管理面板里找到文件那一行点击右侧的“”号就把文件添加到了暂存区也可以直接在终端里执行git add .注意git add .的意思是添加当前目录下所有改动过的文件包括新文件和修改过的文件。如果你是第一次提交整个项目这句话最省事。如果项目里有一些不想提交的文件务必要先写进.gitignore否则一个git add .会把所有东西都加进去。5.3 git commit给当前状态拍一张快照文件加入暂存区后VSCode 源代码管理面板顶部的输入框会变成可输入状态在这里输入本次提交的说明比如“第一次提交添加 hello.py”然后点击输入框上方的对勾按钮或者按CtrlEnter就完成了一次本地提交。终端操作则对应git commit -m 第一次提交添加 hello.py-m后面的引号内容是提交信息。提交信息是给人看的所以要写得清楚明白不要写“111”“aaa”这种没意义的内容。将来你回头看项目历史时全靠这些信息理解每一步做了什么。如果此时报错Please tell me who you are说明第二步的全局用户名邮箱没配好回去执行那两条git config --global命令再回来提交。5.4 git push把本地版本推送到 Gitee提交只是把快照保存在了本地仓库远端 Gitee 还看不到任何变化。接下来就是整个教程的关键动作——推送。在 VSCode 源代码管理面板上如果当前分支是master你会看到一个“发布更改”按钮点击它会自动执行推送。如果你更习惯终端执行git push -u origin master这里origin是远程仓库的默认别名master是本地分支名。-u参数的作用是建立本地分支与远程分支的关联这样以后执行git push或git pull时可以省略后面这些参数。如果你的仓库主分支名是main就把命令里的master换成main。推送成功后回到 Gitee 仓库网页刷新页面你会看到刚才本地提交的文件已经出现在网页上了提交记录里也能看到你的提交信息。从这一步开始你的代码就已经实现了云端备份。5.5 第一次推送时容易忽略的几个细节有几个细节我在带新人时反复提醒。第一个推送时如果遇到fatal: remote origin already exists说明这个本地目录已经关联过一个远程仓库需要先检查一下git remote -v看看关联的地址对不对不对的话用git remote set-url origin 新地址修改。第二个如果你在网页端创建仓库时勾选了“初始化仓库”本地又是用 git init 新建的项目两者之间可能没有共同的历史推送时会提示failed to push some refs解决办法是先执行git pull origin master --allow-unrelated-histories再推送。第三个我强烈建议新手第一次推送不要急着在网页端直接编辑 README 或其他文件。很多人喜欢在网页上顺手改个内容本地也改同一个文件下次推时就冒出冲突。刚入门时先统一习惯一切修改从本地开始最终都通过 push 同步到远端。6. 日常协作与更新pull、分支、冲突处理6.1 git pull每天开工前先同步最新代码当你换了另一台电脑或者和同学协作别人已经把代码推到远端了你本地还是旧版本。这时候直接改代码再提交大概率会遇到冲突。正确的习惯是每次开始写代码之前先执行一次git pull把远端最新的代码拉下来。git pull实际上包含两个动作先从远端下载最新的提交记录到本地然后把下载下来的改动合并到你当前的工作分支里。在 VSCode 里源代码管理面板右上角也有一个“同步更改”按钮点击后它会先 pull 再 push。我个人的建议是手动执行git pull看清楚输出结果确认没有冲突后再继续开发不要一键“同步”了事。如果 pull 之后终端输出了Already up to date说明本地已经是最新版本没有任何改动需要拉取。6.2 分支操作主分支别乱推分支才是日常主力版本管理进入团队协作阶段后最核心的概念就是分支。可以这样理解master或main分支是主干道是稳定的代码版本你可以从主干道上分出一条小路在分支上随便试验不会影响主干道。等分支上的代码稳定了再把小路合并回主干道。在终端里执行以下命令创建一个新分支并切换过去git checkout -b dev执行git branch可以查看当前所有分支当前所在分支前会有个星号。VSCode 左下角会显示当前分支名点击它可以直接在弹出来的列表里切换分支。在开发分支上完成代码修改后按我们之前学过的流程 add、commit然后推送git push -u origin dev推送分支时同样需要-u建立关联。推送完之后你想把 dev 分支合并回 main需要先切回 main再执行合并git checkout master git merge dev对于新手来说可能很长一段时间都用不到分支但哪怕是自己一个人写代码分支也是个保护伞。比如我想尝试重构某个模块但又怕把好好的代码搞坏就先开一个分支去改不行就删掉分支主分支毫发无损。6.3 代码冲突的本质以及解决思路冲突是很多新手最害怕遇到的情况但其实它并不可怕只要理解了原因解决起来就很简单。冲突的本质是你和某人同时修改了同一个文件的同一行内容Git 不知道该听谁的。Git 会尝试自动合并不同的改动但如果改动发生在同一个位置它就无能为力了只能请你人工裁决。发生冲突后终端会提示CONFLICT (content): Merge conflict in 文件名对应的文件在 VSCode 里也会标记出来。打开文件你会看到类似这样的内容 HEAD 这是本地的修改 这是远端拉下来的修改 origin/dev HEAD和之间是你本地当前分支的内容和之间是对方分支的内容。VSCode 针对冲突提供了几个快捷选项“接受当前更改”“接受传入更改”“接受两者更改”。如果两个改动是有先后关系的点“接受两者”最方便如果内容完全不同需要取舍就手动编辑把标记符号删除保留想要的内容。解决完文件内容后保存文件执行git add 文件名把它标记为冲突已解决然后git commit提交这次合并。整个过程中不必慌冲突不是错误它是版本管理帮助你规避代码覆盖的保护机制。7. 热词场景扩展环境配置、插件与常见实操需求7.1 用 VSCode 配置 C/C、Python 等开发环境热词里搜“VSCode 配置 C/C 环境”的人非常多这里顺带展开一下思路。VSCode 本身不包含编译器它只是编辑器所以配置 C/C 环境的关键是安装编译器。Windows 下最常见的是 MinGW-w64安装后把其中 bin 目录的路径配置到系统环境变量里然后 VSCode 安装 C/C 扩展再配置tasks.json和launch.json两个文件就能用 F5 键编译调试了。Python 简单很多装好 Python 解释器后在 VSCode 里安装 Python 扩展CtrlShiftP打开命令面板输入“Python: Select Interpreter”选中解释器就能直接运行 py 文件。需要特别提醒的是环境配置类教程非常容易过期因为工具版本更新快网上搜到的旧教程可能已经不适用。我的建议是遇到报错时先看错误信息里的关键词再针对性搜索而不是整个教程从头再走一遍。另外VSCode 里配置环境折腾来折腾去其实和 Gitee 推送不冲突不要因为环境没配好就影响代码托管学习。7.2 实用插件推荐哪些值得装哪些建议别装热门搜索词里关于“VSCode 插件”“插件推荐”的内容很多这里我说一些真正用得上的。中文语言包是必备的Git 相关的插件里 GitLens 能看到每行代码是谁写的、何时写的对理解项目历史帮助很大Git Graph 会把分支提交历史可视化理解分支操作时一目了然。写代码辅助类插件按需安装比如写 Python 的有 Python、Pylance写了 C/C 的有 C/C前端写 HTML/CSS/JS 的有 ESLint、Prettier。需要提醒的是插件不是越多越好。很多新手看到推荐列表就一股脑全装结果 VSCode 启动变慢、右下角频繁弹提示反而影响体验。我的习惯是先裸奔一段时间等真的觉得缺某个功能再去搜插件。这样你装插件时更清楚自己在解决什么问题。7.3 其他 IDE 与工具如何操作 Gitee热词里有不少关于“PyCharm 上传代码到 Gitee”“IDEA 提交代码到 Gitee”的搜索。这些 IDE 也是图形化操作 Git思路和 VSCode 源代码管理面板几乎一致。PyCharm 和 IDEA 通常在菜单栏里有 VCS 菜单选择“Share Project on Gitee”或“Share Project on GitHub”就能直接把项目共享到远端。不过两个 JetBrains 系 IDE 默认对 Gitee 的支持不如 GitHub 完善更常见的做法是先用 Git 命令git init和git remote add关联远端之后再用 IDE 的图形化按钮提交推送。这也是为什么我建议新手先学命令行操作的原因图形界面每换一个软件就变一套但思路一模一样。命令行学明白了换到任何一个 IDE 里你都会非常自然地找到对应的图形按钮。8. 常见问题与排查技巧实录8.1 高频报错对照速查表这一节我直接整理一个高频报错表每个问题都是实际带人时踩过无数次的坑。报错信息原因解决办法Permission denied (publickey)SSH 公钥没配置成功或本机没找到私钥检查 Gitee 后台是否已粘贴公钥执行ssh -T gitgitee.com验证确保公私钥文件在默认路径下Please tell me who you are没配置全局用户名和邮箱执行git config --global user.name、git config --global user.emailfatal: remote origin already exists当前项目已经关联过远程仓库执行git remote -v查看关联地址用git remote set-url origin 新地址修正failed to push some refs本地远程仓库历史不一致通常因为两边都做了初始化先执行git pull origin master --allow-unrelated-histories再 pushfatal: unable to access网络问题或克隆地址填错确认地址格式国内网络通常不需要额外处理重试一次中文文件名或内容乱码终端编码和 Git 配置不一致在 Windows 终端执行git config --global core.quotepath false确认文件本身是 UTF-8 编码8.2 实操中容易踩的细节坑有几个坑不是报错但比报错更容易消耗人的耐心。第一个是推大文件。Gitee 默认限制单文件不超过 100MB如果你的项目里塞了一个很大的视频或数据包push 时会失败。解决办法是确认哪些文件属于产物而不是源码把它们添加进 .gitignore或者考虑用 Git LFS 管理大文件。第二个是忘记 .gitignore结果本地把node_modules推上去了仓库瞬间变得又大又乱再想清理非常麻烦。正确做法是项目一开始就写好 .gitignore宁可先多写几条规则也不要在后期追悔莫及。第三个坑是“在网页端和本地同时改了文件”。新手在学习 Git 的早期阶段习惯在 Gitee 网页上修改 README本地也会经常编辑 README两边内容不一致下一次 pull 或 push 时就出现冲突。我的建议是初期阶段所有文件都从本地改网页端只负责浏览。等你熟练了 pull、merge 之后再随意在网页端操作也不迟。8.3 我给新手的几个实用操作建议最后分享几个我个人的使用习惯。第一个给常用命令做一张小抄贴在电脑旁边包括git status、git add .、git commit -m 说明、git push、git pull、git branch、git checkout -b 分支名、git log。每天用 Git 操作时先看小抄慢慢这些命令就刻在肌肉记忆里了。第二个每次 commit 不要攒一大堆文件才提一次。一个功能或一个修复对应一次提交信息写清楚这样将来排查问题能精确定位是哪一次改动引入了 bug。提交信息建议用简洁的动词开头比如“添加登录页面”“修复首页样式错乱”“重构数据库连接代码”。第三个遇到搞不懂的状态时先执行git status再看 VSCode 源代码管理面板两次的信息是同步的。对照着看能帮你把抽象的命令和具体的图形界面关联起来以后就不怕黑底白字了。结尾这套 VSCode 加 Gitee 的工作流陪我走过了写课程设计、做个人项目、小团队协作这几个阶段。刚入门那会儿我也觉得 Git 是一个很难学的庞然大物后来发现其实核心操作就那么几个。真正的进步不是背下全部命令而是在一次次 commit、push 中逐步理解了版本管理为什么存在、它能给你带来什么保护。代码不是写出来就结束了能把它管好、存好、协作好才是职业成长里很重要的一步。希望这篇保姆级教程能帮你迈出第一步。