这是一个在开发者群体里被问过无数次的问题。只要你在做编程相关的事情迟早会听到“把项目传到 Gitee 上吧”这句话。Gitee 是国内使用非常广泛的代码托管平台操作逻辑和 GitHub 几乎一致但访问速度快、中文界面友好也是很多企业、高校和个人开发者管理代码的第一站。这篇文章我打算从一个实际使用的角度把从零开始把项目上传到 Gitee 的全流程、背后的原理、以及常见的坑一次讲清楚。这篇内容适合什么人看刚接触 Git 的新手、从 GitHub 转到国内平台的老手、用 VS Code 和 IDEA 做开发但还没有规范管理代码的人。覆盖的范围包括前期准备、创建远程仓库、本地项目首次上传、日常提交更新、拉取远端代码、以及一个很常见但容易让人抓狂的场景——本地项目误删了.git文件后如何重新绑定到 Gitee 已有仓库。1. 先说清楚几个关键概念1.1 Gitee 和 Git 到底是什么关系很多新手第一次听到“把项目传到 Gitee”时会以为 Gitee 是一个上传工具。这个理解不太准确。Git 是本地版本管理工具负责记录项目文件的所有变更历史Gitee 是基于 Git 的远程代码托管平台相当于把你的 Git 仓库放到一台服务器上方便备份、协作和分享。打个比方Git 是你电脑上的记账本记录了每一笔改动Gitee 是一个保险柜你把记账本复制一份放进去别人也能通过这个保险柜查看和存取。即使电脑坏了记账本的内容也不会丢。所以“上传项目到 Gitee”这句话的本质是把本地 Git 仓库的提交记录推送到 Gitee 的远程仓库。这也是为什么很多教程里第一步都是“初始化 Git 仓库”而不是“登录 Gitee”。1.2 为什么选择 Gitee 而不是 GitHub这个问题我经常被问。答案是看你自己的实际需求。GitHub 是全球最大的代码托管平台开源资源丰富社区活跃度高。但你在中国大陆访问它速度和稳定性都是硬伤。Gitee 的优势有几个国内访问速度快clone 和 push 大项目时体感差异非常明显。中文操作界面对英文不太熟练的人友好很多。私有仓库免费GitHub 的私有仓库虽然也免费但 Gitee 的免费套餐对个人开发者来说基本够用。支持手机号注册、扫码登录账号体系更符合国内使用习惯。如果你是个人项目、学习笔记、课程设计、小组作业或者公司内部项目不方便放国外平台的Gitee 是更稳妥的选择。如果项目需要全球范围内的开源协作GitHub 的优势更明显。两平台可以同时使用Git 允许你配置多个远程仓库。2. 动手前的准备工作2.1 安装 Git 并完成基础配置Gitee 网页端只是仓库的展示和托管界面真正的上传操作需要用 Git 客户端在本地完成。Git 的安装方式不细说了官网下载对应系统的安装包即可。Windows 用户安装时建议默认选项唯一要注意的是安装过程中选择使用 Git Bash 作为命令行终端非常方便。安装完成后打开终端Windows 下打开 Git BashmacOS 下打开 Terminal先配置用户名和邮箱。git config --global user.name 你的名字 git config --global user.email 你的邮箱这个配置不可跳过。每一次提交都会记录下这两项信息在 Gitee 上会显示为提交人。建议直接填入 Gitee 账号的用户名和绑定邮箱这样提交记录上能和你的账号对应起来。验证配置是否生效git config --global --list2.2 生成 SSH Key 并添加至 Gitee上传项目到 Gitee 有两种常用方式HTTPS 和 SSH。HTTPS 方式每次 push 时都需要输入 Gitee 的用户名和密码或私人令牌麻烦不说还容易因为输入错误导致认证失败。SSH 方式配置一次之后就不用再输入密码密钥对在本地验证身份更方便也更安全。这里我推荐你直接使用 SSH 方式。生成密钥的命令是ssh-keygen -t rsa -b 4096 -C 你的邮箱执行后会提示你选择保存路径直接回车使用默认路径即可。如果之前生成过会询问是否覆盖自己根据情况决定。之后会提示设置 passphrase就是使用密钥时的保护密码可以直接回车不设置。生成完成后查看公钥内容cat ~/.ssh/id_rsa.pub复制输出的全部内容打开 Gitee 网页端登录后点击头像进入设置界面找到“安全设置”里的“SSH 公钥”选项把复制的内容粘贴进去标题可以随便填。这一步完成后在本地终端验证一下是否配置成功ssh -T gitgitee.com第一次验证可能会提示确认主机指纹输入 yes 回车。如果输出类似 “Youve successfully authenticated” 的提示说明 SSH 连接已经畅通。3. 在 Gitee 上创建远程仓库3.1 网页端新建仓库的操作细节登录 Gitee 后点击右上角右上角的加号选择“新建仓库”。这里有几个选项需要认真确认仓库名称必填建议使用英文或拼音组合不要包含中文和空格。比如student-manage-system。仓库名称会出现在访问 URL 中取名时要考虑可读性。路径一般会自动跟着仓库名称走也可以单独设置。这是你仓库访问地址的一部分。开源许可证新手阶段选一个合适的很重要。如果不清楚该选什么可以先不选。后面在仓库设置中还能补充。常见选择有 MIT宽松允许别人任意使用修改你的代码、Apache-2.0宽松但有明确的专利授权条款、GPL使用你的代码的项目也必须开源。个人学习笔记类项目其实可以不填等真的发布开源软件时再决定。仓库类型选“私有”还是“公有”私有仓库只有自己和被你添加的协作者能看到公有仓库是全网可见。如果只是交作业、内部项目选私有。如果希望别人能看到甚至参与选公有。注意Gitee 的免费账户私有仓库是有协作者数量限制的普通个人用足够了。初始化仓库设置建议勾选“初始化仓库”并使用 README 模板创建文件。这一项建议勾选它会在远端生成 README.md 文件和 .gitignore 文件模板对新手来说方便很多。也可以在选择 .gitignore 模板的时候根据你的项目语言类型比如 Java、Python、Node自动生成忽略文件。点击创建后你就有了一个远程仓库。页面上会显示出仓库的 SSH 地址和 HTTPS 地址先复制 SSH 地址备用形如gitgitee.com:用户名/仓库名.git。3.2 远程仓库与本地项目的关系理解远程仓库和本地项目本质上都是 Git 仓库中间通过一个“远程地址”建立联系。在 Git 中远程仓库在本地被命名为一个远程引用默认名字叫origin。这个机制决定了一个本地项目可以同时关联多个远程仓库比如同时推送到 Gitee 和 GitHub。理解这一点很重要。很多初学者会把“项目的代码”和“Git 的仓库”混为一谈。实际上.git目录里存的是版本历史。删除.git目录只是删除了版本历史项目文件本身不受影响。后面会单独讲这个问题。4. 首次把本地项目推送到 Gitee4.1 用 Git Bash 完成第一次推送这是整个流程中最核心的阶段。假设你本地已经有一个项目文件夹里面是写好的代码。进入该文件夹cd /path/to/your/project如果项目还没有初始化过 Git 仓库先执行git init这条命令会在当前目录创建一个.git隐藏目录从此 Git 开始接管这个文件夹的版本。然后可以配置当前仓库的用户名和邮箱如果前面已经在全局配置过这里可以省略。但如果这个项目想用不同的身份提交可以单独设置git config user.name 你的名字 git config user.email 你的邮箱接着把项目文件添加到暂存区git add .这个.表示把当前目录下所有文件都加入暂存区。如果你只想添加特定文件可以写具体文件名比如git add README.md。提交到本地仓库git commit -m first commit提交信息建议写清楚做了什么比如 “初次提交项目代码” 或者 “完成用户登录功能”。这是以后回溯历史的唯一依据写得越清晰越好。关联远程仓库把之前复制的 SSH 地址用上git remote add origin gitgitee.com:用户名/仓库名.git如果提示 remote origin already exists说明之前关联过远程仓库。可以用git remote -v查看当前关联的地址。如果地址不对用git remote set-url origin 新的地址修改。推送本地代码到远程仓库git push -u origin master这里-u参数的作用是设置上游分支相当于告诉 Git本地的 master 分支和远程的 master 分支建立关联。以后只需要git push就能推送不需要再写分支名。如果此时遇到报错提示远程分支名是main而不是master这是 Gitee 默认分支名不同的情况。解决办法有两个一个是本地分支改名后推送git branch -M main git push -u origin main另一种是保持本地 master推送到远端的 master 分支并要求合并。推荐用第一种和远端保持一致更干净。推送成功后刷新 Gitee 页面就能在仓库里看到你的项目文件了。4.2 HTTPS 方式推送会遇到的密码问题如果你的远程地址用的是 HTTPS 格式形如https://gitee.com/用户名/仓库名.git在 push 时输入密码那一环要注意现在 Gitee 要求不是输入登录密码而是输入私人令牌。生成私人令牌的路径是 Gitee 网页端设置 - 安全设置 - 私人令牌生成时勾选需要的权限范围。复制令牌后把它当成密码粘贴到终端里即可。这个设计是为了安全避免你在不信任的环境中使用主账号密码。但也确实让一些新手困惑。如果你希望省事直接用 SSH 方式就好。4.3 使用 VS Code 上传项目VS Code 是目前使用率极高的代码编辑器内置了 Git 图形化功能很多人不喜欢在命令行里操作那用 VS Code 完全可以完成上传。先打开项目文件夹点击左侧源代码管理图标一个带分支的圆圈图标。如果没有显示检查一下项目是否已经git init初始化过。VS Code 会在“源代码管理”面板中显示所有变更文件文件旁边会有字母标识U 表示未跟踪M 表示已修改。在上方输入框里写提交信息点击对勾图标完成提交。如果当前项目还没有本地仓库VS Code 会提示你初始化仓库。完成第一次本地提交后点击终端快捷键Ctrl ~或菜单中“终端”-“新建终端”执行关联远程仓库以及推送的命令和 Git Bash 里一样。之后的操作可视化程度更高了点击“源代码管理”面板右上角的“...”选择“推送”即可将本地提交推送到远程仓库。如果你用的是旧版 VS Code 或者某些远程开发插件干扰推送按钮有时会变灰。点开“...”选择“推送到...”手动选择远程仓库分支即可。4.4 使用 IntelliJ IDEA 上传项目IDEA 系列的集成做得同样出色。打开项目后按快捷键Ctrl Shift AmacOS 是Cmd Shift A输入share project on github是分享到 GitHub 的Gitee 的话需要装 Gitee 插件。不装插件也行直接按照前面命令行方式操作即可设置菜单中开启 Git 支持代码变动再提交。IDEA 中点击右上角的 Git 图标选择“推送”按钮如果本地只建了仓库而没有配置远程地址推送时会让你填写远程 URL输入 Gitee 仓库的 SSH 地址。IDEA 的优势是代码审查体验好。提交前可以在“提交”窗口里用 Diff 视图逐行查看代码改动确认无误后再提交这是一个值得养成的好习惯。别一股脑全选提交提交了不该有的配置文件比如本地的数据库密码是很多人踩过的大坑。5. 日常更新与多日开发流程中的操作5.1 更新本地代码并推送项目不是一次性上传就完事的。后续每天写代码都有新的修改需要重复 添加暂存区、提交、推送 这个循环。git add . git commit -m 完成了某某功能 git push熟悉之后这个流程非常顺手。如果你在上次推送时用了-u关联了上游后续就不需要再指定分支。如果没有使用-u每次推送都需要写git push origin master。两种方式都可以但建议首次推送就养成加-u的习惯。5.2 从 Gitee 拉取项目到本地运行除了上传另一个常见场景是把 Gitee 上的项目下载到本地运行。Gitee 仓库页面上有“克隆/下载”按钮有两种方式直接下载 ZIP 包网页端点击下载压缩包解压后就能看代码。这种方式适合只读代码不需要版本历史的场景。Git 克隆在本地终端执行git clone命令把整个仓库连同意版本历史下载下来。这种方式适合需要继续开发、提交修改的场景。git clone gitgitee.com:用户名/仓库名.git克隆后项目文件夹里自带.git目录本地直接就是一个完整的 Git 仓库你可以在里面继续开发并推送。5.3 拉取 Gitee 项目覆盖本地项目有的情况下你把 Gitee 上的最新代码拉下来后发现本地有一些改动了想用远端代码完全覆盖本地。这个场景在多人协作或换电脑工作时经常出现。警告以下操作会丢弃本地未提交的所有修改操作前请确认本地代码不需要保留。如果还想保留先把本地修改提交到另一个分支或者备份到其他目录。git fetch origin git reset --hard origin/master这两行的含义是先从远程拉取最新状态到本地暂存区然后强制把本地当前分支指针移动到远程分支的最新提交同时工作区文件也覆盖为远程版本。如果项目里有多余的本地文件想一并清理再加上git clean -fd这个命令会删除没有被 Git 跟踪的文件和目录。用完这个命令后整个项目目录就和 Gitee 上的一模一样了。6. 常见问题排查与实操心得6.1 提示 “remote origin already exists”出现这个提示说明当前项目已经关联过远程仓库。查看当前关联的地址git remote -v如果输出的地址不是你想要的修改地址git remote set-url origin 新的仓库地址这条命令只会修改远程关联地址不会影响本地文件和历史放心操作。6.2 push 报错 “failed to push some refs”这个报错通常发生在远程仓库有本地没有的提交。常见场景是你创建远程仓库时勾选了“初始化仓库”生成了 README.md而本地项目没有拉取过这个文件。解决办法有两种。第一种先拉取远程内容合并后再推送。git pull --rebase origin master git push -u origin master--rebase会把你的本地提交重新放到远程最新的提交之后历史看起来更线性。如果你不清楚 rebase 和 merge 的区别直接用git pull origin master也行只是可能多一条合并记录。第二种更简单粗暴如果你确定远程仓库里那些文件比如 README.md没有保留价值可以直接强制推送。但注意强制推送会覆盖远程历史如果远程仓库里有别人的提交绝对不能这么做会把别人的代码冲掉。只有你自己独占的仓库或者你明确要覆盖远程时才使用git push -f origin master6.3 本地项目误删了 .git 目录如何重新关联到 Gitee这是一个非常高频的问题。有人在清理文件时把.git隐藏目录删了或者项目是从网上下载的源码根本没有 .git 目录现在想重新上传到 Gitee而且最好是传到一个已经存在项目的仓库中。先说结论.git目录被删只是版本历史没了项目文件还在。重新关联的步骤和新项目首次上传其实一样第一步确认项目目录下有没有.gitls -a如果确实没有执行git init这一步重新初始化本地仓库。第二步配置远程地址。如果 Gitee 仓库已经存在里面可能已经有一些文件先拉取一次远程内容把远端已有文件和本地合并。git remote add origin gitgitee.com:用户名/仓库名.git git pull origin master --allow-unrelated-histories--allow-unrelated-histories这个参数很关键。因为本地是一个全新的仓库和远程仓库没有共同的历史直接 pull 会报 “refusing to merge unrelated histories”。加上这个参数Git 才会允许把两个不相关的历史合并。如果远端仓库里没有任何文件比如你创建仓库时没有勾选初始化那就更简单了初始化后直接把本地提交推送。第三步正常 add、commit、push。如果远端仓库里已经有文件并且本地项目里也有同名文件合并时可能会产生冲突。这些冲突文件需要手动处理打开冲突文件搜索冲突标记、、根据实际情况保留内容然后重新提交。如果远端文件完全不重要只是想用本地覆盖远端也可以跳过 pull 步骤直接强制推送git push -f origin master这个方法会覆盖 Gitee 上的全部内容使用前确认仓库里没有需要保留的提交。6.4 推送时报 “Permission denied (publickey)”这个报错说明 SSH 认证失败。排查步骤检查本地是否有密钥ls ~/.ssh看看有没有id_rsa和id_rsa.pub。检查公钥是否已经添加到 Gitee登录 Gitee设置 - SSH 公钥确认内容与cat ~/.ssh/id_rsa.pub的输出一致。检查仓库 SSH 地址是否正确git remote -v查看地址确认用户名部分是 Gitee 用户名。有时候会因为复制错误把其他平台的地址贴上来了。6.5 Gitee Pages 还有没有这是很多人会关心的一个点。Gitee Pages 是 Gitee 提供的静态网站托管服务可以把仓库里的静态页面部署为一个可访问的网站。以前个人版也可以用后来因为种种原因个人版的 Gitee Pages 服务调整了。目前的情况是个人用户要使用 Gitee Pages需要先完成实名认证并且在 Gitee 上有一定的活跃度和仓库要求不是所有用户都能一键开启。如果你是为了部署个人官网或项目展示页更推荐直接使用 Vercel、Netlify、Cloudflare Pages 等平台免费且流程顺畅。把代码推送到 Gitee 仓库后再去这些平台关联部署效果更好。6.6 Gitee 上开源许可证怎么选创建公开仓库时开源许可证的选项很容易让人纠结。这里给一个简单建议如果只是分享代码、让别人能看能学选 MIT 最省事约束最少别人拿你的代码做任何事都不用向你支付费用只要保留版权声明。如果你希望任何基于你代码衍生的项目也必须开源选 GPL-3.0。如果你是做一个库/框架希望别人使用你的代码时保留署名同时允许闭源商业使用选 Apache-2.0。学习笔记、作业、配置文件等非正式项目不填许可证也完全可以。有一点需要注意的是一旦选定许可证后续改起来很麻烦因为所有基于你项目的人都会受原许可证条款约束前期认真确认。7. 从 Gitee 下载的项目如何在 IDEA 中运行7.1 使用 Git 克隆后在 IDEA 中打开从 Gitee 上克隆一个项目到本地后直接在 IDEA 中打开文件夹即可。但打开后经常会遇到依赖下载慢、项目跑不起来的问题。这是因为 Gitee 上的项目往往只托管了源代码依赖包需要根据配置文件重新下载。以 Java 的 Maven 项目为例打开项目后 IDEA 会自动识别pom.xml并开始下载依赖。如果网络不好依赖下载时间会非常长甚至卡住。这个时候需要检查 Maven 的镜像配置建议配置国内镜像源例如阿里云镜像或华为云镜像。配置文件在 Maven 安装目录的conf/settings.xml中添加 mirror 到 central。改完后重新加载 Maven 项目即可。7.2 使用 ZIP 方式下载后运行如果只是在 Gitee 上点击“下载 ZIP”得到的项目解压后项目中不带.git目录在 IDEA 中打开也不会有 Git 功能。想把它变成 Git 仓库在 IDEA 终端中执行git init即可。之后按照前面讲的方式关联远程仓库。需要特别提醒的是很多从 Gitee 下载的项目自带.gitignore文件里面列出了不参与版本控制的文件类型。在你新建本地仓库和提交时请保留这个文件不要随意删除否则会把 IDE 配置文件、编译产物等乱七八糟的东西推到远程影响协作和项目体积。7.3 配置全局忽略文件避免提交无用的 IDE 文件这一点虽然和上传本身没有直接关系但极其影响日常体验。如果你经常用 IDEA 或 VS Code 开发项目中不可避免会产生.idea、.vscode、*.iml、*.log、target、node_modules等目录和文件。这些内容不属于源代码每个开发者的环境不同不应该提交到仓库。建议创建全局忽略文件git config --global core.excludesfile ~/.gitignore_global然后在~/.gitignore_global中添加常见的忽略规则.DS_Store .idea/ .vscode/ *.iml target/ node_modules/ dist/ *.log配置后这些文件在所有 Git 仓库中都不会被跟踪避免反复出现的噪音。8. 我的几点实在建议在你决定把自己写过的东西传到 Gitee 之前有几条建议我认为值得认真看一下。不是每个项目都需要同步到远端也不是每次提交都需要把所有文件打个包。一个是别把本地仓库当成网盘用该忽略的依赖目录文件就忽略掉干干净净的仓库在后期维护时有多舒服只有踩过坑的人才知道。另一个是提交信息一定要写清楚几个月后回看提交历史那种每一条都写着 “update” 的历史会让你欲哭无泪。至少格式上做到这次改了什么功能、修了什么 bug、为什么这样改。上面这些大部分的问题都可以归纳为两种情况不理解 Git 的本地与远程关系、操作时没有确认上下文。只要把 Git 的本地仓库、暂存区、分支这些概念弄明白“上传项目到 Gitee”这件事就变成了一道填空题——初始化、关联、提交、推送每一步都有固定的语法和指令多操作两次就形成了肌肉记忆。希望这篇文章能帮你顺利地迈出第一步。如果你在推送的时候碰了什么新的报错回来看看是不是和上面某一条对上了大概率能定位到原因。祝提交顺利。