Git本地仓库上传Gitee完整指南：从初始化到免密推送

1. 先把概念理顺：Git、Gitee和“上传”到底在做什么

先聊个有意思的事。很多新手第一次接触Git，满脑子想的都是“怎么把代码传到网上”，结果一搜教程，全是git init、git add、git commit、git push这一串命令，照着敲完也不知道自己到底干了什么。出错了更懵，报错信息一堆英文，也不知道该查哪个。

我的建议是，动手之前先用三分钟把这条链路搞清楚，后面所有操作都会变得顺理成章。

Git本身是一个版本管理工具，它管的是你本地文件夹里那一堆文件的每一次修改记录。所谓“本地仓库”，就是经过git init初始化之后、被Git纳管的那个文件夹。每次git commit都会往这个本地仓库里存一个快照，相当于给当前的项目状态拍了一张照片，随时能回退。

Gitee则是一个代码托管平台，你可以把它理解成一个远端备份中心。本地仓库是你自己电脑硬盘上的东西，Gitee仓库是服务器上的东西，两者靠git push把本地提交推上去，靠git pull把远端更新拉下来。

所以“本地仓库上传Gitee”这件事，本质上就三步：本地把代码提交成记录，Gitee创建好一个空仓库，再把本地记录推送到远端。

下面我把每一步拆开讲，包括那些教程里很少告诉你、但实操中一定会踩的坑。

2. 环境准备：Git的安装与初始化配置

2.1 各平台安装Git的方式

装Git这件事本身不难，但很多人在装之前会纠结“该下哪个版本”“要不要装Git Bash”。我的建议很直接：

• Windows用户：去Git官网下载安装包，一路默认下一步就行。安装路径建议保持默认的C:\Program Files\Git，不要改到中文路径下，否则后面一些工具可能不认。安装过程中会问调整PATH环境变量，选“Git from the command line and also from 3rd-party software”，这样在CMD和PowerShell里都能直接敲git命令。
• macOS用户：如果装了Homebrew，一条brew install git搞定；没装的话直接官网下载pkg包安装也可以。
• Linux用户：apt install git（Debian/Ubuntu）或者dnf install git（Fedora/CentOS），都行。

装完之后打开终端（Windows下打开Git Bash），敲git --version，能看到版本号就说明装好了。如果提示git : 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称，大概率是环境变量没配好，重新运行安装包，选“修复”或者手动把Git的bin目录加到PATH里。

2.2 提交身份配置：为什么一定要配user.name和user.email

这一步很多人会跳过，结果第一次git commit直接报错，提示Please tell me who you are。

Git每次提交都需要记录“是谁提交的”，这个信息就存在user.name和user.email里。不是注册账号，而是一个身份标识，会写进每一条commit记录里，方便团队协作时知道每行代码是谁改的。

配置命令很简单：

bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

这里有个值得注意的细节：邮箱不一定要用Gitee绑定的邮箱，但强烈建议用同一个。因为Gitee可以通过邮箱把你的提交记录关联到账号上，如果配了不存在的邮箱，提交虽然能成功，但Gitee上不会显示你的头像，也无法计入贡献图。后面推送时如果开了账号实名关联，邮箱不一致还可能触发校验提醒。

另外这个配置分三个层级：--global配置所有仓库通用，--local只对当前仓库生效，还有个--system是整台机器生效。如果你在公司电脑上想用个人身份提交代码，可以在某个仓库目录下单独配--local的配置，优先级高于全局配置。

2.3 换行符和文件权限设置

这一步是很多老手容易忽略、但跨平台协作时非常关键的配置。

Windows和Linux/macOS的换行符不一样，Windows是CRLF，Linux/macOS是LF。如果不管，一个文件在不同系统上切换编辑后，Git会把整行判定为改动，git diff看过去全是红的，非常头疼。

建议Windows用户执行：

bash复制git config --global core.autocrlf true

macOS/Linux用户：

bash复制git config --global core.autocrlf input

意思是：Windows下提交时自动把CRLF转成LF，检出时转回CRLF；macOS/Linux下提交时转成LF，检出时不转。这样能避免“一换行就全文件冲突”的尴尬。

还有一句建议顺手执行：

bash复制git config --global core.quotepath false

这句解决的是文件名显示中文变成\346\265\213...这类八进制转义的问题。配置后，git status里能直接看到中文文件名，不用再对着乱码猜半天。

3. 在Gitee上创建远程仓库

3.1 创建仓库时的关键选项

登录Gitee后，右上角“+”号里选“新建仓库”，会进入仓库信息填写页。这里有几个选项想重点说说：

• 仓库名称：会自动成为仓库URL的一部分，比如仓库名是my-project，那地址就是https://gitee.com/你的用户名/my-project。命名建议用小写字母、数字和中划线，尽量不要用中文和下划线。中文虽然能用，但复制URL时会自动转码，看着非常难受。
• 路径（Path）：老版本叫“路径”，新版本叫“仓库名称”下面的关联字段，用于覆盖URL中的路径。一般保持默认就行，不用动。
• 开源许可证：这块是Gitee上最常见的选择困难症。简单说：
  • 不选（默认）：代码版权归你，别人只能看不能商用。
  • MIT：最宽松，别人随便用，保留版权声明即可。
  • Apache 2.0：也宽松，但多了专利授权和商标保护条款。
  • GPL 3.0：传染性协议，别人用你的代码做衍生品也必须开源。
  • 选了“使用Readme文件初始化这个仓库”之后，Gitee会自动帮你生成一个README.md和许可证文件。

我的建议：个人学习项目直接用MIT就行，不是法律建议，纯粹是“省心、允许别人随便用”的默认选项。如果不想开源，就选“私有”，许可证选项会自动消失。

• 选择分支模型：有些仓库默认分支叫master，有些叫main，Gitee上创建仓库时默认分支可以自己选。我建议创建时统一用main，和GitHub新仓库保持一致，后面团队协作、对接CI/CD工具时不容易出兼容性问题。当然，如果你本地已经习惯master了，教程里很多命令会冲突，下面会专门说怎么处理。

3.2 创建完成后先别急着关页面

仓库创建成功后会跳到空仓库的首页，页面上会给出两种仓库地址：HTTPS地址和SSH地址。

HTTPS格式：https://gitee.com/用户名/仓库名.git
SSH格式：git@gitee.com:用户名/仓库名.git

如果你点“克隆/下载”按钮没看到SSH地址，说明账号还没配置SSH公钥，这个后面会专门讲到。先记住：HTTPS方式第一次推送时需要输用户名密码，SSH方式配好密钥后免密，两者URL协议头不一样，不要搞混。

另外，创建仓库时如果勾选了“初始化仓库”并生成了README，那远端仓库就已经有了一次提交。你本地再推的时候，需要先git pull合并或者用--force强推，否则会报rejected错误。这点后面排查部分会详细说。

4. 本地仓库初始化与第一次推送

4.1 从零开始：git init、git add、git commit

假设你本地有了一个项目文件夹，里面是代码文件，现在想推到Gitee。建议先在文件管理器里进入项目根目录，右键打开Git Bash（Windows）或终端（macOS/Linux）。

第一步，初始化仓库：

bash复制git init

这句执行完，文件夹下会多出一个隐藏的.git目录，这就是本地仓库的核心。里面的东西不要随便删，删了历史记录就全没了。

第二步，把文件加入暂存区：

bash复制git add .

git add .会把当前目录下所有未被忽略的文件加入暂存区。在这之前，强烈建议先创建.gitignore文件，把不需要提交的目录和文件排除掉，比如：

• Java项目里的target/、.idea/、*.iml
• Node项目里的node_modules/
• Python项目里的__pycache__/、.venv/
• IDE的配置文件.vscode/、.settings/

新手最容易犯的错就是把node_modules这种动辄几百MB的依赖目录直接git add .一起提交，后续不管推送还是克隆，体验都极其糟糕。

.gitignore里还可以写通配符，比如*.log忽略所有日志文件，/build忽略根目录下的build文件夹。语法不复杂，可以边用边学。

第三步，提交到本地仓库：

bash复制git commit -m "init commit"

-m后面是提交说明，建议规范一点。一般团队会统一的格式，比如feat: 新增登录功能、fix: 修复xxbug。个人项目至少也要写清楚这次改了什么，不然一个月后回看历史完全不知道当时的意图。

到这里，代码已经安全地躺在本地仓库里了，和Gitee还没有任何关系。接下来才是“上传”的真正动作。

4.2 关联远程仓库：git remote add origin

回到Gitee仓库页面，复制HTTPS地址（注意是.git结尾的完整地址）。

在本地仓库执行：

bash复制git remote add origin https://gitee.com/你的用户名/仓库名.git

这条命令把本地仓库和远程仓库建立关联，origin是远程仓库的别名，这是一个约定俗成的默认名字，后续所有命令里都用origin指代这个远程地址。你可以用git remote -v查看关联情况，会输出fetch和push两个URL，正常说明关联成功。

如果输错了想改，执行：

bash复制git remote set-url origin 新的URL

或者直接删了重新加：

bash复制git remote remove origin

4.3 首次推送：git push -u origin master

关联好远程仓库之后，开始推代码：

bash复制git push -u origin master

这条命令的意思是：把本地master分支推送到远程origin的master分支，-u表示设置上游跟踪关系，之后在这个分支上直接敲git push就能推送，不用再写完整命令。

如果创建Gitee仓库时默认分支选的是main，而本地分支是master，直接用上面的命令大概率会看到一个警告：

text复制Warning: 您正在推送一个非默认分支。

这个不报错，推送其实是成功的。但如果远端已经用main初始化过（比如勾选了自动创建README），状态就变成：

text复制! [rejected]        master -> master (fetch first)
error: failed to push some refs

这种就是因为远端仓库有README，而本地没有拉取到导致的冲突。处理方法有两种：

方法一（推荐）：先拉取合并，再推送

bash复制git pull origin main --allow-unrelated-histories
git push -u origin main

--allow-unrelated-histories是让Git允许两个没有共同提交历史的分支进行合并，加了这句才能正常拉取。

方法二（新手最省事）：删掉远端初始化的内容，强制推送

前提是远端仓库空着没代码，执行：

bash复制git push -u origin master --force

把本地历史强推到远端，覆盖掉远端初始化的提交。

我的建议是：如果远端仓库里只有自动生成的README，直接强推是最省心的；如果远端已经有别人的代码提交了，千万别强推，老老实实pull下来合并。

4.4 分支名不一致：master还是main

刚才的场景是远端用main，本地用master。还有一种情况是：Gitee创建仓库时默认分支选了main，你本地项目初始化后git默认分支是master，推到一半发现推到了master，远端显示的是main，两个分支并列存在，看着非常乱。

这不是错误，但分支不统一会带来很多麻烦。最简单的处理方式是，把本地默认分支改成main：

bash复制git branch -m master main

然后推送到远端：

bash复制git push -u origin main

如果远端已经有一个空的main分支，再执行：

bash复制git push -u origin main --force

把本地main覆盖上去。之后每次操作都用main分支，不再碰master。

有一个全局设置可以避免以后每次新建仓库都要手动改：

bash复制git config --global init.defaultBranch main

配置后，以后git init创建的仓库默认分支就是main，不会再有master和main混用的问题。

5. 免密推送配置：SSH Key还是HTTPS凭据

5.1 两种免密方式的对比

第一次用HTTPS地址推送时，Git会弹出窗口让输入Gitee的用户名和密码，输完这之后推送还是要输，每次推送都输一遍非常折磨人。想要免密，有两条路。

方式一：配置HTTPS凭据存储

bash复制git config --global credential.helper store

执行之后，第一次输入的用户名密码会被明文保存在~/.git-credentials文件里，之后就不用再输入了，但安全性不够高。

更稳妥一点的是用manager（Windows上默认）或者osxkeychain（macOS上），把凭据交给系统凭据管理器保存：

bash复制git config --global credential.helper manager

方式二：配置SSH密钥（推荐）

SSH密钥是一个公钥一个私钥，你生成之后把公钥放到Gitee后台，私有钥匙留在本地，推送时Git会用密钥自动认证，全程不用输密码，安全性也更高。这一步是真正解决“推送免密”的最终方案。

5.2 SSH Key的生成与配置

先生成密钥。打开Git Bash或终端，执行：

bash复制ssh-keygen -t rsa -b 4096 -C "你的Gitee注册邮箱"

这里-t rsa指定算法，-b 4096指定长度，-C后面是备注信息，一般填邮箱方便识别。执行后一路回车，会生成两个文件：默认路径~/.ssh/id_rsa是私钥，~/.ssh/id_rsa.pub是公钥。私钥绝对不能泄露，公钥可以安全地放到服务器上。

查看公钥内容：

bash复制cat ~/.ssh/id_rsa.pub

复制全部内容，然后打开Gitee，进入“设置” -> “安全设置” -> “SSH公钥”，把内容粘贴进去，标题随便填个能认出来的名字，比如“家里的台式机”。

添加完公钥后，测试连接：

bash复制ssh -T git@gitee.com

第一次连接会问Are you sure you want to continue connecting，输入yes回车。如果看到提示Hi 用户名! You've successfully authenticated, but GITEE.COM does not provide shell access.，说明SSH密钥配置成功。

之后把远程仓库地址改成SSH格式：

bash复制git remote set-url origin git@gitee.com:用户名/仓库名.git

再执行git push，从此免密。

5.3 多账号场景：一个电脑上有多个Gitee/GitHub账号

如果你在公司和个人分别有Gitee账号，或者Gitee和GitHub同时使用，默认的id_rsa密钥就不够用了，因为同一个电脑的同一个密钥不可能同时对应两个账号。

解决办法是给不同平台配置不同的密钥文件，并在~/.ssh/config里分配。

比如生成两个密钥：

bash复制ssh-keygen -t rsa -b 4096 -C "company@email.com" -f ~/.ssh/id_rsa_gitee_company
ssh-keygen -t rsa -b 4096 -C "personal@email.com" -f ~/.ssh/id_rsa_gitee_personal

然后在~/.ssh/config文件里写：

text复制Host gitee.com
    HostName gitee.com
    User git
    IdentityFile ~/.ssh/id_rsa_gitee_company

这样git@gitee.com这个地址推送时，会自动走id_rsa_gitee_company这个密钥。GitHub同理，在config里加一段Host github.com映射到另一个密钥。

多账号的坑在于：同一个域名下无法区分账号，所以如果你有两个Gitee账号，本质上只能用一个默认配置，另一个账号的仓库一般改用HTTPS方式加个人访问令牌（Personal Access Token）来推送，两个方式并存不冲突。

5.4 关于Gitee个人访问令牌

有的场景下企业内网或者某些网络环境走SSH端口（默认22）会被限制，导致ssh -T git@gitee.com卡住或者连接超时。这时候可以改用HTTPS加令牌方式。

在Gitee后台“设置” -> “私人令牌”里生成一个新令牌，选择需要的权限范围，推送代码最少勾选projects相关权限。生成后马上复制下来，Git会用HTTPS推送时，用户名填你的Gitee用户名，密码填这串令牌，就能推送了。

注意：令牌只显示一次，关掉页面就再也看不到了，忘了只能重新生成。

6. 常见问题与排查实录

6.1 认证失败类问题

报错1：fatal: Authentication failed for 'https://gitee.com/...'

这个最常见的原因有两种：

第一种是Windows凭据管理器里存了旧密码或错误的用户名密码。到“控制面板” -> “用户账户” -> “凭据管理器”，找到git:https://gitee.com，删掉，重新推送时再输一次。

第二种是账号密码错误，尤其是密码里有特殊字符时，终端输入容易出错。建议先去Gitee网页端确认密码能正确登录，再用带令牌的方式推送。

报错2：Permission denied (publickey)

这个SSH方式推送时的典型报错。可能是公钥没添加，或者本地私钥和公钥不匹配。按顺序排查：

1. cat ~/.ssh/id_rsa.pub 查看本地公钥
2. Gitee后台“SSH公钥”页面确认公钥一致
3. ssh -T git@gitee.com 测试能否连接
4. 如果提示登录失败但公钥没错，检查是不是用了多账号，IdentityFile指向了错误的私钥

我在实际使用中遇到过一种情况：ssh -T测试正常，但git push还是报Permission denied。最后发现是仓库的remote地址写成了https://开头，改成git@gitee.com:开头后一切正常。所以检查完密钥后，务必看一眼git remote -v输出的URL协议头对不对。

6.2 推送被拒绝类问题

报错：! [rejected] main -> main (non-fast-forward)

中文意思是远端有本地没有的提交，直接推送会被拒绝，避免覆盖别人的代码。常见于远端README初始化或者同事已经推了代码。

解法分两种情况：

• 远端是全新仓库且没有其他人代码：直接强推，git push -u origin main --force，简单粗暴。
• 远端有别人的提交或你自己已经拉下来的提交：先git pull origin main，解决冲突后重新推送。冲突解决的方式就是打开冲突文件，保留需要的部分，删掉<<<<<<<、=======、>>>>>>>标记行，然后git add和git commit。

报错：failed to push some refs to 'https://gitee.com/...'

这个是上面情况的汇总，具体原因要看报错上面的详细输出。常见的是远端有提交，或者分支名不一致。按上一节方法处理即可。

6.3 大文件与仓库体积问题

如果你的项目里有明显超过1MB的文件（比如模型文件、素材包、视频），推送到Gitee时会特别慢，甚至失败。Gitee对单文件大小有限制，仓库总体积也有上限，不然仓库会膨胀得无法维护。

这里要区分两种情况：

第一，你还没有提交历史，或者仓库刚起步，想加一个大文件进来。最简单的建议是：确认node_modules、build、dist、target这类生成目录已经被.gitignore排除掉，不要让它们进版本库。真正需要的资源大文件，考虑用Gitee的“附件”功能或者单独的文件存储方式来分发，代码仓库只存代码。

第二，你已经不小心把大文件提交进历史了，想从历史中抹掉。最不容易出错的工具是git filter-repo，执行：

bash复制git filter-repo --path 大文件路径 --invert-paths

然后强推一次。但这个操作会改变所有提交的hash，如果有别人在协作，会让所有人的本地历史失联，务必谨慎。

实操中我的经验是：上传前先看一遍项目体积，挨个确认中大型文件是否有进仓库的必要。排查命令：

bash复制du -sh ./*

然后把它和.gitignore规则结合起来，确保第一次提交之前已经过滤干净。一次搞定，比后面清洗历史省事得多。

6.4 其他高频问题

问题1：git push卡在Writing objects阶段，进度条不动

大概率是网络问题或仓库太大。先看仓库里有没有异常大的文件，如果有就排除；如果仓库不大但不走，可以试试：

bash复制git config --global http.postBuffer 524288000

这个配置把HTTP推送的缓冲区调到500MB，对某些网络环境下推送被中断的情况有效。同时可以考虑切换HTTPS和SSH两种远程地址，看哪种更稳定。

问题2：推送成功但Gitee后台看不到代码

检查是不是推到了别的分支。git push后Gitee上默认显示的是仓库的默认分支，如果你只有git push -u origin master而远端默认分支是main，刚推上去的master分支不会出现在默认视图里。切到“分支”标签页能看到所有分支，或者按前面说的把本地分支重命名统一成main再推。

问题3：Gitee的Pages服务不可用，想用仓库托管网页怎么办

好多教程会把代码推到Gitee后用Pages功能直接生成网站。如果发现后台找不到了，先确认自己的账号是否实名认证，Gitee Pages目前对实名用户开放。如果还是找不到，可以尝试：

• 把网页文件放到仓库的docs目录，用“服务” -> “Gitee Pages”里的“文件夹选择”指向docs
• 或者直接用第三方静态托管，代码仓库只做版本管理，网页静态文件部署到别处

问题4：git pull时报冲突，直接改坏文件

如果不懂代码，最简单的方式是保留远端版本：

bash复制git checkout --theirs 文件名

或者保留本地版本：

bash复制git checkout --ours 文件名

执行完后git add和git commit完成合并。但这种方式只适合确定要保留哪个版本的情况，如果两边的改动都要，必须手动整理文件内容。

7. 日常使用中的几点体会和提醒

写到最后，还是想分享几个实操中比较深的感受。

第一，提交信息写清楚一点，三个月后你会感激自己。 很多新人提交信息就写“update”“修改”，过段时间回看历史完全不知道改了啥。养成习惯用feat:、fix:、docs:、refactor:这种前缀，哪怕个人项目也建议这么做，成本很低，收益很大。

第二，推送前先看一眼git status，确认改动的文件是你预期的。 我用git add .误提交过环境配置、密钥文件、本地缓存，都是血泪教训。一个靠谱的.gitignore能避开90%的坑，剩下10%靠每次提交前检查。

第三，第一次推送不要慌，报错信息才是最好的老师。 Git的报错其实写得很清楚：Authentication failed是密码问题，non-fast-forward是远端有新提交，Permission denied (publickey)是密钥问题。把报错信息复制到搜索引擎或AI工具里，通常很快就能定位问题。怕的是报错不看就直接重试，同一句话重复十遍也不会成功。

第四，如果你的项目是给别人看的，README一定要写。 Gitee仓库首页默认显示README，这个文件决定了别人第一眼看到的是什么。建议至少包含：项目简介、环境要求、运行步骤、目录结构。不用长篇大论，但关键信息一定要有。

第五，日常工作流建议养成“小步提交、频繁推送”的习惯。 每次改动只做一件事，一次提交只改相关文件。万一哪里改出问题，回退范围小，排查也容易。不要等到做了三天大改动再一次性提交，到时候你自己都分不清哪段代码和哪个功能对应。

这套“本地Git仓库上传Gitee”的操作，本质上就是一个流程：本地提交、远端创建、关联推送、免密配置。把每一步的原理和常见报错都吃透，后续不管换GitHub、GitLab还是公司内部代码平台，操作逻辑都是相通的，只是把远端地址换掉而已。