写代码这件事这几年最让我省心的组合就是 VSCode 加 Gitee。VSCode 负责本地编辑、调试、跑插件Gitee 负责代码托管、版本回溯、团队协作两个一接上写项目从零到上线基本不用离开编辑器。这篇教程我按自己从踩坑到熟练的全过程来写把 VSCode 安装、Gitee 仓库创建、SSH 密钥配置、代码克隆推送、常见报错处理全部串一遍尽量少说废话照着做就能跑通。不管你是刚学编程的学生还是想把手头项目托管到 Gitee 的开发者这套流程都适用。1. 环境准备先把 VSCode 和 Git 装利索1.1 VSCode 下载安装与汉化VSCode 全称 Visual Studio Code是微软出的一款免费开源编辑器轻量但扩展性极强装完基础体积才几百兆却几乎能胜任任何语言的开发。下载时直接去官方渠道拿安装包认准 Stable 稳定版别碰 Insider 预览版除非你想当小白鼠。安装过程基本一路下一步但有几个选项值得留意勾选“添加到 PATH”这个一定要勾上否则后面在终端敲code命令打开编辑器可能没反应。勾选“通过 Code 打开”操作菜单勾选后右键文件夹就能直接用 VSCode 打开日常操作方便很多。关联文件类型可以全选也可以不选影响不大。装完默认是英文界面想换成中文很简单打开左侧扩展面板快捷键CtrlShiftX搜索“Chinese (Simplified)”安装微软官方出的中文语言包装完右下角会提示重启。重启后菜单栏就是中文了。这个中文语言包只改界面不影响代码和终端输出放心用。1.2 Git 安装与基础验证VSCode 本身只负责编辑代码版本管理靠的是 Git。Gitee 是远程仓库本地代码要推上去必须借助 Git 来完成。先检查系统里有没有装过git --version如果提示找不到命令就去 Git 官网下载对应系统的安装包。在 Windows 上安装时有几个容易误解的选项默认编辑器选择可以选择用 VSCode后面用 Git 的时候会自动唤起。调整 PATH 环境选“Git from the command line and also from 3rd-party software”这条最稳确保命令在任何终端都能用。换行符转换Windows 用户选第一个“Checkout Windows-style, commit Unix-style line endings”就好这样团队里混用 Windows 和 Mac 时不容易出现换行符混乱的问题。装完重新开一个终端输入git --version能输出版本号就说明没问题。还有一句很关键的话Git 第一次使用要交代身份因为每次提交都会记录作者信息。设置命令如下git config --global user.name 你的Gitee用户名 git config --global user.email 你注册Gitee的邮箱别小看这两条不设置的话第一次 commit 会报错或者提交记录显示一堆乱码。2. Gitee 端准备仓库、许可证与 SSH 密钥2.1 创建仓库时到底要怎么选参数Gitee 是国内的代码托管平台类似 GitHub 的国内版访问速度快支持私有仓库免费额度适合个人项目和中小团队。注册账号这种基础操作就不展开说了直接进重点创建仓库时那些选项怎么选。仓库名要一眼能看出用途比如blog-system、my-portfolio不要用test、aaa这种命名。路径名会直接出现在访问地址里如果仓库用于静态托管或开源分享建议全小写、用连字符分隔单词这样 URL 更规整。开源许可证的选择一直有人问到。简单说选许可证是告诉别人“你可以怎么用我的代码”许可证特点适合场景MIT最宽松基本随便用只需保留版权声明个人开源项目、工具库Apache 2.0宽松附带专利授权条款涉及专利的项目GPL传染性较强衍生代码也必须开源希望代码永远开源的项目不选默认保留所有权利私有项目、未决定是否开源如果你只是把自己的学习代码放上去当备份不打算给别人用选个 MIT 就好最省事。如果完全不知道选什么又确定要公开那就 MIT理由是不限制别人使用也不会给后来维护的人挖坑。2.2 SSH 密钥配置不用每次输密码的关键往 Gitee 推送代码有两种常见协议HTTPS 和 SSH。HTTPS 每次推送都要输入账号密码除非用凭据管理器记住SSH 配置好密钥之后一劳永逸推荐直接上 SSH。先检查本地有没有生成过密钥ls -al ~/.ssh一般没有则直接生成。注意把邮箱换成自己注册 Gitee 用的邮箱ssh-keygen -t ed25519 -C 你的Gitee邮箱一路回车即可默认会保存到~/.ssh/id_ed25519。如果系统比较老不支持 ed25519可以用ssh-keygen -t rsa -b 4096替代。生成完成后查看公钥内容cat ~/.ssh/id_ed25519.pub复制整段输出去 Gitee 的“设置 → 安全设置 → SSH 公钥”页面粘贴并保存。然后验证是否配置成功ssh -T gitgitee.com第一次连接会提示是否确认主机指纹输入yes回车。如果看到欢迎语之类的内容说明密钥配置成功。这里有个经验之谈配置密钥时一定确认是id_ed25519.pub这个公钥文件的内容不是id_ed25519私钥。后者绝对不能泄露一旦公开你的代码仓库就任人摆布了。3. 打通本地与远程克隆、提交与推送全流程3.1 用 HTTPS 还是 SSH克隆项目怎么选在 Gitee 仓库页面能看到“克隆/下载”按钮提供 HTTPS 和 SSH 两种地址。选哪个取决于你的使用场景SSH 地址形如gitgitee.com:用户名/仓库名.git。配置好密钥后推送和拉取全程免密。强烈推荐日常开发用它。HTTPS 地址形如https://gitee.com/用户名/仓库名.git。首次操作要输账号密码适合偶尔用一下的临时机器。在 VSCode 里克隆项目有两三种方式最简单的是先打开命令面板CtrlShiftP输入Git: Clone回车后会让你填仓库地址再选一个本地存放目录然后自动开始克隆。也可以在终端执行git clone gitgitee.com:用户名/仓库名.git克隆完成后用 VSCode 打开对应文件夹直接进入开发状态。3.2 首次上传把已有代码推到空仓库把本地已有的项目推送到一个刚建好的空仓库是新手最常卡住的环节。关键点在于默认分支名和远程仓库关联。假设本地项目文件夹叫my-app打开终端进入该目录先初始化 Gitgit init然后看到当前仓库的分支名。新版 Git 默认叫master但 Gitee 新建仓库默认分支是master还是main取决于创建时的选择。最稳妥的做法是创建仓库时把仓库名称、分支名都记下来保持一致。接下来把所有文件加入暂存区并提交git add . git commit -m initial commitgit add .是把当前目录下所有新增和修改的文件都加入暂存。注意如果目录里有 node_modules、编译输出等不需要托管的内容应提前创建.gitignore文件否则会把一堆垃圾文件推上去而且之后同步都受影响。.gitignore的基本写法node_modules/ dist/ *.log .DS_Store提交之后把本地仓库和远程关联起来。远程地址别名统一叫origingit remote add origin gitgitee.com:用户名/仓库名.git首次推送要加上-u参数把本地分支跟远程分支建立关联之后再推就只需要git pushgit push -u origin master如果本地分支名和远程默认分支名不一致比如本地是master远程仓库初始化用了main会推送失败。解决办法是指定推送或者更快的方式是直接改名git branch -M main git push -u origin main3.3 日常迭代改代码、提交、拉取的正确节奏项目跑到日常维护阶段最常见的一套操作就是改代码 → 暂存 → 提交 → 推送。我自己的习惯节奏是开工前先git pull把远程最新代码拉到本地确保自己在最新代码基础上改。完成一个小功能或修完一个 bug及时git add相关文件git commit -m 清晰的提交说明。提交信息尽量写清楚“做了什么、为什么”不要写update、update2这种没有信息量的内容。推送前如果再发现远程有别人更新的代码先git pull再git push能有效减少冲突。这三个命令贯穿整个开发过程熟记即可git status # 查看当前改动状态 git add file # 添加某个文件到暂存区 git commit -m 描述 # 提交暂存区内容 git push # 推送到远程VSCode 左侧的源代码管理面板快捷键CtrlShiftG把这些操作图形化了。修改过的文件会显示在列表里点击文件可以查看行级差异暂存、提交、推送都有按钮非常直观。对于不熟悉终端命令的初学者用面板操作也能完整走通这套流程。3.4 分支操作不要一直在 main 上裸奔分支是 Git 里非常重要但被很多初学者一开始忽略的功能。主线分支main 或 master应该保持稳定、可发布的状态开发新功能时单独开分支验证没问题再合并这样即使写崩了也不会影响主分支。常用的分支命令git branch 新分支名 # 创建分支 git checkout 新分支名 # 切换到该分支 git checkout -b 新分支名 # 创建并切换一条命令搞定 git branch -a # 查看所有本地和远程分支 git merge 新分支名 # 把该分支合并到当前分支在 VSCode 的源代码管理面板底部可以看到当前分支名点击就可以切换或创建分支。Gitee 仓库页面上也会展示所有分支推送上去之后可以直接在网页端查看差异、发合并请求。4. VSCode 里这些插件能让你效率翻倍4.1 必备插件列表VSCode 强大的地方很大程度来自插件生态。下面这几个插件是为 Gitee/Git 工作流服务的装完之后体验提升非常明显GitLens最强大的 Git 插件之一。它能直接在代码行尾显示这行是谁、什么时候、因为什么提交修改的点击能看到完整的提交历史和 diff。排查“这行代码为什么改过”特别好用。Git History以图表形式展示所有提交记录、分支走向还可以对某个文件查看它的历次修改历史。Remote - SSH虽然名字里有 SSH但用途是远程开发。配合 VSCode 插件体系可以远程连接服务器直接在编辑器里改代码。进扩展面板CtrlShiftX搜索名字就能安装不需要额外配置。4.2 语言环境配置C/C、Python 实例热搜词里很多人搜“vscode 配置 c/c 环境”、vscode python 环境配置这里顺便把这两个最常见的配置思路说清。在 VSCode 里配置开发环境核心思路是编辑器负责写代码编译器/解释器负责运行。VSCode 自己不带编译器需要先把工具链装好。Python 环境算是最简单的安装 Python 官方解释器并勾选“Add Python to PATH”。VSCode 安装 Python 扩展微软官方出品。打开任意.py文件VSCode 会自动识别解释器右下角可以切换。直接按CtrlF5或点击运行按钮就能跑脚本。C/C 环境稍麻烦一点Windows 上推荐安装 MinGW-w64把它bin目录添加到系统 PATH 环境变量。VSCode 安装 C/C 扩展。写一个简单程序按下 F5 选择“C (GDB/LLDB)”VSCode 会生成launch.json和tasks.json两个配置文件里面指定了编译命令和调试器。虽然首次配置要花点心思但配完之后体验比很多 IDE 都轻快而且项目的编译调试配置都在仓库里换机器重新构建也快。5. 常见问题与避坑实录5.1 推送被拒、权限报错怎么排查用 git push 推送时遇到权限问题大概率是 SSH 密钥没配对。排查顺序很有讲究先验证密钥是否生效运行ssh -T gitgitee.com如果看到欢迎信息说明 SSH 链路没问题。如果提示权限 denied去 Gitee 设置页检查 SSH 公钥是否粘贴正确尤其注意不要带多余空格或换行。确认本地 Git 身份信息对应的用户名邮箱和 Gitee 账号一致与否不影响 SSH 校验但会影响提交记录的归属最好设置正确。如果用的是 HTTPS 地址推送时提示输入用户名密码却输不对去 Windows 凭据管理器里删掉旧的 Gitee 凭据重新推送时再输入一次就好。还有一个比较高发的情况远程仓库里有文件比如初始化时勾选了 README 或 .gitignore但本地仓库是全新的两者没有共同历史直接推送会报failed to push some refs。解决办法是先把远程内容拉下来合并git pull origin main --allow-unrelated-histories加上--allow-unrelated-histories是允许两条独立历史合并拉下来之后处理好冲突再推送代码才能上去。5.2 冲突处理这块代码怎么同时被改了多人协作时冲突不可避免。场景简单描述你和同事同时修改了同一个文件的同一段代码你先推送成功他再推送时被拒因为有冲突需要解决。处理冲突的操作路径git pull拉取远程代码Git 会标记冲突文件文件里会出现类似下面这样的标记 HEAD 你本地写的内容 远程拉下来的内容 origin/main在 VSCode 里打开冲突文件编辑器会用颜色块区分“当前更改”和“传入的更改”顶部有“接受当前更改”“接受传入更改”“保留双方更改”等按钮手动选择或直接编辑。保存文件后在源代码管理面板里标记为已解决然后照常提交推送。解决冲突的核心原则看清每段代码是干什么的别盲目覆盖。如果不确定找协作的同事沟通一下再合并比事后排查快得多。5.3 误操作补救commit 错了、文件删了怎么办代码托管平台带来的安全感之一就是误操作可以补救。Gitee 的仓库页面可以查看所有提交历史找到某个历史提交后可以一键回滚或者把它重置到某个状态。这个操作要小心如果团队都在用同一个仓库回滚会影响别人操作前最好和团队确认。本地误操作也有补救办法git log --oneline # 查看提交历史 git reset --soft HEAD~1 # 撤销最近一次提交但保留改动 git reset --hard HEAD~1 # 撤销最近一次提交同时丢弃改动 git reflog # 查看所有历史操作包括 reset 之前的记录git reflog是最后的救命稻草。即使误用了--hard只要提交对象还在本地就能找到对应的哈希值回到正确状态。我自己的习惯是重要分支推送前先确认 diff宁可多花一分钟检查也不要推错代码。5.4 批量删库这类高危险操作要谨慎Gitee 上有一个“批量删库”功能管理多个仓库时确实方便但批量操作风险极高。曾经见过有人本想清理废弃仓库不小心把还在正常使用的项目连同所有历史版本一起删掉。几点建议删库前在本地确认这个仓库的代码都有完整备份至少确保最近一次提交已经 clone 到了本地。批量删库列表出来后逐个确认仓库名不要只看缩略信息。Gitee 的仓库删除有二次确认机制输入指定仓库名的操作千万别嫌麻烦这是在给你最后一道保险。我在实际使用中的体会是Gitee 作为国内访问速度极快的代码托管平台在个人备份、项目展示、团队协作这些场景下都非常顺手。但工具始终只是工具真正决定项目质量的是你有没有规范的提交习惯、清晰的仓库结构、合理的分支管理。如果你正处在“写代码只会保存在本地 U 盘”的阶段这篇教程应该能帮你把第一个仓库稳稳当当地推上去。等你养成每次提交都写清楚说明了习惯你会发现代码管理的安全感远比想象中的爽。