最近这几年Git 基本成了程序员的“第二本能”但话说回来天天用 Git 的人里面真正能一口气把项目从本地推到远端仓库、再顺利被同事拉下来的人真没想象中那么多。尤其咱们在国内做开发打交道最多的平台就是 Gitee——托管代码、管理开源项目、部署静态页它一条龙都管。今天这篇就专门聊透一件事怎么把项目干净利落地传到 Gitee 仓库里顺带把创建仓库、选许可证、VS Code 配置、IDEA 拉取、Gitee Pages 这些高频操作一起梳理清楚。这篇文章适合什么人刚学 Git 的新手、从 GitHub 转过来想用 Gitee 的老手、还有那些因为项目里.git文件夹被误删导致无法推送的倒霉蛋都能在里面找到对应的解法。我不会扯太多抽象概念全程都是可以直接照着敲的命令和点按步骤还会把我自己踩过的坑一并写出来。1. 项目上传前的基础认知Git、Gitee 与代码托管1.1 到底什么是 Gitee为什么选它Gitee 是国内主流的 Git 代码托管平台很多团队和个人用它替代 GitHub。原因很朴素——国内服务器访问快不用费劲折腾网络注册门槛低支持手机号直接开账号免费版对私有仓库的开放程度也比 GitHub 大方不少。对大部分开发者来说把项目放到 Gitee 上日常 push、pull、建 Issue、发 Release体验上和 GitHub 几乎没差别。但要注意一个关键区分Gitee 是“代码托管平台”Git 是“版本管理工具”。你本地的 Git 操作不会因为换了平台就改变git add、git commit、git push这套流程全世界一样。区别只在于你 push 的“远端地址”指向哪里——是github.com还是gitee.com。这个概念理顺了后面所有操作都不会蒙。1.2 上传前需要准备哪些环境先把清单列出来避免做到一半发现缺东西一个已经注册并完成实名认证的 Gitee 账号后面用到 Pages 或某些功能时会要求实名。本地装好 Git。Windows 下建议用 Git for Windows安装时一路默认即可macOS 可用 Homebrew 装或者直接xcode-select --install。一个项目文件夹。它可以是代码项目也可以只是文档甚至是一个空文件夹。基本命令行工具Windows 的 CMD/PowerShell 或 macOS 的终端。如果你更习惯图形界面VS Code 和 IDEA 也有完整集成后面会讲到。装完 Git 后建议先确认版本git --version我见过有人折腾半天最后发现是 Git 都没装好终端里敲git直接报“command not found”。所以开始之前这一步务必确认。2. Gitee 仓库创建全流程可见性、许可证和初始化选项2.1 仓库创建步骤拆解登录 Gitee 后在页面右上角点“”号选择“新建仓库”进入创建页面。这一页的选项直接决定你后面 push 的姿势每一个都要看懂再选。仓库名称必须填而且建议用英文小写加连字符比如my-springboot-project。原因有两个第一仓库名会成为访问 URL 的一部分带中文或大写会在复制链接时产生转义问题第二命令行操作用英文名不容易出错。路径默认跟着仓库名走不用改。仓库介绍可填可不填但对开源项目来说建议填一下因为它会显示在仓库首页别人第一眼就能知道你这项目是干嘛的。点击“创建”之后Gitee 会跳转到仓库首页这时你看到的地址就有两种形态HTTPS 形式https://gitee.com/你的用户名/仓库名.gitSSH 形式gitgitee.com:你的用户名/仓库名.git这两种地址后面会用到。2.2 开源许可证怎么选创建仓库时有一个“选择开源许可证”的下拉框很多人直接跳过我建议别跳。如果你是写开源项目许可证直接决定别人能不能合法使用你的代码如果是内部私有项目选“不使用许可证”就行。常见的几个许可证我按实际使用场景给你拆一下MIT最宽松。别人拿你的代码商用、修改、闭源都行只要保留原版权声明。适合工具类、组件类项目。Apache 2.0同样宽松但多了明确的专利授权条款对企业和涉及专利的代码更友好。GPL-3.0强“传染性”。别人用了你的代码他的项目也必须开源且同样用 GPL。适合你希望代码永远开源的场景。LGPL-3.0主要针对库。允许别人把库用在闭源软件里但改了库本身的代码必须开源。MPL-2.0文件级 copyleft改哪个文件就开源哪个文件比 GPL 温和。一个简单的选择逻辑如果你不知道怎么选默认 MIT 基本不会错如果你在乎代码不能被闭源商用选 GPL-3.0如果你在给公司做事先问法务再说。2.3 仓库配置的四个关键选项创建仓库时还有几个设置项我一个个说“开源”还是“私有”。私有仓库只有你和你邀请的协作者能看到。老实说Gitee 对私有仓库的免费政策相对友好即使免费版也能用。拿不准就先私有以后随时可以改成公开。“初始化仓库”。如果勾选了“使用 Readme 文件初始化”Gitee 会自动生成一个 README.md。这个选项要特别小心如果勾上远端仓库就有了第一次提交和默认分支你要是本地也有了 Git 仓库直接 push 可能会遇到failed to push some refs的错误。后面的排查章节我会专门讲。“选择分支模型”。Gitee 在创建时让你选默认分支名默认是master也可以选main。现在很多新项目喜欢用main但公司老项目用master的很多。这块不用过度纠结记住你 push 时的分支名要和远端一致就行。.gitignore 模板。Gitee 提供了常见语言的忽略文件模板。你可以在创建时选一个比如 Java 项目选 Java 模板Node 项目选 Node 模板。这样本地生成的target/、node_modules/等目录就不会误提交。3. 本地代码上传实操命令行、VS Code 和 IDEA 三个维度3.1 命令行方式最通用也最推荐先把场景分成两种本地项目还没有 Git 仓库 vs 本地项目已经是一个 Git 仓库。先说最常见的本地项目已经存在但还没有用 Git 管理。打开终端进入项目目录cd 你的项目路径 git init这会创建一个.git隐藏文件夹里面记录所有版本信息。可以用ls -a查看确认。然后设置用户信息这是提交记录里显示的作者名git config --global user.name 你的名字 git config --global user.email 你的邮箱接着把项目里的文件加入暂存区git add .git add .会把当前目录下所有非忽略文件加入暂存区。如果你不想全加也可以指定具体文件git add src/main/java/Test.java。然后提交git commit -m first commit这里注意如果 Git 提示“Please tell me who you are”说明没设置 user.name 和 user.email按上面补上就行。接下来把本地仓库和 Gitee 远端关联起来git remote add origin https://gitee.com/你的用户名/仓库名.git建议先用 HTTPS比较省事。SSH 方式需要提前配置密钥后面单独说。然后推送git push -u origin master如果你的默认分支是main就把最后的master换成main。-u的意思是设置上游分支下次直接git push就能推送。如果执行时提示要输入用户名密码输入 Gitee 的账号密码即可。现在 Gitee 支持个人访问令牌Personal Access Token代替密码推荐用令牌后面认证失败部分会细说。3.2 VS Code 中配置 Gitee 并推送代码VS Code 里的 Git 功能默认是打开的前提是系统里装了 Git。打开 VS Code按快捷键Ctrl Shift PmacOS 是Cmd Shift P输入 “Git: Clone”可以先把远端仓库克隆到本地。克隆方式有两种。第一种是从零开始克隆git clone https://gitee.com/你的用户名/仓库名.git第二种是本地已有项目、想把项目整个推送到 Gitee。这种情况不需要克隆直接在 VS Code 里打开项目文件夹然后点击左侧源代码管理图标长得很像分叉的树。如果没有检测到 Git 仓库它会提示初始化仓库点一下“Initialize Repository”等价于执行git init。接着在源代码管理面板里你会看到所有变更文件顶部输入框写提交信息点“提交”按钮。再点右上角的“...”选择“推送”VS Code 会问你远端地址选择“添加远程”把 Gitee 仓库的 HTTPS 地址粘贴进去确认后继续推送。实操中有一个细节VS Code 第一次 push 时可能要求你提供凭据Windows 上会弹出一个 Git Credential Manager 窗口输入 Gitee 账号密码或个人访问令牌即可。如果用的是 HTTPS凭据会被 Windows 凭据管理器记住下次不用再输。我推荐装一个 GitLens 插件它能在编辑器里直接看到每一行代码是谁、什么时候、为什么改的。这个小工具对代码审查和排查问题非常实用而且完全免费。3.3 IDEA 里从 Gitee 拉取和运行项目很多 Java 开发者的日常开发工具是 IntelliJ IDEA从 Gitee 拉取代码的流程和 VS Code 不同单独说。先装插件。IDEA 自带 Git 集成但对 Gitee 支持更好的是官方 Gitee 插件。打开 IDEA 设置Settings选择 Plugins搜索“Gitee”安装 Gitee 插件重启 IDE。有两种方式拉取项目。方式一从 Version Control 拉取。文件File- 新建New- 从版本控制获取Project from Version Control在弹窗里选择 Gitee登录后可以看到你的仓库列表选一个直接克隆。方式二如果是已有项目的二次开发打开 IDEA 后选择“Get from VCS”粘贴仓库地址选择本地目录IDEA 会克隆并自动导入。克隆下来的项目如果是 Maven 项目IDEA 会自动识别pom.xml并下载依赖Gradle 项目则识别build.gradle。需要注意IDEA 里拉项目之前要确认 JDK 和构建工具版本。很多时候不是代码拉不下来而是拉下来跑不起来——JDK 版本对不上、Maven 仓库地址访问不了、Lombok 插件没装这些都是高频踩坑点。遇到“项目 Import 后一堆红叉”不要慌先按顺序检查JDK 版本是否和pom.xml或build.gradle里规定的一致。Maven 本地仓库配置是否正确settings.xml里有没有配国内镜像源。依赖是否下载完成Maven 面板里点一下“Reload All Maven Projects”。3.4 Gitee Pages 静态站点发布Gitee Pages 是把 Gitee 仓库里的静态网页直接部署成可访问网址的功能相当于国内版的 GitHub Pages。适合放个人博客、项目文档站点、纯前端页面。要先明白一点Gitee Pages 只能托管静态文件也就是 HTML、CSS、JavaScript 这类。动态网站比如 Java Spring Boot、Node.js 后端是不能直接跑在 Pages 上的它没有执行代码的环境。所以如果你是想把 Vue 或 React 项目部署上去需要先执行构建命令生成dist目录再把构建产物放到仓库的指定目录。具体操作确认 Gitee 账号已经实名认证没有实名认证无法使用 Pages。在仓库的“服务”菜单下找到“Gitee Pages”。选择部署的分支和目录。默认是master分支的根目录如果你的静态文件在docs/目录就选docs/如果是 Vue 项目可以选dist/。点击“启动”按钮等几秒钟Gitee 会给你一个形如http://你的用户名.gitee.io/仓库名的地址。热搜里有个词叫“gitee pages 没有了吗”这里统一回答一下Gitee Pages 目前还在只是需要实名认证且偶尔会有审核调整。如果你的 Pages 服务无法启动先确认是否实名、是否在维护期以及是不是免费额度用完了。Pages 默认域名不太好看Gitee 支持绑定自定义域名。在 Gitee Pages 设置页里填上你的域名然后在域名服务商那边加一条 CNAME 记录指向你的用户名.gitee.io等解析生效后就可以用自己的域名访问了。4. 常见问题与排查技巧实录4.1 项目里的 .git 文件夹被删了怎么重新绑到 Gitee 已有项目这个问题特别多我也踩过。git init产生的.git文件夹是本地 Git 仓库的灵魂一旦被误删或者被人拷走项目时没带上隐藏文件夹本地项目就和 Gitee 断了联系。最直接的表现是你打开 VS Code源代码管理里看不到任何历史提交git status也提示这不是一个 Git 仓库。解法很简单重新初始化。cd 你的项目路径 git init git add . git commit -m 重新初始化 git remote add origin https://gitee.com/你的用户名/仓库名.git git push -u origin master --force注意最后那个--force它是关键也是危险项。因为 Gitee 上的仓库已经有一份历史提交了而本地是全新初始化的仓库两者历史完全不相关普通git push会被拒绝提示failed to push some refs。用--force强制推送会用本地的历史覆盖远端。如果你是一个人单干仓库里没有别人的改动这么做没问题但如果是团队协作千万先确认没有其他同事推过新代码再考虑用--force。一个更稳妥的替代方案不需要重新初始化直接把旧的.git恢复过来。如果项目被删除时还有一个.git的备份很多人会拖到回收站直接放回去就行。没有备份的话重新初始化加 force push 是唯一出路。4.2 VS Code 拉取 Gitee 项目覆盖本地如何避免丢修改这个问题在热搜里也很常见“vscode拉取gitee项目覆盖本地项目”。很多人操作时太顺手点完 pull 发现本地改的代码全没影了急得一头汗。先说原理。git pull本质上执行的是git fetchgit merge。如果你的本地修改没有提交Git 默认会阻止合并报错“Your local changes to the following files would be overwritten by merge”。这是保护机制不是 Bug。真正危险的是你用git reset --hard origin/master强行使本地和远端一致这时本地未提交的修改会直接消失几乎没有恢复手段。所以正确思路是如果你还没提交但想保留本地修改执行git stash把修改暂存起来然后git pull最后git stash pop恢复。如果你已经提交了直接git pull就行Git 会自动合并。如果有冲突手动解决冲突后git add .再git commit最后git push。如果你确定本地修改不要了先git fetch origin再git reset --hard origin/分支名强制让本地和远端一致。这一步后所有未推送的本地产物都会丢失操作前务必确认。一个日常习惯建议在 VS Code 里做任何拉取操作前先看一眼源代码管理面板有没有未提交的修改如果有要么 commit 要么 stash。这个习惯养成后基本不会出现拉取覆盖本地项目这种事故。4.3 认证失败或推送被拒的原因与处理Gitee 推送时报认证错误是另一个高频问题。常见表现是remote: [31m[session-xxxx] Access denied: authentication failed fatal: Authentication failed for https://gitee.com/xxx/xxx.git原因通常有几个第一密码输错或使用了已过期的密码。Gitee 在某个时间点开始不再允许直接用账号密码推送需要在个人设置里生成“私人令牌”Personal Access Token。操作路径Gitee 首页右上角头像 - 设置 - 安全设置 - 私人令牌 - 生成新令牌。生成时记得选择权限范围比如projects权限用来读写仓库。拿到令牌后推送时用户名填你的 Gitee 账号密码填令牌。第二本地 Git 缓存了旧的凭据。Windows 上可以通过“控制面板 - 凭据管理器 - Windows 凭据”把与gitee.com相关的旧凭据删掉下次推送时重新输入。第三SSH 密钥问题。如果你用的 SSH 地址要先检查本地有没有生成公钥ls ~/.ssh/id_rsa.pub没有的话生成一个ssh-keygen -t rsa -C 你的邮箱然后把id_rsa.pub的内容复制到 Gitee 的“安全设置 - SSH 公钥”里。添加完成后可以验证ssh -T gitgitee.com成功的话会返回欢迎信息。4.4 其他高频坑初始化冲突、大文件限制、分支名不一致再补充几个实战中几乎必遇到的坑。仓库被初始化过导致 push 被拒。如果你创建 Gitee 仓库时勾了“使用 Readme 初始化”而本地又是一个全新的 Git 历史git push -u origin master时大概率会报! [rejected] master - master (fetch first) error: failed to push some refs to https://gitee.com/xxx/xxx.git hint: Updates were rejected because the remote contains work that you do hint: not have locally.两种解法一是先把远端拉下来合并执行git pull origin master --allow-unrelated-histories然后处理冲突再推送二是确定远端 Readme 无所谓直接git push -u origin master --force覆盖。我建议优先用前一种至少不会直接抹掉远端已有内容。分支名不一致。Gitee 默认分支如果是main你本地执行git push -u origin master可能提示远端没有master分支。可以先查一下本地分支名git branch如果是master但远端是main要么在 Gitee 仓库设置里把默认分支改成master要么本地重命名分支git branch -M main git push -u origin maingit branch -M是强制重命名后面跟新名字。大文件推送失败。Gitee 对单个文件大小有上限仓库整体也有容量限制。如果 push 时报remote: error: File xxx is 25.00 MB; this exceeds GitHubs file size limit一类信息说明把大文件直接放进仓库了。解决方案有几种把大文件从 Git 历史中彻底移除可以使用git filter-branch或 BFG Repo-Cleaner。改用 Git LFS 管理大文件。把大文件放到对象存储如阿里云 OSS、腾讯云 COS仓库里只存访问链接。从根上防止这个问题最好在项目根目录创建.gitignore文件将构建产物、日志文件、临时文件全部忽略掉。.gitignore这一个文件能省掉 80% 的 Git 使用问题。写在最后的一点实操心得上面这套流程拆开来看都很简单但真正把项目上传到 Gitee 这件事大多数人卡住的不是单个命令不会敲而是对 Git 的本地仓库、远端仓库、提交历史这几个概念理解不够清楚。我见过太多人问“为什么我明明 push 了Gitee 上却什么都没有”——不奇怪因为你 push 之前没有 commit本地 Git 仓库里压根没有“记录”可以被推送。Git 的流程永远是add把改动加入暂存commit把暂存内容变成一次提交记录push把提交记录推送到远端。三步缺一不可。关于 Gitee 和 GitHub 的选择我个人的建议是国内项目、团队协作、想部署 Pages 的优先 Gitee自己的开源项目想面向全球开发者GitHub 依然是主流。两个平台的 Git 操作完全相通学会了其中一套另一套只是换了个地址而已。平时练手的话我强烈建议多用命令行少依赖图形界面的按钮——命令行能让你看到每一步的真实输出排查错误时信息完整得多。如果这篇的内容对你有用照着操作一遍把第一个项目推到 Gitee 上你会发现整个过程撑死也就五分钟。第一次做完后面再传新项目就是纯肌肉记忆了。