说到往Gitee仓库上传文件我接触到的很多新同事第一反应都是“不就是一个git push吗”结果真上手的时候卡在密钥配半天、创建仓库时不知道选不选初始化、本地仓库和远程仓库对不上报错……这些细节踩一轮下来半小时就没了。这篇文章就是把“上传文件到Gitee仓库”这件事完完整整过一遍从建仓库、配SSH密钥到命令行推送再到IDE可视化提交最后把高频报错整理成速查表不管是刚入门的新手还是偶尔要用一下Git的老同事都能直接照着做。1. 准备工作账号、Git环境与SSH密钥配置1.1 注册账号和安装GitGitee是国内用得比较多的代码托管平台上传文件的第一步是有一个账号。注册很简单去gitee.com点击注册手机号和邮箱都能注册个人开发者选个人账号就行。注册完顺手把头像和个人主页补一下后面给仓库加协作者或者被别人看到主页时会显得专业不少。Git客户端的安装就看你是什么系统。Windows用户直接去Git官网下载安装包一路Next默认选项装完就行装完在开始菜单里能看到Git Bash。macOS用户如果有Homebrew一条brew install git搞定没有的话去官网下pkg包。Linux用户更简单apt install git或者yum install git看发行版。装完打开终端跑一下git --version能输出版本号就说明环境没问题。这里要强调一下Windows用户安装Git时建议把默认的“Git Bash”终端用起来不要在CMD里敲Git命令。Git Bash在Windows下对路径处理和命令补全的体验好很多尤其是后面要操作SSH密钥的时候处理起来顺手得多。1.2 SSH密钥配置为什么推荐怎么配置Gitee支持HTTPS和SSH两种方式上传文件。HTTPS方式的地址形如https://gitee.com/用户名/仓库名.gitSSH方式的地址形如gitgitee.com:用户名/仓库名.git。两种方式都能用但我的建议是直接用SSH花三分钟配置一次后面一劳永逸。原因有两个。第一HTTPS方式每次push时都要输入Gitee的用户名和密码如果开启了登录验证还要填验证码频繁操作非常烦人SSH方式配置好密钥后推送代码全程免密。第二在实际体验中SSH方式的连接稳定性比HTTPS好一些不太容易出现推送中途断开的情况。配置SSH密钥的步骤如下# 1. 打开终端Windows用Git Bash生成密钥 ssh-keygen -t rsa -b 4096 -C 你的Gitee注册邮箱 # 2. 一路回车默认路径即可如果要设置密码短语也可以输入 # 3. 查看公钥内容 cat ~/.ssh/id_rsa.pub把cat输出的内容完整复制然后登录Gitee网页端右上角头像 → 设置 → 安全设置 → SSH公钥粘贴到“公钥”输入框里标题随便填一个方便识别的名称比如“我的电脑”提交保存。验证是否配置成功运行ssh -T gitgitee.com如果返回Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.就说明公钥生效了。这一步做完后面所有和Gitee仓库的交互都不需要再输密码。注意~/.ssh/id_rsa是私钥千万不要泄露出去。换电脑或者重装系统后只需要把私钥文件拷贝到新机器的~/.ssh目录下或者重新生成一遍密钥再添加公钥就能继续免密访问。2. 创建仓库与仓库初始化设置2.1 网页端创建仓库开源许可证怎么选登录Gitee后页面右侧有个“新建仓库”的绿色按钮点进去就是仓库创建页面。这里有几个字段要解释清楚。仓库名称是必填的这个名称会显示在仓库地址的路径中建议用小写字母、数字和中划线组合比如SpringCloudDemo这种驼峰命名虽然好看但在URL里访问时经常要区分大小写不如spring-cloud-demo这种全小写加中划线的风格省心。“路径”字段通常和仓库名称联动生成后可以手动修改。如果仓库名称是中文或者包含特殊字符路径就非常重要了因为访问仓库的URL实际使用的是路径而不是名称。“开源许可证”这个选项我发现很多人每次创建仓库都会纠结。提供一个简单的判断标准仓库完全私有不打算给别人看选“无许可证”就行仓库公开但允许别人随便用只要保留你的版权声明选MIT仓库公开且在意专利保护选Apache 2.0仓库公开且希望后期代码使用者也必须开源即GPL协议选GPL 3.0如果拿不准我的习惯是个人项目的默认选择是MIT因为限制最少朋友拷贝去玩也不会有什么心理负担。如果项目是公司或者团队内部用的直接不勾选许可证保持私有。下面还有三个勾选项初始化仓库、选择.gitignore模板、选择开源许可证模板。我的建议是全部不勾选创建空白仓库。这个建议后面会解释原因。2.2 仓库概览页的主要信息创建完成后会自动跳到仓库首页页面上能看到几个关键信息仓库地址。页面顶部会展示HTTPS和SSH两种克隆地址记住SSH地址长什么样后面命令行推送会用到。仓库分支名。Gitee新建的仓库默认分支是master还是main取决于你创建时的选项和Gitee当前默认设置。这个信息在上传时要注意因为如果本地分支名和远程分支名不一致push时需要显式指定。创建完空白仓库后页面上通常会有一段提示文字列出在你本机要执行的Git命令。如果项目在本地已经存在照着这段提示操作就行。但如果本地项目完全还没纳入Git管理就往下看第三节的完整步骤。3. 命令行上传文件HTTPS方式与SSH方式实测3.1 场景化方案选择先克隆还是先init命令行上传文件有两种场景我简单说一下怎么选。场景一本地还没有任何代码文件夹是空的或者只是零零散散几个文件。这种场景最简单把远程仓库克隆下来再把文件放进去提交推送。场景二本地已经有一个完整的项目目录里面已经通过git init初始化过或者已经提交了多次历史。这种场景要做的是先初始化Git再关联远程仓库最后推送。很多新手容易搞混这两种场景把场景二的问题拿到场景一去操作结果各种报错。下面我把两种场景的具体做法都写清楚。3.2 实操步骤从零把一个本地文件夹推到Gitee假设我现在有一个本地文件夹叫my-project里面是我写好的项目代码这个文件夹此前没有做过任何Git操作。我的操作流程是# 1. 进入项目目录 cd my-project # 2. 初始化Git仓库 git init # 3. 配置用户信息如果之前没配置过全局信息 git config --global user.name 你的昵称 git config --global user.email 你的注册邮箱 # 4. 把所有文件加入暂存区 git add . # 5. 提交到本地仓库 git commit -m first commit # 6. 关联远程仓库用前面复制的SSH地址 git remote add origin gitgitee.com:你的用户名/my-project.git # 7. 推送本地分支到远程 git push -u origin master如果一切顺利这条命令执行完终端会打印一系列更新提示然后网页端刷新一下文件就出现了。这里有一个非常关键的细节也是我反复提醒周围同事的点第7步之前如果远程仓库不是空的也就是创建仓库时勾选了初始化README或添加了.gitignorepush会报错错误信息通常是! [rejected] master - master (fetch first)或者failed to push some refs。这是本地仓库和远程仓库的历史记录不一致导致的。解决办法有两个。一个是在创建仓库时就选“不初始化仓库”保持远程仓库干净后续推送不会有任何历史冲突。另一个是如果远程已经有内容了先拉取合并再推送git pull origin master --allow-unrelated-histories # 拉取合并后如果有冲突先解决没有冲突就继续推送 git push -u origin master对于第一次接触Git的新手我更推荐前一种方式创建空白仓库什么都别初始化本地git init之后直接推送。干净省事不产生意外。3.3 文件很大怎么办Gitee单文件限制与LFS策略Gitee对单文件大小有100MB的上限仓库整体的体积建议控制在合理范围内。我见过有人直接把整个编译产物目录推到仓库几百MB甚至上GB这种操作不仅容易触发限制还会让clone仓库变得非常慢体验极差。如果确实需要存储大文件我的建议是这样做第一用.gitignore把不需要入库的目录排除掉。比如Java项目里的target目录、Node项目的node_modules目录、Python项目里的__pycache__这些都是在本地构建时自动生成的不应该进仓库。创建仓库时Gitee提供了.gitignore模板如果当时没有勾选也可以在本地手动创建.gitignore文件。第二大文件用Git LFS管理。Gitee支持LFS功能操作方法是# 安装LFS插件 git lfs install # 指定大文件后缀比如所有zip文件 git lfs track *.zip # 确认生成新的.gitattributes文件并提交 git add .gitattributes git commit -m add lfs track rules之后这些被LFS追踪的文件会以一个指针的形式存在Git仓库里真正的内容存储在Gitee的LFS存储空间里clone和推送的速度会快很多。对于用Gitee托管包含模型、压缩包、二进制文件的场景这个功能很有用。4. 用IDE提交代码到GiteeIDEA、VSCode、PyCharm实操4.1 IDEA提交代码到Gitee如果日常开发主要用IntelliJ IDEA我强烈建议不要只在命令行里操作把Git集成直接用在IDE里效率会高很多。IDEA自带Git支持也提供了Gitee官方插件装好之后整个提交流程都在图形界面里完成。IDEA里关联Gitee仓库有两种方式。一种是打开IDEA后从「Get from VCS」进入粘贴仓库地址直接克隆另一种是本地项目已打开在顶部菜单「Git」→「Git Bash」或「终端」里先添加远程仓库地址然后从界面上拉取。推荐流程是这样的先克隆仓库IDEA会直接识别出这是Git仓库右下角弹出一个分支信息。在项目里修改文件后文件会变成绿色新增、蓝色修改、或者红色未跟踪这都是Git颜色标识不用死记看多了自然反应得过来。提交的快捷键是CtrlK会弹出Commit窗口左边勾选需要提交的文件下面填写提交信息点Commit。推送用CtrlShiftK点Push就能推到远程仓库了。如果远程仓库有更新推送前先在菜单栏点一下「Git」→「Pull」拉取最新代码避免提交冲突。有几点体验上的小建议提交信息不要写“test”或者“更新”这种没意义的内容。按照“做了什么为什么做”的结构写比如“fix: 修复登录接口空指针导致白屏”。后期翻历史记录时你会感谢自己当时没有偷懒。IDEA底部有一个“Git”窗口可以查看每次提交的改动内容和代码作者。团队协作时善用这个窗口比在网页端看历史方便很多。如果提交的反了比如提交到本地但发现内容有问题还没推送直接在Git窗口右键这次提交选择“Undo Commit”可以撤销提交改动内容不会丢。4.2 VSCode和PyCharm的操作要点VSCode操作Git同样方便。打开项目后左侧边栏的源代码管理图标一个圆形分叉的图标就是Git面板。初始化仓库后所有未跟踪的文件会列在这里输入提交信息点击“提交”然后点击“同步更改”就会推送。VSCode里如果传代码到Gitee我习惯先配置好远端仓库再推送。在命令面板CtrlShiftP里输入Git: Add Remote输入远程仓库地址添加完成后在源代码管理面板点击三个点的菜单选择“推送”。同样的如果远程有更新先“拉取”再“推送”。PyCharm和IDEA都是JetBrains家的兄弟产品界面高度相似操作方式基本一致。顶部菜单「Git」栏里Commit和Push的功能和IDEA一模一样快捷键也一样CtrlK提交CtrlShiftK推送。如果你之前用过IDEA换到PyCharm完全不需要重新学习。我对IDE上传文件的建议是能图形化操作就不要用纯命令行尤其在多人协作、需要查看文件差异和解决冲突的场景下IDE的图形化对比工具比命令行高效太多了。但命令行能力也不能丢服务器上的项目没有IDE只能用命令行而且出了问题排查时命令行给出的报错信息往往比IDE的弹窗提示更明确。5. 进阶操作批量删库、静态托管与常见问题排查5.1 Gitee的批量删除仓库与仓库管理仓库越建越多总有些废弃的Demo项目想清理。Gitee支持批量管理仓库。在Gitee个人主页 → 仓库标签页或者右上角头像 →「我的仓库」里可以看到自己所有的仓库列表在列表上方有“批量管理”的入口勾选多个仓库后可以统一操作删除。这里要重点提醒删除仓库是不可逆操作。仓库被删除后里面所有分支、提交记录、Issue、Pull Request统统消失Gitee不会保留回收站功能。动手之前一定确认好这个仓库是不是真的不要了最好的做法是先克隆一份到本地再把远程仓库删掉。本地留着完整的Git历史以后后悔了还能重新推上去。单个仓库的删除入口在仓库页面「管理」→「设置」→「删除仓库」操作时需要输入仓库名称才能确认这是Gitee设计的防误删机制。我看到一些团队会定期清理过期仓库把不再维护的项目归档或删除这套操作流程搞清楚很有用。另外顺带提一个很实用的仓库管理小技巧Gitee支持仓库的“转移”可以把仓库转移到一个组织或另一个账号名下。交接项目时不需要重新上传文件再删旧仓库直接在管理页面操作转移即可历史记录完美保留。5.2 Gitee Pages静态托管Gitee还提供了Gitee Pages服务相当于一个静态网站托管功能。把项目里的静态文件HTML、CSS、JS推到仓库里然后在仓库「服务」→「Gitee Pages」里启动部署就能得到一个在线访问的网址。这个功能非常适合作项目文档、个人技术博客或者给前端项目做演示页。部署前需要先在Gitee完成实名认证认证通过后在Pages页面里选择要部署的分支和目录点击启动就行。更新内容时推完代码再点击更新网站内容就会同步变化。我个人的用法是把一些工具的在线说明文档放在Gitee Pages上方便团队成员随时访问不用每次发文件、传压缩包。相比自建服务器省去了买服务器和维护环境的成本静态站点加载速度也很快。部署一次之后我只需要记往仓库修改文件、提交推送然后点一次“更新”整个过程两分钟。5.3 高频报错问题排查速查手册把这些年用Gitee上传文件遇到的高频问题整理成一张速查表建议收藏出错的场景报错信息特征原因与解决办法添加远程地址时重复remote origin already exists已经添加过远程仓库了。先执行git remote remove origin再重新git remote addpush时被拒绝failed to push some refs远程仓库有本地没有的提交先git pull origin 分支名再推送如果创建仓库时初始化过READMEpull时需要--allow-unrelated-historiespush时报403remote: Forbidden或Permission denied (publickey)公钥没配对。重新执行ssh -T gitgitee.com验证确认公钥已添加到Gitee账号下找不到分支src refspec master does not match any本地还没有任何提交先git commit之后再push推送的文件太大this exceeds GitHubs file size limit of 100 MBGitee版本提示类似单文件超过100MB改用Git LFS管理大文件或考虑把大文件放对象存储克隆时连接超时Failed to connect to gitee.com port 443检查本机网络环境换一个网络重试企业内网经常有代理限制确认代理设置是否正确提交到错误的分支推送后网页端发现分支不对用git branch -m 旧分支名 新分支名重命名分支然后git push -u origin 新分支名重新推送再删除远程旧分支还有两个特别容易踩的坑想单独说。第一个是换行符问题。Windows下Git会把文件里的CRLF转换成LF在pull时又变回CRLF导致Git提示整个文件都修改了实际上只是换行符变了。解决办法是在项目根目录创建.gitattributes文件写入* textauto或者执行git config --global core.autocrlf true让Git自动处理换行符避免诡异的全量diff。第二个是master和main的分支名混淆。新版Git初始化仓库时默认分支可能是master但Gitee新建仓库的默认分支可能是main。本地和远程分支名不一致推送时就需要显式指定比如git push -u origin master:main把本地的master推到远程的main分支。养成习惯推送前先git branch看看当前所在分支。最后分享一个我自己的操作习惯我个人的习惯是这样的日常改动比较频繁的公共仓库用IDEA图形界面提交需要精细控制提交粒度、或者要写多行提交信息的时候用命令行而服务器的代码同步和一次性文件上传基本只用命令行方式。两种方式没有谁更好看场景选择效率最高的那个就行。还有一个我踩过好多次坑总结出来的点无论是网页端还是命令行创建仓库时尽量保持仓库“空白初始化”任何README、.gitignore、许可证都后面按需添加。一个空仓库就是一张白纸后面往里面推代码的路径最简单也不会遇到合并历史冲突那一堆破事。仓库的维护讲究一个“用得越久越干净”一开始就选对了方式后面所有的操作都会顺很多。如果你之前总是在网页端手动上传单文件我建议这次就试一下命令行推送配好SSH密钥后体验完全不同。第一次完整走一遍“创建仓库 → 本地commit → push”的流程你就能理解为什么程序员都离不开Git了。