把本地项目的文件传到 GitHub 或 Gitee 的远程仓库里这件事看起来简单实际操作时却卡住过很多人。我刚接触 Git 的那会儿也天真地以为在网页上拖拽上传就完事结果项目文件一多、改动一频繁网页上传完全失控。后来老老实实把 Git 本地推送这套流程跑通了才觉得这是每个开发者都应该掌握的基本功。这篇文章专门讲怎么用 Git 把本地文件上传到 GitHub 或 Gitee从最开始的安装配置到第一次推送成功再到日常更新和报错排查一步一步写清楚。适合刚接触版本控制的新手也适合给临时需要把项目挂到远程仓库的人做个速查。1. 上传前先想清楚Git 到底在解决什么问题1.1 本地仓库和远程仓库的关系Git 是当前最主流的分布式版本控制工具而 GitHub 和 Gitee 都是基于 Git 的代码托管平台。两者的关系可以简单理解成本地仓库是你自己的项目档案室远程仓库是放档案的公共展示柜。你在本地做的每一次修改都不会立即出现在远程仓库里需要先确认改动、生成提交记录再显式地推送上去。这个“显式推送”的设计一开始让人很不习惯但它是版本控制的核心价值所在。因为每次推送之前你都有机会检查自己改了什么而不是让所有临时修改一股脑出现在公共仓库里。网页拖拽上传的问题就在于没有中间检查步骤也几乎没有版本历史哪次改了什么全靠人工记简直是自找麻烦。1.2 为什么推荐用 SSH 连接远程仓库连接 GitHub 或 Gitee 有两种常见方式HTTPS 和 SSH。SSH 连接的核心是用密钥对代替账密反复输入本地生成一对公钥和私钥私钥留在自己机器上公钥填到平台的 SSH 配置里。推送代码时平台通过公钥判断有没有权限。用 HTTPS 也不是不行但每次推送往往都要验证身份有时候还要折腾个人访问令牌体验比较割裂。SSH 配好之后日常操作基本上是无感的推拉代码都畅通。所以我下面的步骤都以 SSH 作为默认方案如果你想改用 HTTPS只需要把仓库地址换成 HTTPS 形式其余流程一样。2. 上传前的准备装好 Git配好身份生成密钥2.1 安装 Git不同系统的偷懒办法Windows 上最省事的做法是去 Git 官网下载安装包一路下一步装完。安装完之后开始菜单里会出现 Git Bash这就是一个类似 Linux 终端的命令行环境后续命令都推荐在这里执行因为路径处理和命令风格都更贴近实际开发环境。macOS 用户可以直接用 Homebrew 安装一条命令就能搞定brew install gitLinux 用户根据系统发行版选择包管理器就好以 Debian/Ubuntu 为例sudo apt update sudo apt install git -y装完先确认一下版本至于版本形态能用就行不需要追求最新git --version提示Windows 安装时如果遇到要选择“默认编辑器”“PATH 环境”的选项保持默认即可不用过度纠结。2.2 给 Git 设置一个身份签名Git 的每一次提交都会记录作者信息也就是 user.name 和 user.email。这两个配置直接影响远程仓库中提交记录的展示效果建议第一次使用就配好git config --global user.name 你的名字 git config --global user.email 你的邮箱加上--global表示这台机器上的所有 Git 仓库默认使用同一身份。如果你的公司和个人项目想分开身份可以进入某个项目目录后不加--global单独配置比如git config user.name 项目专用名字 git config user.email 项目专用邮箱很多新手漏了这一步提交代码后发现远程仓库显示“无名之辈”或者提交信息里的邮箱不对看着非常难受。所以开局就把身份信息钉死后面会省掉一堆麻烦。2.3 生成 SSH 密钥并添加到 GitHub 或 Gitee生成密钥的命令如下建议用 ed25519 算法比传统的 RSA 更短更安全ssh-keygen -t ed25519 -C 你的邮箱命令执行后会问保存路径和口令直接一路回车就能生成在~/.ssh/id_ed25519和~/.ssh/id_ed25519.pub两个文件里。.pub后缀的是公钥可以随便给别人看不带后缀的那个私钥要当作密码一样保护绝对不能泄露。查看公钥内容cat ~/.ssh/id_ed25519.pub把输出的整串内容复制下来登录 GitHub 后进入 Settings找到 SSH and GPG keys点 New SSH key把内容粘贴进去保存。Gitee 也是类似路径在设置里的安全设置里找到 SSH 公钥粘贴保存。验证一下是否配置成功ssh -T gitgithub.com ssh -T gitgitee.com成功的话会返回类似“身份已验证”的提示。我第一次配的时候在这里卡了很久后来发现是放公钥时把整个文件都粘贴进去了平台只认那串以ssh-ed25519开头的内容多一个字符都不行。3. 在 GitHub 或 Gitee 上建立一个空仓库3.1 GitHub 新建仓库的关键细节以 GitHub 为例登录后点击 New repository填写仓库名称、选择公开或私有然后直接创建。这里有一个特别容易踩的坑如果你本地已经有项目要推上去创建时不要把 README、.gitignore、License 这些初始化选项勾上。一旦远程仓库里有这些初始化文件本地仓库和远程仓库就会是两个互不相识的历史后面推送时会直接报错还得多绕一段合并的路。既然要配合本地推送最干净的做法是创建一个什么都不带的空仓库。创建完成后的页面会显示一个仓库地址可能是 HTTPS 形式也可能是 SSH 形式记得点击按钮切换到 SSH 选项卡复制那个以gitgithub.com开头的地址。3.2 Gitee 新建仓库的注意事项Gitee 的流程基本一致登录后点“新建仓库”填仓库名称选择开源或私有。同理如果本地已有项目“使用 Readme 初始化这个仓库”这个选项不要勾选。这里额外提醒一句Gitee 对远程仓库的路径和地址风格跟 GitHub 略有差异但 SSH 协议的核心逻辑一样。创建完成后仓库页面同样有 SSH 地址格式是gitgitee.com:用户名/仓库名.git。复制备用就好。3.3 仓库地址的两种写法对比仓库地址很容易混淆我放一张速查表方便对照平台SSH 形式HTTPS 形式GitHubgitgithub.com:用户名/仓库名.githttps://github.com/用户名/仓库名.gitGiteegitgitee.com:用户名/仓库名.githttps://gitee.com/用户名/仓库名.gitSSH 形式适合配好密钥后长期使用推送更顺滑。HTTPS 形式适合临时访问或者不想搞密钥的场景但推送时会被要求验证身份记住这点就够了。4. 本地从零初始化一条龙推上远程仓库4.1 进入项目目录执行 git init打开终端进入你的项目目录。如果不知道目录在哪可以先切到对应路径再执行git init这条命令会在当前目录下生成一个隐藏的.git文件夹它记录着这个项目的所有版本信息。把它理解成仓库登记处以后所有版本操作都由它一手打理。执行完先看一眼状态git status此时目录里所有文件都会以未跟踪的形式出现也就是 Git 还不认识它们。这很正常毕竟刚刚登记还没有谁被正式纳入管理。4.2 把文件加入暂存区并生成第一个提交Git 的工作流程里有一个非常重要的概念叫暂存区。它的作用相当于“待发货仓库”你从工作区挑出本次要提交的文件放进暂存区检查没问题后再一次性打包发出。这不是多此一举而是给开发者一个二次确认的机会避免把临时日志、调试文件、缓存一股脑提交进去。加入全部文件的命令git add .分开添加某个文件或目录git add src/readme.md git add config/app.conf添加之后再看看状态确认暂存区里的内容符合预期然后提交git commit -m feat: 初始化项目结构这里-m后面的内容是提交说明建议写清楚这次提交做了什么。以 “feat” 开头表示新功能以 “fix” 开头表示修复问题这种习惯会让后续回溯历史时省很大力气。如果此时系统提示需要先配置 user.name 和 user.email说明第一步的身份配置漏掉了补上之后重新提交即可。4.3 关联远程仓库并推送现在把本地仓库和远程仓库连接起来这一步是很多新手理解上的分水岭。所谓关联就是在本地仓库里记一条“远程地址”的别名默认的别名是 origingit remote add origin gitgithub.com:你的用户名/你的仓库名.git如果用的是 Gitee就把地址替换成对应的 SSH 地址。关联之后可以查看一下git remote -v看到两条记录分别对应 fetch 和 push 使用的地址说明关联成功。接下来把当前分支改名为 main。Git 新仓库默认分支什么名字都行GitHub 平台现在默认叫 main为了保持一致本地也统一叫 maingit branch -M main然后推送git push -u origin main-u表示把本地的 main 分支和远程仓库的 main 分支绑定起来以后直接在项目目录执行git push就能默认推到这。推送完成后刷新远程仓库页面本地文件应该已经整整齐齐地出现在那里了。注意第一次推送如果报错提示“remote origin already exists”说明这个目录之前已经关联过别的远程地址可以用git remote -v先看再用git remote set-url origin 新地址改掉。5. 以后每次更新从 commit 到 push 的完整节奏5.1 日常三连add、commit、push项目推上去之后并不是就完事了。后面每次改动代码都会持续走一遍固定的三道工序git add . git commit -m feat: 新增登录页面 git push第一道工序是把改动放进暂存区第二道工序是生成一条本地提交记录第三道工序是把本地提交推到远程。这三步对应前面讲的“工作区、暂存区、本地仓库、远程仓库”的数据流动。这里要特别强调一下git add .虽然省事但在大项目里等于闭着眼睛上货。更好的习惯是用git status先看然后单独添加本次相关的文件至少确认没有把.env、密钥文件、临时产物提交上去。提交前再花十秒看下改动内容git diff看到的是尚未暂存的改动确认没问题后再 add是成本最低的保险。5.2 push 被远端顶住的时候先 pull 再看冲突多人协作或者你在网页上直接改动过文件后本地执行git push有可能会被拒绝。报错信息往往写着“failed to push some refs”或者“远程仓库包含本地没有的提交”。这种情况硬推是推不动的正确的做法是先把远程的改动拉下来合并。最简单的处理方式是用 rebase 让本地提交叠加在远程提交后面保持历史更线性git pull origin main --rebase如果本地和远程改的是同一个地方Git 会提示冲突。此时打开冲突文件里面会有标记示意两边内容的分界手动整理成最终想要的版本然后执行git add 冲突文件 git rebase --continue没有冲突则不需要额外操作直接再推一次git push这种“先拉后推”的习惯应该刻进肌肉记忆里。别一看到拒绝就想着git push -f强制推送强制推送会覆盖远程历史在共享分支上这样做等于自毁长城。5.3 一个仓库同时推到 GitHub 和 Gitee不少人有这样的需求本地代码既想放 GitHub又想放 Gitee方便国内访问。操作方法并不复杂核心是利用 Git 可以配置多个远程地址的特性把两个平台分别当作不同的远程名来管理。首先添加两个远程git remote add github gitgithub.com:用户名/仓库名.git git remote add gitee gitgitee.com:用户名/仓库名.git注意这里我没有用默认的 origin而是用了 github 和 gitee 两个名字这样一眼就能辨认对面是谁。之后推送时就分别执行git push github main git push gitee main如果希望第一次就绑定上游可以写成git push -u github main git push -u gitee main需要移除某个远程时用git remote remove github即可。这种双远端方案特别适合把 GitHub 作为主仓库、Gitee 作为国内镜像的场景配置一次之后推两遍也不算麻烦。6. 高频报错与排查技巧实录6.1 提示 Permission denied (publickey)看到这个报错说明 SSH 密钥没有被远程平台识别。先按顺序排查密钥是否生成、公钥是否完整粘贴、平台是否保存成功、当前机器是否确实在使用这把私钥。必要时用ssh -T gitgithub.com手动测试成功的输出里会带上你的用户名这能直接确认问题出在哪。还有一种情况是私钥不在默认路径导致客户端没找到。可以用ssh-add手动添加或者检查是不是因为这个平台配置了多个密钥需要指定~/.ssh/config里的 Host 规则。不过新手阶段最可能的问题还是公钥粘贴不完整或者复制到了私钥。6.2 推送时报 fatal: repository not found仓库地址错误或者权限不够。检查地址里的用户名、仓库名是不是完全正确注意大小写。如果仓库是私有的确认当前 SSH 密钥是不是有权限访问。还有一种细节很容易忽略地址里的用户名是平台账号名不是仓库名。6.3 单个文件太大推不上去GitHub 和 Gitee 对单文件体积都有硬限制超出之后推送会直接拒绝。遇到这种情况先确认是不是误把二进制大文件放进仓库比如压缩包、模型文件、数据库文件。解决办法是先用工具确认大文件路径把它们移出版本控制再考虑要不要用 Git LFS 这类专门方案管理大文件。如果一个大文件已经被提交进历史记录单纯删除当前版本还不够需要重写历史才能彻底移除这个过程对新手并不友好所以最好的策略是在项目一开始就写一个靠谱的.gitignore把不需要进仓库的文件提前挡在门外。6.4 换行符问题CRLF 和 LF 的经典内战Windows 默认用回车加换行表示分行Linux 和 macOS 则只用换行。跨平台协作时Git 经常会提示“LF will be replaced by CRLF”这类信息。最稳妥的办法是 Windows 上开启自动转换git config --global core.autocrlf truemacOS 和 Linux 上则设置成git config --global core.autocrlf input这样提交到仓库的统一是 LF 格式本地检出时 Windows 自动转回 CRLF两边都不受罪。另外如果遇到中文文件名显示为转义字符可以打开一个开关git config --global core.quotepath false之后中文文件名就不会再变成一串八进制数字了。6.5 常见错误速查表现象常见原因处理思路remote origin already exists已经关联过远程用git remote set-url origin 新地址替换Permission denied (publickey)密钥未配置或粘贴不完整检查公钥配置测试ssh -Tfailed to push some refs远程有本地没有的提交git pull origin main --rebase后重新推repository not found地址错误或无权限核对仓库名、账号名、私有权限单文件超出大小限制误提交大文件移出仓库或使用 Git LFSCRLF 与 LF 警告平台换行符差异设置 core.autocrlf7. 我每次都会注意的几个使用习惯写到这里基础的上传流程已经覆盖得比较完整了。再分享几个我实际操作中慢慢养成的习惯算是在踩过坑之后沉淀下来的经验。提交信息不要写“update”这种废话。哪怕只是改了三个字也要说明改了什么比如“fix: 修复列表加载空数据时页面崩溃”。以后回看日志时这种信息能让你节省大量回忆成本。推送之前养成看 diff 的习惯。git diff不只看内容更要看成份尤其要确认有没有密钥、密码、token 这类敏感信息混进去。一旦把密钥推到公开仓库第一时间危险第二时间就要立刻去平台撤销并重新生成安全意识和流程习惯同样重要。给稳定的版本打标签。代码不只是往 main 分支上推还可以在重要节点用标签标记版本比如git tag v1.0.0 git push origin v1.0.0标签在远程仓库里会以一个清晰的版本号出现比靠人脑记住“第几次提交”靠谱得多。最后再说一个小技巧新机器上我会把常用命令配成别名减少重复敲长命令的时间。比如git config --global alias.lg log --oneline --decorate --graph git config --global alias.st status配置之后一个git lg就能看到清晰的提交历史拓扑git st就能快速查看状态。别小看这些小别名日积月累下来的效率提升很明显。把本地文件上传到 GitHub 或 Gitee本质上就是搭好一条从工作区到远程仓库的流水线。第一次配置 SSH、建库、推送可能会花一点时间但配好之后后面每次提交和推送都只是几十秒的事。先用这套基础流程跑顺再慢慢接触分支、标签、变基这些进阶操作你会发现 Git 越用越顺手。