我经常在后台收到类似的问题：“怎么把文件传到 Gitee 仓库啊？”“Git 命令到底要敲哪几个？”说实话，这一行问的人特别多，因为网上教程要么太老，要么绕来绕去一堆术语，好不容易跟着走一遍，还经常在远程地址、分支名、密钥配置这些环节卡住。今天这篇我就想用最短的路径讲清楚：在 Gitee 上传文件到仓库，到底有哪几条路可以走，哪条适合什么样的人，以及我实测下来最容易踩的坑在哪里。
这篇内容覆盖了你可能需要用到的全部入口：先在网页上把仓库建对，再用网页直传、Git 命令行、VSCode/PyCharm/IDEA 集成上传三种方式来传文件。如果你是完全零基础，从第 1 章顺着读；如果你已经在用 Git 但老是出差错，可以直接跳到第 5 章排查报错。仓库地址、分支冲突、密钥失效、大文件限制这些常见问题，我全部放在后面单独讲。
1. 先把仓库建好：这一步选错，后面全得重来
很多人上来就想传文件，结果连仓库都还没建。更常见的情况是仓库建得很快，但初始化选项乱勾一气，等传文件的时候才发现 README 冲突、许可证不对、仓库类型选错，又得删了重建。我建议你先花两分钟把仓库设置看明白，这比后面绕弯路省事得多。
1.1 建私有库还是公开库？先想清楚再点
登录 Gitee 之后，右上角“+”号点开，选择“新建仓库”。这里最关键的一个选项是“是否开源”。如果你选“公开”，那你的代码对所有访客可见，别人能克隆、能下载；如果你选“私有”，只有你自己和被你添加为成员的人能访问。
我的建议是：个人学习笔记、练手项目、还没写完的东西，一律先建私有仓库。原因很简单，公开仓库一旦被别人 fork 或者 clone，你再修改历史记录就很麻烦；私有仓库以后随时可以切公开，但公开仓库不能直接切私有（Gitee 限制公开仓库必须保留一定时间才能转私有），所以一开始保守一点没坏处。如果是公司项目或者你明确要做开源，那再选公开。
仓库名称这块，建议用英文小写加短横线，比如springboot-blog。Gitee 会自动生成一个“路径”，这个路径其实就是你仓库访问 URL 的一部分，后面基于 HTTP 克隆地址的时候会用上，一般让 Gitee 自动填就行。不要用中文命名仓库，后面命令行操作时复制地址容易出现编码问题。
1.2 初始化选项到底该不该勾
新建仓库页面下面有几个初始化选项，很多人一知半解就直接全勾了，这其实埋了不少坑。
- 初始化仓库：如果勾选，Gitee 会帮你生成一个空仓库结构（只有 README 说明文件）。如果你走命令行 push 的路线，我建议不要勾，保留一个完全空的仓库，这样
git push的时候不会出现远程仓库有文件而本地没有的冲突问题。但如果你的目标就是网页端直传文件，那就勾上，方便有个 README 先写着。 - README 文件：很多新人以为 README 是“必选”，其实不是。README 就是仓库首页显示的项目说明文档。如果你准备用命令行传一个现成的项目，就不要勾，否则首次 push 大概率会遇到
failed to push some refs的错误，原因就是远程仓库的 README 和本地仓库没有任何共同历史。 - 选择 .gitignore 模板：这个是告诉 Git 哪些文件不要跟踪，比如 Java 项目的
target目录、Python 的__pycache__、Node 的node_modules。如果你对 Git 还不熟，先选了语言模板没问题，但不选也完全不影响传文件。我见过很多人选错模板，导致本地项目中该提交的文件被忽略了，传上去之后发现少一堆东西，排查半天才发现是 .gitignore 的锅。建议初期先用无，等哪天发现某些该提交的文件老是不出现，再回头加模板。 - 开源许可证：如果你想长期开放源码给社区用，选一个开源许可证，Gitee 里常用的有 MIT、Apache 2.0、GPL 3.0。三种的区别简单说就是：MIT 最宽松，别人拿了你的代码可以闭源商用，只要保留版权声明；Apache 2.0 类似 MIT，但额外包含专利授权条款；GPL 3.0 是“传染性”协议，别人基于你的代码开发的软件也必须开源。个人玩票的话选 MIT 就够，公司内部代码或者不想别人商用就选 GPL，搞不清楚的话就先用 MIT，后面在仓库设置里还能改。
仓库创建成功后，你会进到一个空页面。这个页面右上角有几个按钮：克隆/下载、上传文件、新建文件。接下来的内容，就围绕这几个按钮展开。
2. 网页端直接拖拽上传：零基础到上手最快的路径
如果你是第一次使用 Gitee，又不想在电脑上装任何额外软件，网页端上传文件是你成本最低的路径。这个方案的优点是所见即所得，缺点是只适合传文件、不适合做日常的代码版本管理。换句话说，传一次两次可以，真做项目还得靠 Git。
2.1 单文件上传和批量拖拽
进入仓库页面之后，点“上传文件”，你会跳到一个上传界面。这里有两种方式：
- 点页面中间的空白区域，从文件管理器里选择文件；
- 直接把文件从本地文件夹拖拽到网页的虚线框里。
实测下来，拖拽上传的效率最高，一次可以拖多个文件进去。界面会显示每个文件的上传状态，等文件都出现在列表里之后，你需要在最下方填一条“提交信息”（Commit Message）。这个提交信息一定要写清楚这次传的是什么，比如“添加项目初始代码”“修复登录页样式”，不要用默认的“Update”三个字母。提交信息写得明白，以后你自己回看提交历史时才知道每次改动是什么。
填完提交信息，点“提交”按钮，页面会自动跳回仓库首页，你在仓库里就能看到刚传上去的文件了。
这里有个关键限制需要提前说清楚：Gitee 网页端对单个文件的体积有上限，超过这个大小网页会报错。我自己的实测经验是，普通代码文件、图片、PDF 都没问题，但如果你要传视频或者超大的压缩包，就老老实实等下一章用 Git 命令行，或者用 Gitee 的 LFS 大文件存储功能。
2.2 在网页上直接新建文件和编辑
除了上传，网页端还支持直接新建文件。比如你要给项目补一个使用说明，最快的方式不是到本地写完了再传，而是直接在仓库里点“新建文件”，输入文件名README.md，然后在编辑框里写内容。Markdown 语法在网页上有实时预览，可以边写边看排版效果，写完点“提交”，这个文件就直接进仓库了。
这个功能也适合修改已有文件。点进某个文件之后，右上角有一个铅笔图标，点一下就能进入编辑模式。改完之后填一条提交信息提交，Gitee 会自动生成一个提交记录。你点文件上方的“历史”标签，能看到这个文件每一次的修改记录，旁边还会显示是谁改的、改了什么内容，这个功能对于多人协作非常有用。
不过要提醒一点：网页端编辑文件只适合改单个文件的场景。如果你要改几十个文件，或者在本地已经改完了一个完整项目想整个传上去，还是老老实实进入下一章的命令行流程。很多人一开始用网页端随手传，项目大了之后网页根本管不过来，最后还是要切回 Git。所以我的建议是，网页端适合浏览、改说明文档、传一两个零散文件；正式的代码项目，从一开始就要走 Git 流程。
3. Git 命令行上传：这才是真正“学会”的标志
先说结论：如果你要在 Gitee 上认真做项目管理，命令行是绕不过去的一关。理由很简单——命令行能做的事情，覆盖了日常开发中 90% 以上的场景：批量上传、版本回退、分支管理、查看每次改动的具体内容。网页端做得再好，也只是帮你临时处理点轻微工作。
3.1 环境准备与基础配置
命令行上传前需要先装 Git。Windows 用户去 Git 官网下载安装包，安装时一路默认选项即可。macOS 用户如果没有安装，执行brew install git就能装好。装完验证一下版本：
git --version能输出版本号就说明 Git 装好了。然后做两个最基础的全局配置，一个是你的用户名，一个是邮箱。这两项会写进你每次提交的记录里，让其他人知道这次提交是谁做的：
git config --global user.name "你的名字" git config --global user.email "你注册Gitee用的邮箱"名字可以用拼音或英文，但邮箱建议和 Gitee 注册邮箱保持一致，这样 Gitee 才能把你的提交记录正确关联到账号上。很多人跳过这步，提交记录里显示的是乱码或未关联用户，看历史记录时会一头雾水。
3.2 SSH 密钥配置：为什么推荐走 SSH 而不是 HTTPS
克隆仓库或关联远程仓库时，你会用到两种地址：HTTPS 地址和 SSH 地址。界面上的“克隆/下载”按钮会同时给出这两个地址。HTTPS 地址每次推送代码可能都需要输入用户名密码（Gitee 要求使用账号密码或私人令牌，密码验证经常被一些二次验证策略拦下来）；而 SSH 方式配好密钥之后，以后推送拉取都免密，用起来最舒服。
配置 SSH 密钥的完整流程是这样的：
ssh-keygen -t rsa -b 4096 -C "你注册Gitee用的邮箱"执行后它会问你把密钥保存在哪里、要不要设置口令，直接回车用默认路径就行。生成完毕后，找到公钥文件并查看内容，macOS 或 Linux 执行cat ~/.ssh/id_rsa.pub，Windows 用 PowerShell 执行type C:\Users\你的用户名\.ssh\id_rsa.pub：
cat ~/.ssh/id_rsa.pub以ssh-rsa开头的那一串就是公钥，复制它。然后登录 Gitee，点头像 → 设置 → SSH 公钥 → 添加公钥，把它粘贴进去，标题随便填一个你认得出来的名字，比如 “我的电脑”。
配置完成后测试一下连通性：
ssh -T git@gitee.com首次连接会提示是否确认主机指纹，输入 yes 回车。如果看到 “Hi xxx! You've successfully authenticated, but GITEE.COM does not provide shell access.” 这种提示，就说明密钥生效了。
SSH 和 HTTPS 的取舍，我一般这样建议：个人电脑、固定使用环境，用 SSH 一劳永逸；临时电脑、公共机器，用 HTTPS 克隆一次性的项目更方便。两种方式在 Gitee 上都支持，你可以同时配置，没有冲突。
3.3 完整的上传流程：本地项目推到远程仓库
假设你本地已经有一个写好的项目文件夹，叫my-blog，里面的代码文件零零散散。现在要把它完整传到 Gitee 上的仓库里，完整的操作序列是这样的：
cd my-blog git init git add . git commit -m "初始化项目代码" git remote add origin git@gitee.com:你的用户名/my-blog.git git push -u origin master我拆开解释每一步在做什么：
git init在当前目录初始化一个 Git 仓库，.git目录会被创建，里面记录项目所有的版本历史和配置。git add .把当前目录下所有文件加入暂存区。注意那个点是当前目录的意思，不是打错了。如果你只想提交某个文件，就写git add 文件名。git commit -m "初始化项目代码"把暂存区的内容正式提交到本地版本库，-m后面跟的就是这次提交的说明信息。git remote add origin 仓库地址把远程仓库地址绑定到本地的origin这个名字上。origin是 Git 默认的远程仓库别名，如果你绑定错了地址，可以用git remote set-url origin 新地址来改。git push -u origin master把本地master分支推送到远程仓库。-u的意思是记住关联关系，以后直接敲git push就能推送，不需要再敲一遍远程仓库名和分支名。
如果你在第 1 步创建仓库时勾选了初始化仓库，本地又已经有了历史，那么 push 大概率会报failed to push some refs。因为远程仓库里已经有 README 文件，而本地仓库和远程仓库历史完全没有交集，Git 出于安全考虑会拒绝推送。解决办法是把远程仓库的改动合并到本地：
git pull origin master --allow-unrelated-histories这条命令的意思是：允许两个没有关联历史记录的仓库进行合并，把远程的 README 拉下来和本地代码合并。合并完可能会有冲突，需要手动处理，然后再次 commit 后再 push。如果你不想处理这个麻烦，最省事的做法就是从头建一个完全空的仓库，不要勾选任何初始化选项，直接走我的命令序列。
4. IDE 集成上传：VSCode、PyCharm、IDEA 三种实测对比
命令行虽说是通用方案，但大部分人日常写代码都在 IDE 里完成，能直接在编辑器里完成提交推送，确实会顺滑不少。我实际用过 VSCode、PyCharm、IDEA 三种常见工具连接 Gitee，操作路径有些差别，但背后用的都是同一套 Git 逻辑：把改动加入暂存、提交、推送。
4.1 VSCode：自带 Git 面板就够用
VSCode 是很多人写前端和轻量脚本的首选，它的 Git 集成是内置的。打开项目文件夹后，左侧边栏有一个“源代码管理”图标（一个像分叉的图形），点开就能看到当前所有改动过的文件。
在文件列表里，文件名的状态缩写有讲究：M表示 modified（已修改）、U表示 untracked（新增但未跟踪）、A表示 added（已加入暂存区）。你点了每个文件右边的“+”号，这个文件就会被放到暂存区；都准备完毕后，在上方输入框填写提交信息，点“提交”按钮，提交就完成了。接着点“同步更改”或“推送”按钮，代码就推到远程了。
首次推送前，VSCode 会要求你关联远程仓库。你可以在命令面板（Ctrl+Shift+P）输入Git: Add Remote，填写远程仓库名字（默认用origin）和仓库地址，地址就是你从 Gitee 仓库页复制的 SSH 或 HTTPS 地址。之后再推送就不需要重新设置了。
如果你需要更丰富的 Git 能力展示，可以安装 GitLens 插件，它能直观看到每行代码是谁写的、什么时候改的、对应的提交信息是什么。不过就日常上传代码这个需求，内置功能完全够用，不需要额外装插件。
4.2 PyCharm：菜单项更多但逻辑一致
PyCharm 里同样内置了 Git 集成。如果你新建的是空项目，第一次使用 Git 需要先执行 VCS → Enable Version Control Integration（启用版本控制集成），选择 Git，点 OK。这时项目右上角或者底部状态栏会出现 Git 相关工具。
修改完代码后，项目文件会显示为红色或蓝色，红色表示新增未跟踪，蓝色表示已修改。依次操作：
- 右键项目文件夹 → Git → Add，把文件加入暂存区（文件变绿色）；
- 右键项目 → Git → Commit Directory，在弹窗里填提交信息，点 Commit；
- 还没配远程仓库的，先 VCS → Git → Remotes，添加 Gitee 仓库地址；
- 最后 VCS → Git → Push，推送代码。
PyCharm 里有一个很容易被忽略的好用功能：Commit 弹窗的下方会显示代码检查结果，比如未使用的导入、语法警告等。提交前扫描一遍，能帮你在代码进仓库前把明显的低级问题过滤掉，这个习惯建议趁早养成。
另外 PyCharm 顶部菜单里有一个“Update Project”（更新项目），对应的是git pull操作。如果你和别人协作同一个仓库，推送前先 Update 一下，能减少很多冲突。
4.3 IDEA：和 PyCharm 同源，但提交前一定要看右侧面板
IDEA（IntelliJ IDEA）和 PyCharm 同属 JetBrains 家族，Gitee 集成逻辑和 PyCharm 几乎一样。很多人用 IDEA 做 Java 后端开发，提交代码时最容易忽略一件事：IDEA 右侧有一个 Commit 工具窗口，它不会自动帮你勾选所有文件，而是会列出所有变更，默认勾选的是你这次想提交的文件。新手以为自己点了“提交全部”，结果只是把部分文件提交上去了，推送到 Gitee 后发现代码不完整。
所以用 IDEA 提交前，务必点开右侧的 Commit 面板，依次检查三个地方：
- 这次变更的文件列表是否完整；
- 下方有没有未解决的冲突提示（IDEA 会显示红色警告条并禁止提交冲突文件）；
- 提交信息是否写清楚。
提交完成后点 Ctrl+Shift+K（Push 快捷键），下方会弹出推送窗口，显示目标仓库和分支。如果远程分支还没建立，IDEA 会提示你创建。确认无误后点 Push，代码就上去了。IDEA 对 Gitee 的支持是通过内置插件完成的，你首次推送填远程地址时，如果提示找不到 Gitee，需要在 Settings → Plugins 里搜索安装 Gitee 插件。
5. 传不上去的常见原因：五类报错逐个排查
最后这部分，就是我实际带新人时碰到的最高频问题了。命令敲了、按钮点了，但文件死活传不上去，报错信息五花八门。我挑五类最常见的，逐个拆解。
5.1 fatal: remote origin already exists
这个报错出现在你执行git remote add origin 地址的时候，意思是当前目录已经绑定过一个远程仓库地址了。你可以用下面命令查看当前绑定的是哪个地址：
git remote -v如果发现地址不对，直接重置：
git remote set-url origin 正确的地址如果确定这个目录不需要原有远程关联，也可以删除后重新添加：
git remote remove origin git remote add origin 地址这种情况经常发生在你从一个旧项目复制目录后重用了.git配置，解决思路就是先核实当前目录的远程仓库到底指向哪，而不是一上来就删。
5.2 Permission denied (publickey)
这个报错说明 SSH 密钥没有通过验证。原因通常有三种：密钥没有添加到 Gitee；你复制公钥时少复制了几个字符；或者你使用的是 HTTPS 地址，但本机没配全局用户名密码。
排查路径是：
ssh -T git@gitee.com这个命令会明确告诉你是认证成功还是失败。如果失败，回到第 3.2 节重新生成密钥并添加公钥，然后重启终端再试。有一点值得多说：很多人生成密钥时ssh-keygen命令后面不带-C参数，导致公钥文件末尾没有注释，这本身不影响使用，但如果你在网络上复制的公钥带了换行、前后空格，就会认证失败。所以复制公钥时一定要完整复制，不要手打，不要用微信传输文件导致格式改变。
5.3 fatal: refusing to merge unrelated histories
这个报错我前面提过，出现在本地仓库和远程仓库没有共同历史时。常见场景就是你本地已经有了项目，远程仓库也初始化过 README，两端各有一部分对方没有的提交记录。
解决办法就是用--allow-unrelated-histories参数强制拉取合并：
git pull origin master --allow-unrelated-histories合并时 Git 会用冲突标记把矛盾点标出来。如果你发现合并后文件乱了，还可以备份目前的改动后执行git reset --hard回到合并前状态，重新选择一条更顺的路径：清空远程仓库，或者把远程仓库删掉重建一个完全空的。对我个人来说，如果远程仓库只有孤零零一个 README，我通常会删掉远程仓库重建一个空的，然后用git push -u origin master一次性推上去，干净利落，不用处理任何冲突。反正 Gitee 的仓库删起来很方便，重建也不费事。
5.4 RPC failed; curl 28 OpenSSL SSL_read: Connection was reset
5.4 大文件导致 “RPC failed; curl 28 ... Connection was reset”
这个报错通常意味着推送的数据量太大，连接被中断。常见原因就是仓库里混入了体积很大的二进制文件，比如压缩包、安装包、视频素材。Gitee 仓库虽然没有把每个文件的大小卡得很死，但大文件推送极其容易触发网络超时。你本地看仓库不觉得大，但因为二进制文件没法增量压缩，每次提交都会把完整内容传到服务器，日积月累仓库体积会失控。
解决办法分两步：
- 第一步，把这个大文件从 Git 跟踪中移除，如果它刚被你误提交，可以重置提交；如果已经提交多次，用
git filter-branch或者 BFG 工具清理历史记录。对新手来说，最简单的方案是把仓库全部内容拷到一个新文件夹，删除旧的.git目录，重新执行git init和一次干净的提交，这样能彻底甩掉历史包袱。 - 第二步，以后超大文件走 LFS（Git Large File Storage，大文件存储）。Gitee 支持 LFS，安装后配置一下跟踪规则，例如
git lfs track "*.psd"，大文件就能以独立方式存储和传输，普通代码推送完全不受影响。
5.5 推送被拒：分支落后于远程分支
当你和别人协作用同一个仓库，或者你自己在网页端改过文件后，本地推送就会提示“更新被拒绝，因为远程分支包含本地没有的提交”。解决办法是先拉取远程改动再推送：
git pull origin master git push origin master如果你本地文件有未提交的改动，git pull可能会提示覆盖冲突，这时候要先把本地改动提交或暂存，再执行 pull。用git stash暂存改动是个好办法，执行后本地改动会被临时保存，pull 完成后用git stash pop恢复。
分支落后这个坑，本质上是本地和远程的“信息不同步”，所以最有效的根治方案是在 IDE 里每次开始写代码前先更新，再动手改文件。我见过太多人一天写下来的代码，推送时发现和同事的几处改动撞在一起，最后花半小时手工解决冲突，这种时间消耗完全可以通过习惯来规避。
收尾前再分享两个我在实际使用中的体会
第一个体会是，命令行的git status是你最好的朋友。传不上去的报错五花八门，但其实任何时候你觉得迷糊了，敲一下git status，Git 都会明确告诉你当前在哪个分支、哪些文件被修改、哪些文件还没提交。这个命令不会改任何东西，随便敲，尽情的敲。
第二个体会是，提交信息真的好好写。我接手过几个个人项目，历史记录清一色都是“Update”“更新”，出了 bug 想定位是哪个版本引入的，根本无从下手。从第一次提交开始养成分步提交的习惯——比如“实现登录接口”“修复注册页表单校验”——以后自己排查问题时能省出大量时间。别嫌麻烦，这比什么高级技巧都实用。
这篇内容到这里就讲完了。核心就一句话：网页端拖拽适合传单个文件，命令行是掌握 Git 的必经之路，IDE 集成则能帮你把提交推送融入日常开发流。照着第 3 章的命令流程走一遍，配置好 SSH 密钥，以后你的代码就能随时同步到 Gitee 仓库，再也不用担心代码丢失了。
