第一次在GitHub上创建远程仓库的时候我以为“提交本地仓库”就是把文件拖上去像往网盘上传一样简单。真正动手才发现GitHub远程仓库背后的逻辑完全是另一套你需要在本地先把改动固化成一条条commit记录再用git remote把本地仓库和远程仓库关联起来最后用git push把提交推上去。这三个环节缺一个都会在命令行里翻车。这篇文章就是把这条链路彻底拆开讲清楚远程仓库到底是什么、创建仓库时那些选项该怎么选、本地提交与推送每一步在做什么以及第一次推送最常遇到的报错怎么救。适合刚学会git add和git commit、准备第一次创建仓库的新手也适合那些日常只用图形界面、从没理解过origin和main含义的开发者。1. 远程仓库到底在解决什么问题1.1 一个比喻本地仓库是草稿本远程仓库是成品交卷如果说本地仓库是你随写随改的草稿本那远程仓库就是你要提交出去的成品版本。草稿本上你可以随便涂改、整页撕掉对应本地commit的反复操作成品则需要干净、完整、让别人看得懂对应远程仓库里的项目面貌。但Git的“交卷”不是把整个本子一次性扔过去而是只把新写的那几页递过去对方自己拼出完整版本也就是推送增量commit。这个比喻可以解释新手最常见的困惑为什么本地改了文件、删了文件GitHub页面上完全没动静因为本地仓库和远程仓库本来就是两份各自独立的仓库不存在自动同步。每一次数据交换都是你主动发起的push把本地新提交推送到远程pull把远程新提交拉回本地。理解这个“两份独立仓库”的模型后面所有命令都顺理成章遇到报错时也能迅速定位问题出在本地还是远程。1.2 远程仓库的三个核心价值备份、协作、发布远程仓库的第一个价值是备份。本地硬盘可能损坏电脑可能丢失只要代码在远程仓库里有一份完整副本项目的所有历史提交都能恢复这大概是很多人第一次认真使用GitHub的真实动力。第二个价值是协作。多个开发者各自把远程仓库克隆到本地分别开发再通过push和pull交换成果远程仓库就是多方约定的会合点。少了这个会合点团队协作就只能靠U盘和聊天软件传代码版本混乱几乎是必然的。第三个价值是发布。把仓库设为Public之后任何人都能查看代码、提出问题、提交Pull Request项目从私人草稿变成了可以公开讨论的社区成员。这三个价值对应不同使用场景个人笔记和配置备份只需要价值一团队项目依赖价值二开源项目则同时用到价值二和价值三。想清楚自己需要哪一层才知道仓库该设为Public还是Private该不该写README和License。1.3 “提交到GitHub”这个说法背后的真实动作链还有一个高频误解很多人以为“提交到GitHub”就是把本地目录整体覆盖到远程所以总想着重新上传一份。实际上标准动作链是先在本地执行git commit再执行git push。push推的不是整个目录而是本地仓库中远程仓库还没有的那些commit记录及其对应的文件变更。远程仓库会在自身已有历史的基础上把新提交拼接上去。所以当本地历史跟远程历史“接不上”的时候Git会直接拒绝推送。这不是Git在为难你而是为了防止破坏提交历史的完整性。理解这一点之后遇到rejected、fetch first、unrelated histories这些报错时你就不会被吓住而是知道自己该去对齐哪一段历史。远程仓库从来不是网盘它的核心资产不是文件快照而是完整的提交历史。2. 动手前先把这些基础配置搞定创建仓库之前有几步基础配置建议先完成。它们不直接出现在创建仓库的操作里却决定了后面的推送是否顺畅以及每一条commit上挂的是谁的名字。别小看这一步很多人在推送之后才发现提交作者信息不对回头改已经迟了。2.1 安装Git并确认命令可用首先得保证本机有Git这个工具。Windows用户建议从官方渠道下载安装包安装时一路保留默认选项就行macOS用户装好之后同样先验证一下环境。装完打开终端或命令行输入git --version能输出版本号就说明基础环境没问题。这一步看似多余却经常有人跳过结果后面执行git init时提示找不到命令才意识到本机根本没有装Git白白浪费排查时间。一个容易被忽略的细节是如果装完Git后发现终端还是找不到命令Windows用户可能需要重启一次终端窗口让环境变量生效macOS用户如果之前用过旧版自带Git也要确认当前用的是新装的版本。这些弯弯绕绕不值得记记住“先确认git --version有输出”这一条就够了。2.2 配置用户名与邮箱commit上的署名从哪来Git要求每一条提交都带作者信息否则拒绝提交。配置全局身份用这两行命令git config --global user.name 你的用户名 git config --global user.email 你的邮箱邮箱建议和注册GitHub用的邮箱保持一致因为GitHub会依据邮箱把本地推送上去的提交归属到对应账号。邮箱不一致提交也能推送成功但GitHub页面上会显示成一个没有头像、没有主页关联的陌生人作者事后追改历史非常麻烦。用git config --list可以查看当前全部配置单独查看某项则用git config user.name。2.3 SSH密钥一次配置换来长期免密推送在GitHub上做认证有两种主流方式SSH密钥和HTTPS地址加Token。对新手来说我更推荐一次配置SSH密钥。生成命令ssh-keygen -t ed25519 -C 你的邮箱一路回车默认在用户目录的.ssh文件夹下生成一对密钥id_ed25519是私钥id_ed25519.pub是公钥。私钥留在本地公钥内容添加到GitHub账号设置的SSH keys里。配置完成后验证ssh -T gitgithub.com看到欢迎语说明链路已通。之后每次push和pull都不需要输入密码一劳永逸。这里要特别注意私钥文件千万不能泄露也不要提交到任何仓库里。如果怀疑私钥泄露第一时间在GitHub上删除对应的公钥重新生成一对。2.4 为什么推荐SSH而不是HTTPS地址很多教程截图用的是HTTPS地址新手直接复制粘贴也能用但后续大概率会遇到认证问题。新版Git对HTTPS推送已经不再接受单纯密码必须使用Token而Token有有效期过期后要重新生成生成时还要仔细勾选权限范围这对新手是额外的负担。SSH走的则是密钥对认证本地的私钥自动完成签名不需要输入任何凭据。配置成本只在刚开始那两分钟之后的体验差距非常明显。所以我的建议很直接别因为HTTPS地址短就选它把SSH密钥配置好复制仓库地址时选SSH那一栏后面省心得多。也不要因为“SSH听起来很难”就回避它本质上只是生成一对文件再粘一串文本的事。3. 在GitHub上创建仓库每个选项都别乱选登录GitHub后点页面右上角的加号选择New repository就进入创建页。这个页面看似简单每个字段和勾选都会影响后续操作尤其是当你本地已经有代码时选错选项几乎必然导致第一次推送被拒。3.1 仓库名与描述URL的一部分不是随便填的装饰Repository name会直接出现在仓库访问地址里是URL的一部分。建议全小写用短横线连接单词例如my-first-project。不要用空格、大写和特殊符号否则生成的URL又长又怪分享和引用都很麻烦。Description写在仓库名下方是可选的项目一句话介绍别人搜索或浏览时更容易判断这个项目是做什么的。它不影响功能但写清楚好处很多尤其是准备公开发布的项目一句准确的描述往往比代码本身更快吸引到对的读者。3.2 Public还是Private先判断这个项目要不要见人Public意味着任何人都能查看你的代码、克隆仓库、提交IssuePrivate意味着只有你显式邀请的人能看到。没有绝对正确的选择取决于项目性质。日常练习、个人配置备份、还没整理好的半成品建议选Private等代码成熟再改成Public也不迟。不少新手第一次创建仓库时选Public只是因为觉得公开很酷。如果代码里混进了环境变量、密码、内部路径这类敏感信息公开仓库等于把家底亮给所有人看这个隐患很难补救。Git仓库的历史记录里一旦出现敏感内容删除文件并不会把敏感信息从历史里抹掉后续处理非常痛苦。3.3 README、.gitignore、License三个初始化选项的取舍创建页面下方有三个初始化选项这里是最容易埋坑的地方三个选项的用途和选择策略整理如下初始化选项作用从零开始建仓库时本地已有提交历史时README自动生成项目说明文件建议勾选不要勾选.gitignore生成忽略规则模板建议勾选不要勾选License生成开源许可证文件计划开源时勾选不要勾选README是项目的门面让访客一眼知道项目用途、使用方法。.gitignore按项目类型提供模板例如Python项目会预置忽略缓存目录、虚拟环境等。License是开源许可证决定了别人能否使用、修改、分发你的代码。这三个选项本身都是好东西但前提是适合“从零开始”的仓库。3.4 本地已有代码时全部初始化选项都别勾关键就在这里如果你在本机已经有一个经过多次提交的本地仓库创建远程仓库时再勾选任何初始化选项远程仓库就有了一个独立的初始提交。于是本地和远程各自拥有互不相干的历史起点第一次push必然被Git拒绝。所以直接给结论本地已有项目代码时创建远程仓库的三个初始化选项全部不要勾让远程仓库保持没有任何提交的空白状态之后把本地完整历史一次性推上来。如果远程仓库已经被勾出了README也不是死局后面报错章节会讲怎么合并但最省事的做法就是从一开始别勾。类似的道理也适用于本地还没有代码的情况那时勾上反而能帮你省去手动创建README的功夫。4. 本地仓库提交与推送的完整链路创建完远程仓库接下来就是“提交本地仓库”的核心操作。这一段我要把每条命令拆开讲因为很多人背下了命令却不知道每一条到底在做什么出问题时自然无从下手。4.1 起步场景判断三种情况三种流程先判断自己属于哪种情况。第一种远程仓库完全空白本地项目存在但还不是Git仓库这是最常见的新手起步方式。第二种远程仓库初始化了README等文件本地项目也是新的需要先处理两套历史的合并。第三种本地已经是Git仓库且提交过多次远程刚建好只需完成关联和推送。本文按第一种展开第二、第三种的处理会在下一章报错部分补上。判断的标准很简单打开终端切到项目目录执行git status。如果提示“not a git repository”就是第一种如果已经能看到修改过的文件列表那就是第三种。先花十秒钟做这个判断能避免后续一系列误操作。4.2 初始化本地仓库init、add、commit的先后关系进入项目目录执行git init这一步在项目根目录生成.git文件夹项目从此成为一个仓库但里面还没有任何提交。接着创建或确认.gitignore文件把不需要入库的内容排除在外例如日志、本地缓存、环境配置文件# 示例Java项目常见忽略项 target/ *.class .idea/ *.iml然后暂存并提交git add . git commit -m first commitgit add .把未被忽略的文件放入暂存区git commit把暂存区内容固化成一条历史记录。提交前务必用git status确认没有意外文件很多人在这一步没检查把密钥文件、下载目录直接提交了上去推送后才追悔莫及。删除历史记录比删除文件麻烦得多宁可提交前多花三十秒。4.3 关联远程仓库remote add到底在做什么回到GitHub仓库页面复制仓库地址。配置过SSH就复制SSH栏地址没有配置就复制HTTPS地址。在本地执行git remote add origin 仓库地址这条命令给本地仓库关联一个名为origin的远程仓库指向复制的地址。origin只是一个约定俗成的名字理论上可以叫别的但所有工具和教程都预期origin没必要花心思改名。关联后检查git remote -v输出里出现fetch和push两组地址就说明关联成功。这一步很多人漏掉检查结果添加失败还以为下一步push卡住是别的问题。如果执行remote add时报“remote origin already exists”说明之前已经关联过先看5.1的处理方式。4.4 首次推送统一分支名并用-u建立跟踪关系推送前先处理分支名。不同版本Git初始分支名不同老的默认master新的默认mainGitHub新建仓库的主分支是main。为了让本地和远程对齐先把本地分支改名为maingit branch -M main然后推送git push -u origin main这里的-u是--set-upstream的简写表示把本地main分支与远程origin/main建立跟踪关系。之后直接敲git push和git pull即可无需每次带远程名和分支名。推送完成后刷新GitHub仓库页面代码、提交历史和文件结构都会出现在眼前。“先统一分支名再推送”这个顺序是新手很容易漏掉但非常关键的细节。本地一直用master远程默认main推上去要么报错要么生成两个主分支后续管理一团乱。加一条git branch -M main一分钟的功夫能省掉后面一整晚的排查。5. 第一次推送就翻车高频报错与修复就算按上面的顺序操作第一次推送还是可能出现各种问题。我把自己真实遇到的、以及周围朋友问得最多的几种报错整理出来按排查链路讲清楚。遇到报错别慌Git的报错信息通常已经把原因说得很明白了。报错关键词原因类别优先排查方向remote origin already exists远程关联重复git remote -v查看当前地址Repository not found地址或权限问题核对地址、仓库可见性、SSH密钥rejected / fetch first双方历史分叉拉取合并或确认后果后谨慎强推unrelated histories两套历史无公共祖先合并时允许无关历史认证失败凭据或Token无效建议直接切到SSH密钥5.1 remote origin already exists远程关联重复执行git remote add origin时报这个错误说明本地仓库以前已经关联过一个远程地址。先执行git remote -v查看当前指向再判断如果地址本来就是对的直接跳过添加继续下一步如果地址是错的需要先删后加git remote remove origin git remote add origin 正确地址这个报错常见于跟着多个教程反复执行关联命令或者IDE的图形化界面已经帮你自动添加过远程。处理逻辑很简单但记得别在没确认旧地址是否正确时盲目用set-url改先看清楚再说。检查完地址之后用git remote -v再确认一遍确保只剩一条origin。5.2 Repository not found地址、权限与SSH的排查顺序推送时提示Repository not found最常见三个原因仓库地址写错、仓库设为Private但当前账号没有权限、SSH密钥没有正确绑定到账号。排查顺序应该是先核对地址再确认仓库可见性最后验证SSHssh -T gitgithub.com如果SSH验证已通过仓库地址也没抄错那问题多半出在用户名或仓库名的大小写上。GitHub的仓库名严格区分大小写手动输入地址时很容易出错所以复制地址时不要自己敲直接复制最稳妥。另外如果你换了电脑或清理过.ssh目录旧密钥文件没了也会表现为同样的报错重新生成并添加公钥即可。5.3 ! [rejected] fetch first两套历史分叉的两种解法如果创建远程仓库时勾了README或者之后在GitHub网页上手动改过文件远程就会多出本地没有的提交。本地push时Git发现双方历史分叉就会拒绝并提示fetch first。两种解法分别对应两种场景。如果你确认远程那些初始化文件根本不需要且这是全新仓库、没有其他协作者那么可以直接强制覆盖git push -f origin main但-f务必慎用它会用本地历史覆盖远程历史任何远程有而本地没有的提交都会丢失多人协作时绝对禁止。更稳妥的做法是把远程历史拉下来合并再推送git pull origin main --allow-unrelated-histories git push origin main--allow-unrelated-histories允许两个没有公共祖先的仓库合并合并产生的冲突需要手动解决解决后提交一次push就能顺利通过。5.4 refusing to merge unrelated histories强制联姻的代价这个报错和5.3紧密相关本地仓库和远程仓库各带一套独立历史时git pull默认拒绝合并因为它认为两个毫无血缘的历史强行合并风险太高。解决办法就是上一节提到的加--allow-unrelated-histories参数。合并过程中最常见的冲突是同名文件比如本地有一个README远程也有一个READMEGit会要求你决定保留哪份。处理思路是保留你真正需要的内容把多余的那份删掉然后git add、git commit完成合并。但诚实地讲对新手来说最省事的方案仍然是从源头避免本地已有代码时创建远程仓库不勾任何初始化文件从一开始就不要产生两套并行历史。5.5 认证失败Token和SSH的最终选择用HTTPS地址推送时遇到认证失败多半是输入了普通密码而Git要求用Token或者Token权限不足。处理方式是重新生成一个有repo权限的Token推送时用户名填GitHub用户名密码位置粘贴Token。虽然可以把Token存进系统凭据管理器减少重复输入但整体复杂度依然高于SSH。所以我反复强调的建议是多花两分钟配置好SSH密钥之后所有认证问题自动消失。至于推送超时或缓慢的情况先检查系统级的网络设置与防火墙策略是否正常排除外部因素后推送在正常网络环境下都应该是几十秒内完成的事不需要在Git本身找原因。最后分享一个我后来一直保持的习惯每次push之前先跑一遍git status和git remote -v确认没有多余文件、远程地址没错再执行推送。这个习惯在多项目之间切换时尤其有用因为最容易犯的错误不是命令写错而是把A项目的代码推到了B项目的远程仓库那种尴尬比任何报错都难收拾。Git的具体命令可以边用边查但“关联、检查、推送”这套心智流程建议从一开始就刻进习惯里。 
长河君 · 2026/10/21 5:46:16 · 阅读 1.2k Git远程仓库入门：从本地commit到GitHub push的完整教程
第一次在GitHub上创建远程仓库的时候我以为“提交本地仓库”就是把文件拖上去像往网盘上传一样简单。真正动手才发现GitHub远程仓库背后的逻辑完全是另一套你需要在本地先把改动固化成一条条commit记录再用git remote把本地仓库和远程仓库关联起来最后用git push把提交推上去。这三个环节缺一个都会在命令行里翻车。这篇文章就是把这条链路彻底拆开讲清楚远程仓库到底是什么、创建仓库时那些选项该怎么选、本地提交与推送每一步在做什么以及第一次推送最常遇到的报错怎么救。适合刚学会git add和git commit、准备第一次创建仓库的新手也适合那些日常只用图形界面、从没理解过origin和main含义的开发者。1. 远程仓库到底在解决什么问题1.1 一个比喻本地仓库是草稿本远程仓库是成品交卷如果说本地仓库是你随写随改的草稿本那远程仓库就是你要提交出去的成品版本。草稿本上你可以随便涂改、整页撕掉对应本地commit的反复操作成品则需要干净、完整、让别人看得懂对应远程仓库里的项目面貌。但Git的“交卷”不是把整个本子一次性扔过去而是只把新写的那几页递过去对方自己拼出完整版本也就是推送增量commit。这个比喻可以解释新手最常见的困惑为什么本地改了文件、删了文件GitHub页面上完全没动静因为本地仓库和远程仓库本来就是两份各自独立的仓库不存在自动同步。每一次数据交换都是你主动发起的push把本地新提交推送到远程pull把远程新提交拉回本地。理解这个“两份独立仓库”的模型后面所有命令都顺理成章遇到报错时也能迅速定位问题出在本地还是远程。1.2 远程仓库的三个核心价值备份、协作、发布远程仓库的第一个价值是备份。本地硬盘可能损坏电脑可能丢失只要代码在远程仓库里有一份完整副本项目的所有历史提交都能恢复这大概是很多人第一次认真使用GitHub的真实动力。第二个价值是协作。多个开发者各自把远程仓库克隆到本地分别开发再通过push和pull交换成果远程仓库就是多方约定的会合点。少了这个会合点团队协作就只能靠U盘和聊天软件传代码版本混乱几乎是必然的。第三个价值是发布。把仓库设为Public之后任何人都能查看代码、提出问题、提交Pull Request项目从私人草稿变成了可以公开讨论的社区成员。这三个价值对应不同使用场景个人笔记和配置备份只需要价值一团队项目依赖价值二开源项目则同时用到价值二和价值三。想清楚自己需要哪一层才知道仓库该设为Public还是Private该不该写README和License。1.3 “提交到GitHub”这个说法背后的真实动作链还有一个高频误解很多人以为“提交到GitHub”就是把本地目录整体覆盖到远程所以总想着重新上传一份。实际上标准动作链是先在本地执行git commit再执行git push。push推的不是整个目录而是本地仓库中远程仓库还没有的那些commit记录及其对应的文件变更。远程仓库会在自身已有历史的基础上把新提交拼接上去。所以当本地历史跟远程历史“接不上”的时候Git会直接拒绝推送。这不是Git在为难你而是为了防止破坏提交历史的完整性。理解这一点之后遇到rejected、fetch first、unrelated histories这些报错时你就不会被吓住而是知道自己该去对齐哪一段历史。远程仓库从来不是网盘它的核心资产不是文件快照而是完整的提交历史。2. 动手前先把这些基础配置搞定创建仓库之前有几步基础配置建议先完成。它们不直接出现在创建仓库的操作里却决定了后面的推送是否顺畅以及每一条commit上挂的是谁的名字。别小看这一步很多人在推送之后才发现提交作者信息不对回头改已经迟了。2.1 安装Git并确认命令可用首先得保证本机有Git这个工具。Windows用户建议从官方渠道下载安装包安装时一路保留默认选项就行macOS用户装好之后同样先验证一下环境。装完打开终端或命令行输入git --version能输出版本号就说明基础环境没问题。这一步看似多余却经常有人跳过结果后面执行git init时提示找不到命令才意识到本机根本没有装Git白白浪费排查时间。一个容易被忽略的细节是如果装完Git后发现终端还是找不到命令Windows用户可能需要重启一次终端窗口让环境变量生效macOS用户如果之前用过旧版自带Git也要确认当前用的是新装的版本。这些弯弯绕绕不值得记记住“先确认git --version有输出”这一条就够了。2.2 配置用户名与邮箱commit上的署名从哪来Git要求每一条提交都带作者信息否则拒绝提交。配置全局身份用这两行命令git config --global user.name 你的用户名 git config --global user.email 你的邮箱邮箱建议和注册GitHub用的邮箱保持一致因为GitHub会依据邮箱把本地推送上去的提交归属到对应账号。邮箱不一致提交也能推送成功但GitHub页面上会显示成一个没有头像、没有主页关联的陌生人作者事后追改历史非常麻烦。用git config --list可以查看当前全部配置单独查看某项则用git config user.name。2.3 SSH密钥一次配置换来长期免密推送在GitHub上做认证有两种主流方式SSH密钥和HTTPS地址加Token。对新手来说我更推荐一次配置SSH密钥。生成命令ssh-keygen -t ed25519 -C 你的邮箱一路回车默认在用户目录的.ssh文件夹下生成一对密钥id_ed25519是私钥id_ed25519.pub是公钥。私钥留在本地公钥内容添加到GitHub账号设置的SSH keys里。配置完成后验证ssh -T gitgithub.com看到欢迎语说明链路已通。之后每次push和pull都不需要输入密码一劳永逸。这里要特别注意私钥文件千万不能泄露也不要提交到任何仓库里。如果怀疑私钥泄露第一时间在GitHub上删除对应的公钥重新生成一对。2.4 为什么推荐SSH而不是HTTPS地址很多教程截图用的是HTTPS地址新手直接复制粘贴也能用但后续大概率会遇到认证问题。新版Git对HTTPS推送已经不再接受单纯密码必须使用Token而Token有有效期过期后要重新生成生成时还要仔细勾选权限范围这对新手是额外的负担。SSH走的则是密钥对认证本地的私钥自动完成签名不需要输入任何凭据。配置成本只在刚开始那两分钟之后的体验差距非常明显。所以我的建议很直接别因为HTTPS地址短就选它把SSH密钥配置好复制仓库地址时选SSH那一栏后面省心得多。也不要因为“SSH听起来很难”就回避它本质上只是生成一对文件再粘一串文本的事。3. 在GitHub上创建仓库每个选项都别乱选登录GitHub后点页面右上角的加号选择New repository就进入创建页。这个页面看似简单每个字段和勾选都会影响后续操作尤其是当你本地已经有代码时选错选项几乎必然导致第一次推送被拒。3.1 仓库名与描述URL的一部分不是随便填的装饰Repository name会直接出现在仓库访问地址里是URL的一部分。建议全小写用短横线连接单词例如my-first-project。不要用空格、大写和特殊符号否则生成的URL又长又怪分享和引用都很麻烦。Description写在仓库名下方是可选的项目一句话介绍别人搜索或浏览时更容易判断这个项目是做什么的。它不影响功能但写清楚好处很多尤其是准备公开发布的项目一句准确的描述往往比代码本身更快吸引到对的读者。3.2 Public还是Private先判断这个项目要不要见人Public意味着任何人都能查看你的代码、克隆仓库、提交IssuePrivate意味着只有你显式邀请的人能看到。没有绝对正确的选择取决于项目性质。日常练习、个人配置备份、还没整理好的半成品建议选Private等代码成熟再改成Public也不迟。不少新手第一次创建仓库时选Public只是因为觉得公开很酷。如果代码里混进了环境变量、密码、内部路径这类敏感信息公开仓库等于把家底亮给所有人看这个隐患很难补救。Git仓库的历史记录里一旦出现敏感内容删除文件并不会把敏感信息从历史里抹掉后续处理非常痛苦。3.3 README、.gitignore、License三个初始化选项的取舍创建页面下方有三个初始化选项这里是最容易埋坑的地方三个选项的用途和选择策略整理如下初始化选项作用从零开始建仓库时本地已有提交历史时README自动生成项目说明文件建议勾选不要勾选.gitignore生成忽略规则模板建议勾选不要勾选License生成开源许可证文件计划开源时勾选不要勾选README是项目的门面让访客一眼知道项目用途、使用方法。.gitignore按项目类型提供模板例如Python项目会预置忽略缓存目录、虚拟环境等。License是开源许可证决定了别人能否使用、修改、分发你的代码。这三个选项本身都是好东西但前提是适合“从零开始”的仓库。3.4 本地已有代码时全部初始化选项都别勾关键就在这里如果你在本机已经有一个经过多次提交的本地仓库创建远程仓库时再勾选任何初始化选项远程仓库就有了一个独立的初始提交。于是本地和远程各自拥有互不相干的历史起点第一次push必然被Git拒绝。所以直接给结论本地已有项目代码时创建远程仓库的三个初始化选项全部不要勾让远程仓库保持没有任何提交的空白状态之后把本地完整历史一次性推上来。如果远程仓库已经被勾出了README也不是死局后面报错章节会讲怎么合并但最省事的做法就是从一开始别勾。类似的道理也适用于本地还没有代码的情况那时勾上反而能帮你省去手动创建README的功夫。4. 本地仓库提交与推送的完整链路创建完远程仓库接下来就是“提交本地仓库”的核心操作。这一段我要把每条命令拆开讲因为很多人背下了命令却不知道每一条到底在做什么出问题时自然无从下手。4.1 起步场景判断三种情况三种流程先判断自己属于哪种情况。第一种远程仓库完全空白本地项目存在但还不是Git仓库这是最常见的新手起步方式。第二种远程仓库初始化了README等文件本地项目也是新的需要先处理两套历史的合并。第三种本地已经是Git仓库且提交过多次远程刚建好只需完成关联和推送。本文按第一种展开第二、第三种的处理会在下一章报错部分补上。判断的标准很简单打开终端切到项目目录执行git status。如果提示“not a git repository”就是第一种如果已经能看到修改过的文件列表那就是第三种。先花十秒钟做这个判断能避免后续一系列误操作。4.2 初始化本地仓库init、add、commit的先后关系进入项目目录执行git init这一步在项目根目录生成.git文件夹项目从此成为一个仓库但里面还没有任何提交。接着创建或确认.gitignore文件把不需要入库的内容排除在外例如日志、本地缓存、环境配置文件# 示例Java项目常见忽略项 target/ *.class .idea/ *.iml然后暂存并提交git add . git commit -m first commitgit add .把未被忽略的文件放入暂存区git commit把暂存区内容固化成一条历史记录。提交前务必用git status确认没有意外文件很多人在这一步没检查把密钥文件、下载目录直接提交了上去推送后才追悔莫及。删除历史记录比删除文件麻烦得多宁可提交前多花三十秒。4.3 关联远程仓库remote add到底在做什么回到GitHub仓库页面复制仓库地址。配置过SSH就复制SSH栏地址没有配置就复制HTTPS地址。在本地执行git remote add origin 仓库地址这条命令给本地仓库关联一个名为origin的远程仓库指向复制的地址。origin只是一个约定俗成的名字理论上可以叫别的但所有工具和教程都预期origin没必要花心思改名。关联后检查git remote -v输出里出现fetch和push两组地址就说明关联成功。这一步很多人漏掉检查结果添加失败还以为下一步push卡住是别的问题。如果执行remote add时报“remote origin already exists”说明之前已经关联过先看5.1的处理方式。4.4 首次推送统一分支名并用-u建立跟踪关系推送前先处理分支名。不同版本Git初始分支名不同老的默认master新的默认mainGitHub新建仓库的主分支是main。为了让本地和远程对齐先把本地分支改名为maingit branch -M main然后推送git push -u origin main这里的-u是--set-upstream的简写表示把本地main分支与远程origin/main建立跟踪关系。之后直接敲git push和git pull即可无需每次带远程名和分支名。推送完成后刷新GitHub仓库页面代码、提交历史和文件结构都会出现在眼前。“先统一分支名再推送”这个顺序是新手很容易漏掉但非常关键的细节。本地一直用master远程默认main推上去要么报错要么生成两个主分支后续管理一团乱。加一条git branch -M main一分钟的功夫能省掉后面一整晚的排查。5. 第一次推送就翻车高频报错与修复就算按上面的顺序操作第一次推送还是可能出现各种问题。我把自己真实遇到的、以及周围朋友问得最多的几种报错整理出来按排查链路讲清楚。遇到报错别慌Git的报错信息通常已经把原因说得很明白了。报错关键词原因类别优先排查方向remote origin already exists远程关联重复git remote -v查看当前地址Repository not found地址或权限问题核对地址、仓库可见性、SSH密钥rejected / fetch first双方历史分叉拉取合并或确认后果后谨慎强推unrelated histories两套历史无公共祖先合并时允许无关历史认证失败凭据或Token无效建议直接切到SSH密钥5.1 remote origin already exists远程关联重复执行git remote add origin时报这个错误说明本地仓库以前已经关联过一个远程地址。先执行git remote -v查看当前指向再判断如果地址本来就是对的直接跳过添加继续下一步如果地址是错的需要先删后加git remote remove origin git remote add origin 正确地址这个报错常见于跟着多个教程反复执行关联命令或者IDE的图形化界面已经帮你自动添加过远程。处理逻辑很简单但记得别在没确认旧地址是否正确时盲目用set-url改先看清楚再说。检查完地址之后用git remote -v再确认一遍确保只剩一条origin。5.2 Repository not found地址、权限与SSH的排查顺序推送时提示Repository not found最常见三个原因仓库地址写错、仓库设为Private但当前账号没有权限、SSH密钥没有正确绑定到账号。排查顺序应该是先核对地址再确认仓库可见性最后验证SSHssh -T gitgithub.com如果SSH验证已通过仓库地址也没抄错那问题多半出在用户名或仓库名的大小写上。GitHub的仓库名严格区分大小写手动输入地址时很容易出错所以复制地址时不要自己敲直接复制最稳妥。另外如果你换了电脑或清理过.ssh目录旧密钥文件没了也会表现为同样的报错重新生成并添加公钥即可。5.3 ! [rejected] fetch first两套历史分叉的两种解法如果创建远程仓库时勾了README或者之后在GitHub网页上手动改过文件远程就会多出本地没有的提交。本地push时Git发现双方历史分叉就会拒绝并提示fetch first。两种解法分别对应两种场景。如果你确认远程那些初始化文件根本不需要且这是全新仓库、没有其他协作者那么可以直接强制覆盖git push -f origin main但-f务必慎用它会用本地历史覆盖远程历史任何远程有而本地没有的提交都会丢失多人协作时绝对禁止。更稳妥的做法是把远程历史拉下来合并再推送git pull origin main --allow-unrelated-histories git push origin main--allow-unrelated-histories允许两个没有公共祖先的仓库合并合并产生的冲突需要手动解决解决后提交一次push就能顺利通过。5.4 refusing to merge unrelated histories强制联姻的代价这个报错和5.3紧密相关本地仓库和远程仓库各带一套独立历史时git pull默认拒绝合并因为它认为两个毫无血缘的历史强行合并风险太高。解决办法就是上一节提到的加--allow-unrelated-histories参数。合并过程中最常见的冲突是同名文件比如本地有一个README远程也有一个READMEGit会要求你决定保留哪份。处理思路是保留你真正需要的内容把多余的那份删掉然后git add、git commit完成合并。但诚实地讲对新手来说最省事的方案仍然是从源头避免本地已有代码时创建远程仓库不勾任何初始化文件从一开始就不要产生两套并行历史。5.5 认证失败Token和SSH的最终选择用HTTPS地址推送时遇到认证失败多半是输入了普通密码而Git要求用Token或者Token权限不足。处理方式是重新生成一个有repo权限的Token推送时用户名填GitHub用户名密码位置粘贴Token。虽然可以把Token存进系统凭据管理器减少重复输入但整体复杂度依然高于SSH。所以我反复强调的建议是多花两分钟配置好SSH密钥之后所有认证问题自动消失。至于推送超时或缓慢的情况先检查系统级的网络设置与防火墙策略是否正常排除外部因素后推送在正常网络环境下都应该是几十秒内完成的事不需要在Git本身找原因。最后分享一个我后来一直保持的习惯每次push之前先跑一遍git status和git remote -v确认没有多余文件、远程地址没错再执行推送。这个习惯在多项目之间切换时尤其有用因为最容易犯的错误不是命令写错而是把A项目的代码推到了B项目的远程仓库那种尴尬比任何报错都难收拾。Git的具体命令可以边用边查但“关联、检查、推送”这套心智流程建议从一开始就刻进习惯里。