从本地到Gitee：Git推送、仓库创建与高频问题全解-开发者社区

最近这几年，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 仓库创建步骤拆解

仓库名称必须填，而且建议用英文小写加连字符，比如my-springboot-project。原因有两个：第一，仓库名会成为访问 URL 的一部分，带中文或大写会在复制链接时产生转义问题；第二，命令行操作用英文名不容易出错。路径默认跟着仓库名走，不用改。

仓库介绍可填可不填，但对开源项目来说建议填一下，因为它会显示在仓库首页，别人第一眼就能知道你这项目是干嘛的。点击“创建”之后，Gitee 会跳转到仓库首页，这时你看到的地址就有两种形态：

HTTPS 形式：https://gitee.com/你的用户名/仓库名.git
SSH 形式：git@gitee.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 + P（macOS 是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 fetch+git 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 git@gitee.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 main

git branch -M是强制重命名，后面跟新名字。

大文件推送失败。Gitee 对单个文件大小有上限，仓库整体也有容量限制。如果 push 时报remote: error: File xxx is 25.00 MB; this exceeds GitHub's 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 上，你会发现整个过程撑死也就五分钟。第一次做完，后面再传新项目就是纯肌肉记忆了。