空白白白白Gitee文件上传这个需求，比想象中普遍。我见过刚学编程的同学把整个项目文件夹拖进网页，结果卡在半路；也见过工作几年的同事push代码被拒绝，一脸茫然地来问“为什么我传不上去”。其实Gitee文件上传本质上就是两条路：一条是网页端直接拖拽上传，适合临时文件、文档、小体积压缩包；另一条是Git命令行推送，适合真正的代码项目、需要版本管理的内容。这篇就把两条路都走一遍，把每一步的原理、命令、报错点讲清楚，适合第一次把本地代码放到远程仓库的初学者，也适合遇到上传失败想定位问题的老手。
1. 内容整体设计与思路拆解
1.1 三条上传路线的优缺点对比
Gitee文件上传可以走的路不止一条。网页端上传是最直观的：登录Gitee后进入仓库页面，点“上传文件”，选择文件、填提交说明、点提交，三步完事。它的优点是操作门槛极低，不需要安装任何工具，浏览器打开就能用；缺点是文件数量多时效率很低，目录结构支持也很有限，而且每次上传都要手动填一次提交说明，无法把本地整个项目文件夹一步到位传上去。所以网页端适合临时补个文件、更新个文档，不适合做正经项目的初始提交。
Git命令行推送是另一条路。在本地进入项目目录，输入git add、git commit、git push，文件就送进远端仓库。它最大的优势是完整保留了文件的版本历史，支持整个目录树批量上传，后续修改只需要几条命令就能增量同步，不需要重新传一遍全部文件。缺点就是需要把基础的Git命令记熟练，对没有接触过命令行的人来说有一定学习成本。
还有一条折中路：桌面客户端或者IDE插件。这些工具有图形界面，又能调用完整的Git功能，看起来是两全其美。但我的实际体验是，图形工具虽然上手容易，出问题的时候也变得更难排查，因为工具把很多细节隐藏了，报错信息也经常二次包装。我的建议很直接：如果只是传一个Excel表格给朋友，那网页端就够；如果你面对的是一个正经项目，老老实实用好命令行。Gitee文件上传的核心其实是Git操作，网页端只是Git之上的一个便利入口。你把命令行这条链路跑通了，反过来再看任何图形客户端，一眼就能明白它在帮你干什么；只依赖图形界面的话，遇到问题会很被动。
1.2 为什么推荐命令行方式
很多新手看到Git命令就头疼，实际上光讨论“上传文件”这个场景，常用的命令五六条就够。我经常拿寄快递来打比方：git init是找一个空箱子，git add是把文件装进箱子，git commit是封箱并把运单号写清楚，git push是把箱子交给快递员送到远端仓库。这条链路一旦走顺，你会发现它比网页端拖拽“省事”得多。因为本地项目更新之后，几条命令就把新增和修改同步过去了，不用重新上传整个文件夹，也不用在网页里一路点鼠标。
命令行方式还有一个网页端给不了的核心价值：可回溯。网页端虽然也有提交记录，但当你需要回滚到几天前的版本、对比某个文件到底改了什么、把代码切到某个分支做独立测试时，只有Git仓库能提供这些能力。这不是某个平台特有的功能，而是Git自身的设计带来的。所以本篇的实操部分会以命令行方式为主线，网页端作为辅助，方向上是围绕“把文件从本地送到Gitee远端仓库”这个核心来展开的。
1.3 从使用场景看影响范围
Gitee文件上传会影响到的人群可以粗略分成三类。第一类是想把Gitee当网盘用的人，传课件、传资料、传压缩包，他们最需要的是网页端操作说明和文件大小限制的知识。第二类是个人开发者，把自己的学习代码、练手项目、博客源码放到仓库里，需要的是一整套完整的Git推送流程，以及免密认证的配置方式。第三类是团队协作成员，除了基本上传，还要解决分支推送、冲突合并、权限控制这些进阶问题。
这篇内容主要覆盖第一类和第二类，第三类也会在常见问题里挑几个典型场景重点讲。因为不管你是哪一种角色，最终动作都绕不开“把本地文件送到远程仓库”这件事，区别只是后续维护的复杂度不同。这也是我为什么把标题定为“Gitee文件上传教程”而不是“Git入门教程”，因为整个内容的落点就是“上传”这个动作，只是顺手把这个动作背后的原理讲明白了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心细节解析与实操要点
2.1 新建仓库时就要想清楚的事
在Gitee网站首页点击“新建仓库”，会碰到几个选项，很多人都是随便填一下就开始传文件，结果后面处处别扭。先说仓库名称，取名不要带空格，建议用小写字母、数字、中划线组合，比如my-blog、note-book。仓库名会成为远程地址的一部分，后期虽然能改，但牵涉到已克隆仓库的地址、文档链接里的URL，能不改尽量不改。
初始化选项这里要注意。“初始化自述文件”建议勾上，这样仓库里会自带一个README.md，仓库页面不会空空白白，克隆下来也有一个落脚点。如果你忘了勾也没关系，后续可以在网页端新建文件补上。“添加.gitignore模板”这一项，建议按项目类型选，比如Java、Python、Node.js都有现成模板。选模板的目的是把编译产物、依赖目录、IDE配置这类不该进仓库的文件自动挡在外面，防止上传了一堆无意义的垃圾文件。
开源许可证的问题，个人练手可以暂时不选；如果这个仓库打算公开展示，选一个合适的许可证对使用者和你自己都更负责。大概想好这几个选项，仓库的基础结构就稳了，后面上传文件时能少很多体力活。
2.2 文件上传的限制与规范
网页端虽然方便，平台对文件大小和仓库容量是有约束的。以我的实际使用经验看，网页端上传更适合几十MB以内的文档、压缩包、配置文件，体积再大就很容易失败或者速度奇慢。命令行推送对普通文本文件基本没什么压力，但如果你需要存几百MB的视频、数据集或者安装包，就要提前研究大文件存储方案，Gitee平台上一般需要用LFS才能持续管理这类大文件。
我的建议是：仓库里尽量放源码、文档、配置文件这些文本类内容，真正的构建产物、数据库备份、视频素材放到仓库之外的其他存储里。这样对仓库容量、克隆速度、版本记录都比较友好。否则每次克隆仓库都要下载一堆大文件，团队协作时大家的体验都会很痛苦。
文件名规范也值得提前统一。仓库里不要出现“新建文档(1).txt”这种随手命名的文件。空格、中文虽然能传，但在命令行操作时容易遇到转义问题，URL里也会有编码问题。最省心的做法是统一用小写英文字母、数字、下划线和中划线，路径层级也不要太深。太深的目录在网页端操作起来很繁琐，在命令行里要敲一长串路径，怎么看都不划算。
2.3 Git三区模型：add、commit、push到底在干嘛
聊完了约束，来看上传动作背后最重要的那套逻辑。Git把文件状态分成工作区、暂存区、本地仓库和远程仓库四个部分。工作区就是你磁盘上看到的文件夹，文件有没有改、改成什么样都体现在这里。暂存区是一个中间地带，git add把文件放进暂存区，相当于告诉Git“这些文件我打算记录”。git commit则把暂存区的内容固化成当地仓库里的一个历史节点，相当于拍了一张快照。git push把本地仓库的历史快照同步到远程仓库，远程仓库收到的就是你最后要的东西。
很多人上传失败，根源就是把这几个步骤混成一步。以为执行了push就能把所有文件都送上去，忽略了add和commit。网页端看起来简单，是因为它把add和commit在一张表单里替你做了，文件名、提交说明填完，点击提交就是“add+commit+push”三合一。命令行里你没办法跳过这些步骤，这是好事，因为每一步都明确，出现问题时你至少能判断是哪一环出了问题。比如提示“nothing to commit”，说明你根本没把文件加入暂存区；提示“push rejected”，说明远端仓库有不属于你的提交。知道问题出在哪个环节，排查起来才有的放矢。
3. 实操过程与核心环节实现
3.1 网页端上传：适合临时文件
先走一条最快的路，网页端上传。登录Gitee，进入仓库首页，找到“文件”面板，点击“上传文件”按钮。这里支持单选、多选文件，也支持直接把本地文件拖进虚线框区域。选中文件后，下方会让你填写一条提交说明，比如“上传教学文档”，填完后点击“提交”，文件就进入仓库了。
如果你需要上传整个目录，网页端目前不能直接拖一个文件夹进来，得手动在网页里一级一级建目录，再把文件分别传进对应目录。文件数量少还能接受，文件多了效率就直线下降。所以网页端更适合什么场景呢？适合你本地没有装Git环境、只有几个文件、临时补个资料的情况。比如某个项目缺了一份设计稿，你顺手把PDF拖进仓库，几分钟搞定。
但这里有个隐患：如果本地项目已经用Git管理，而你在网页上直接改了文件或者传了新文件，下次在本地commit并push时，就极大概率出现推送冲突。所以我的建议是，凡是正经项目仓库，尽量少用网页端改动文件；非改不可的话，也要在本地先git pull同步后再提交。网页端的定位是应急入口，不是日常工作流。
3.2 命令行推送：完整步骤与参数说明
这一节是整个教程的重头戏。假设你的本地有一个文件夹叫my-project，里面有代码和文档，现在要传到Gitee新建的同名仓库里。下面是完整流程。
第一步，安装Git环境。Windows去官网下载安装包，一路下一步即可；macOS可以用Homebrew执行brew install git；Linux发行版各自用系统包管理器安装。装完后打开终端，Windows用户建议打开Git Bash，确认版本：
code复制git --version
能看到类似git version 2.x.x的输出，说明环境OK。
第二步，进入项目目录：
code复制cd my-project
第三步，初始化Git仓库。这一步会在当前目录生成一个隐藏的.git文件夹，用来存放版本信息：
code复制git init
第四步，把文件加入暂存区。先用git add .把当前目录下所有文件都加进去，这个点号代表当前目录：
code复制git add .
如果你的目录里有被.gitignore规则忽略的文件，它们不会进入暂存区，这是符合预期的。想只添加某些文件，也可以指定文件名：
code复制git add README.md
第五步，提交一个本地版本：
code复制git commit -m "first commit"
提交说明建议写清楚这次提交的目的，不要用“update”这种敷衍的内容，一条好的提交信息在半年后会帮你快速回忆当时做了什么。
第六步，关联远程仓库。回到Gitee仓库页面，复制远程地址。这里有两种格式可以选择，HTTPS地址形如：
code复制https://gitee.com/用户名/仓库名.git
SSH地址形如：
code复制git@gitee.com:用户名/仓库名.git
第一次接触建议先复制HTTPS地址，把它关联到本地：
code复制git remote add origin https://gitee.com/用户名/仓库名.git
origin是远程仓库的默认别名，可以理解成给这个远程地址起了一个名字。
第七步，推送到远程：
code复制git push -u origin master
-u参数的作用是，在第一次推送时把本地的master分支和远端master分支关联起来，后续这个仓库再执行git push时就可以直接推送，不用每次写完整参数。
关于分支名，这里有个容易卡住新人的细节。老版本Git初始化仓库默认分支名是master，较新的版本可能默认是main，Gitee新建仓库时也会让你设置默认分支名，常见的是master或main，具体看你创建仓库时的选择。如果本地分支名和远端分支名不一致，push时会报错或者推不上。解决方法有两个，一是直接指定推送关系，把本地master推到远端main：
code复制git push -u origin master:main
二是把本地分支改名：
code复制git branch -m master main
然后再正常push。具体用哪种看你的习惯，但一定要保证本地和远程的分支名对齐。
3.3 本地已有项目如何关联新仓库
很多人不是从零开始的，本地项目早就初始化过Git仓库，甚至之前关联过别的平台。这时候直接执行git remote add origin会报错，因为origin这个名字已经存在。正确做法是先看当前远程配置：
code复制git remote -v
如果发现已经有origin，可以直接修改它的地址：
code复制git remote set-url origin https://gitee.com/用户名/仓库名.git
也可以删掉再添加：
code复制git remote remove origin
git remote add origin https://gitee.com/用户名/仓库名.git
接下来还是标准的提交推送流程：
code复制git add .
git commit -m "sync to gitee"
git push -u origin master
这里有一个坑值得单独说：如果本地仓库积累了多轮历史提交，而Gitee远端仓库也不是全新状态（比如初始化时勾选了自述文件），直接push大概率会被拒绝。空仓库一般没问题，有历史就不一样。你需要先合并再推送，或者使用强制推送。强制推送会把远端历史覆盖成本地历史，危险程度不低。我个人的习惯是：如果远端仓库里没有其他人的提交，新仓库同步时我会先确认后使用强制推送；团队共享仓库绝对不使用force push，这是底线。
3.4 SSH Key配置，告别每次输密码
HTTPS推送第一次会让你输入Gitee的用户名和密码，之后可能还会反复要求输入。配置SSH Key之后就能免密推送，而且SSH协议在部分场景下连接更稳定。整个配置过程分五步。
第一步，检查本地是否已经存在SSH密钥。在终端执行：
code复制ls ~/.ssh
如果看到id_ed25519和id_ed25519.pub两个文件，说明已有密钥，直接跳到第三步读取公钥。
第二步，如果没有密钥目录，用下面的命令生成，邮箱换成你注册Gitee时用的邮箱：
code复制ssh-keygen -t ed25519 -C "you@example.com"
执行过程中一路回车即可，默认路径就是~/.ssh/id_ed25519。如果系统提示是否覆盖已有文件，说明之前生成过密钥，可以选择覆盖或者换路径存储，根据你的实际情况判断。
第三步，查看公钥内容：
code复制cat ~/.ssh/id_ed25519.pub
复制整段内容，注意是从ssh-ed25519开头一直到结尾的邮箱注释，中间不能漏字符。
第四步，登录Gitee网站，进入个人“安全设置”里的“SSH公钥”页面，把刚才复制的内容粘贴进去，标题随便起一个方便识别的名字，比如“笔记本密钥”。
第五步，测试连接是否配置成功：
code复制ssh -T git@gitee.com
首次连接会提示确认主机指纹，输入yes回车继续。看到类似“认证成功”的返回信息，说明SSH已经打通。
最后把本地仓库的远程地址从HTTPS换成SSH格式：
code复制git remote set-url origin git@gitee.com:用户名/仓库名.git
配置完成后，这个仓库里的push和pull就都不需要再手工输入账号密码了。这个流程我在不同的操作系统上验证过多次，只要公钥粘贴完整、密钥类型一致，基本一次就能通过。
4. 常见问题与排查技巧实录
4.1 认证失败：403、用户名密码错误
push时报403或者认证失败，绝大多数是凭据问题。如果你使用HTTPS地址，Git第一次会要求输入账号密码，但Gitee很多场景不支持直接用登录密码操作，而是需要先到安全设置里生成一个私人令牌，然后在提示输入密码时把令牌粘贴进去作为密码。认证失败的另一种常见场景是，以前成功过，后来修改了密码，本机保存的旧凭据还在缓存里，Git继续使用旧凭据自然被拒。这种情况需要清理操作系统的凭据管理器里的旧记录，再重新执行push，才会弹出新一次的认证输入。
排查这一类问题的顺序我建议是先确认浏览器能不能正常登录Gitee，排除账号本身被锁定或密码异常，再用git remote -v检查远程地址有没有写错，最后考虑换SSH方式。实测下来，配置好SSH Key后，认证类问题基本就根除了，连输密码这一步都省掉，体验比HTTPS舒服得多。
4.2 推送被拒绝：non-fast-forward与冲突
这是新手最常撞到的报错，提示大概是这样的：
code复制 ! [rejected] master -> master (fetch first)
error: failed to push some refs
它的意思是远端仓库有你本地没有的提交，你不能直接覆盖过去。产生原因基本是远端通过网页端改过文件、有其他协作者推了新代码，或者远端仓库初始化时自带了文件而你的本地没有同步这些内容。解决办法是先拉取远端内容合并到本地：
code复制git pull --rebase origin master
--rebase参数会把本地的提交挪到远端最新提交之后，让提交历史保持一条直线，看起来更整洁。拉取过程中如果产生了冲突，Git会明确提示哪些文件冲突。打开这些文件，里面会用<<<<<<<、=======、>>>>>>>标记把两端内容分隔开，你需要手工决定保留哪些内容，删除这些标记后重新add、commit、push。
整个过程第一次接触会觉得繁琐，但经历过一次之后，你就理解冲突的本质了：两个人或者两个位置修改了同一个文件的同一处区域，Git没法自动判断谁对谁错，只好让你来裁决。这是正常的协作环节，不是系统出错。
4.3 误提交大文件与.gitignore失效
传上去的文件体积太大，除了上传慢，还可能让整个仓库的体积膨胀。如果只是执行了git add，还没commit和push，处理起来很简单：
code复制git reset HEAD 文件路径
然后修改.gitignore，把这类文件路径写进去。如果你已经把文件push到了远端，事情就麻烦不少。即使后续你把文件删除再提交，它在Git历史中的记录仍然存在，远端仓库的体积还是很大。想要彻底清理，往往需要修复历史或者重建仓库，成本很高。
这里有一个重要的认知：.gitignore不是万能的。如果某个文件已经被Git跟踪，你再在.gitignore里加入它的规则是不会生效的，因为Git对已经跟踪的文件优先保留跟踪状态。正确的解除跟踪方式是：
code复制git rm --cached 文件路径
执行之后再提交，这个文件才会被Git遗忘，同时本地磁盘上的文件还保留着，不会被误删。这个操作在新手阶段很容易踩坑，我建议在第一次上传整个项目之前，就把.gitignore写好，认真检查是不是把所有依赖目录、编译产物、缓存文件都列进去了。
4.4 网页端与命令行状态不同步
这是一个非常容易踩中的隐性坑。你在网页端上传了一个文件，本地完全没有感知，下一次在本地commit并push时，因为远端领先本地几个提交，推送会被拒绝。这不是Gitee出了bug，而是Git分布式模型的正常表现。网页端是独立于本地仓库之外的另一个节点，任何一边有自己的新提交，另一边都不会自动感知。
应对方式也很简单，上传前先git pull，把远端的变更拉下来再push。如果你经常在多个设备之间切换操作同一个仓库，建议固定一套工作流：无论在哪一端改动，都从git pull开始，再处理本地修改和提交。我自己维护文档类仓库时，因为网页端可以快速编辑，配合本地Git提交，偶尔就会遇到同步问题。后来养成了一个习惯：网页端只做新增文件，不做已有文件的修改，已有文件的修改全部放到本地完成。这样冲突面会大幅缩小，仓库历史看起来也清爽很多。
最后分享一个我自己的习惯：不管在什么平台托管代码，我都会先写好.gitignore，再初始化仓库，这样从一开始就不会让临时文件进入版本管理。每一次提交信息也写得具体一点，比如“修复登录页空指针”而不是“更新”，半年后回看git log一眼就能想起当时的改动意图。Gitee文件上传这条路上能走多顺，关键不在于会背多少条命令，而在于把add、commit、push这条主链路跑熟，同时养成先同步再修改的习惯。把上面这些细节都做到，上传这件事基本不会卡你太久。