企业官网建设流程全解析

同事端着笔记本过来，屏幕上是一屏红字：! [rejected] master -> master (fetch first)，底下还跟着一段error: failed to push some refs to ...。他说代码明明写完了，就是推不上去，已经折腾了快一个小时。这种情况我遇到过太多次了——git push origin master这个命令短得不能再短，但它背后牵扯的东西一点都不少：本地分支和远程分支的状态、认证方式、网络、仓库配置、甚至你的 Git 版本和默认分支名字，任何一个环节对不上，它都会用一屏报错来告诉你"此路不通"。但好消息是，绝大多数这类报错就那么几种，每一种都有清晰的定位方法和固定的解决姿势。这篇内容我打算把git push origin master报错这件事彻底拆开讲：先教你读懂报错信息，再按类型逐个击破，最后整理一份我自己日常在用的常见 git 命令清单。不管你是刚配好环境、第一次把代码往远程仓库推的新手，还是偶尔被认证和分支问题绊一下的老手，都能从里面找到直接能抄的步骤。

1. 报错别慌，先学会从一行信息里定位问题

很多时候人被报错吓住，是因为那一屏字全是英文，看起来像天书。其实 Git 的报错信息写得相当克制，关键信息往往就藏在最后两三行。你要做的是先别急着上网搜整段报错，而是把它拆成几个部分来读。

1.1 一条报错信息的三段结构

拿最常见的这条来说：

To https://github.com/yourname/yourrepo.git ! [rejected] master -> master (fetch first) error: failed to push some refs to 'https://github.com/yourname/yourrepo.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally. ...

我习惯把它拆成三块看。第一块是目的地：To https://github.com/yourname/yourrepo.git，告诉你这次 push 到底推到了哪个远程地址，很多人配置错了 remote，推的根本不是自己想推的仓库，问题就出在这里。第二块是动作结果：! [rejected] master -> master (fetch first)，这行是核心，rejected表示被拒绝，括号里的fetch first是 Git 给出的原因提示。第三块是error:和hint:开头的补充说明，error:是硬性错误，hint:是 Git 好心给的解决建议，读这两行通常就能知道八成。

实操心得：我看报错有个固定习惯，Screen 上翻到最底下，先只看error:那一行和它上面的结果行，中间那些进度、枚举、计数信息基本可以忽略。定位效率比从头逐行读高得多。

1.2 最常见的报错其实就分四大类

把我在实际项目里碰到过的git push报错整理一下，九成以上落在下面四类里，认识它们的分界，就等于拿到了问题的入口。

这张表建议直接存下来，下次报错先对号入座，再往下看对应章节，能省掉大量无头苍蝇式的搜索时间。

1.3 动手前先做两件事自检

在真正动手改任何东西之前，我强烈建议你先跑两条命令，把当前状态摸清楚，心里有底再操作。

git status git remote -v

第一条git status告诉你本地现在有哪些改动、在哪个分支、有没有未提交的内容。第二条git remote -v列出你配置的所有远程地址以及它们的名字——这一步太重要了，我见过太多人以为自己在推origin，结果 remote 里压根没有 origin，或者 origin 指向的是一个几年前的旧仓库。先确认这两点，很多"莫名其妙"的报错当场就能解释清楚。

2. 推送被拒绝（rejected）类报错，从根上解决

这是出现频率最高的一类，没有之一。你敲下git push origin master，Git 回你一句rejected，然后一堆 hint。它的本质逻辑其实很朴素：Git 在 push 之前会先检查远程分支的状态，如果远程分支上有一些提交是你本地没有的，为了不覆盖别人的工作，它会默认拒绝你。

2.1 non-fast-forward 到底是什么意思

要理解这个，得先知道 Git 的提交是条链。每条提交都记录着自己的上一个提交（父提交），一路往回串成历史。所谓 fast-forward（快进），就是你本地的历史是远程历史的"完美延续"——远程的最新提交正好是你本地某个提交的祖先，这时候 Git 只要把你的新提交接上去就行了，安全又省事。

反过来，如果远程有一个提交，本地没有它的血缘，你这条链和远程那条链已经岔开了，Git 就没法简单地"接上去"，它担心你把别人已经推上来的提交覆盖掉，于是拒绝。这就是non-fast-forward。想象一下两个人合作写文档：你基于昨天下午的版本做了修改，同事在同一时间也基于昨天下午的版本改了另一段并先传了上去，这时候你直接上传，就会把同事那段覆盖掉。Git 的拒绝是在保护他，不是跟你作对。

2.2 解法一：先拉后推，用 merge 保留两条历史

最稳妥、最不需要动脑的做法，就是先把你没同步的那部分远程提交拉下来，合并完再推。标准三步：

git pull origin master # 解决可能出现的冲突，git add 相关文件 git commit -m "merge remote master" git push origin master

git pull实际上等于git fetch加上一个合并动作。它把远程的提交下载下来，然后尝试和你的本地分支合并。如果你的改动和远程改动不在同一处，Git 会自动合并，顺顺当当。如果碰巧改了同一个文件的同一段，就会产生冲突，需要你手动打开文件，把<<<<<<<、=======、>>>>>>>之间的内容取舍好，git add标记为已解决，再提交。

注意：git pull后出现冲突时不要慌张地乱删标记符号，<<<<<<< HEAD到=======之间是你本地的版本，=======到>>>>>>>之间是远程的版本，你要做的是把它们改成你最终想要的代码，然后删掉这三行标记。

2.3 解法二：用 rebase 拉出一条干净的直线

merge 的缺点是会产生一个合并提交，历史看起来像两条线交汇，时间久了图表会很乱。如果你在意提交历史的整洁，可以用 rebase：

git pull --rebase origin master git push origin master

--rebase的意思是：先把远程的新提交拿下来，然后把你本地还没推的提交一个个"摘下来"，接到远程最新提交之后，等于把你的工作"挪"到了最新的起点上。好处是历史变成一条直线，没有多余的合并节点。代价是如果冲突较多，rebase 过程中可能需要你逐个提交去解决冲突，比 merge 稍微费神一点。

我个人的取舍是：个人项目、分支上只有自己提交，用--rebase保持干净；多人协作的公共分支，老老实实用 merge，因为 rebase 会改写提交的哈希值，对已经共享出去的历史动刀是有风险的。

2.4 强制推送不是不能用，但要认清代价

搜报错的时候，你一定会搜到git push -f这个"大力出奇迹"的招数。它能强行覆盖远程，把 rejected 直接消灭。但我把话放这儿：在共享分支上对已经推上去的提交用强制推送，几乎等于在团队里埋雷。

# 危险操作，仅限个人分支且确认无人依赖时使用 git push -f origin master

-f是--force的缩写，它跳过一切安全检查，把远程分支指针直接掰到你本地的位置。如果远程有别人提交的内容而你本地没有，那些提交就从分支历史上消失了，别人的工作直接丢。更安全的替代是--force-with-lease：

git push --force-with-lease origin master

它的含义是"只有当远程分支还是我上次拉取时的样子，才允许强制推"。万一这期间别人推了新东西，它会拒绝，从而避免误伤。如果你非要用强制手段，请至少换成这个。

2.5 顺带聊聊 .gitignore 和空目录的老问题

还有一类 rejected 是"冤枉"的，跟历史无关，而是文件被忽略或被跟踪的问题。有时候你想推的配置文件没有出现在git status里，是因为被.gitignore挡住了。检查一下：

git check-ignore -v config/local.ini

这条命令会告诉你到底是哪一行.gitignore规则忽略了它。反过来，如果你发现某个本该被忽略的文件已经被跟踪，需要先把它从索引里移除再提交：

git rm --cached config/local.ini git commit -m "remove tracked local config"

--cached的意思是从 Git 索引里删掉，但保留工作区里的实际文件，避免误删你辛苦写的东西。

3. 认证与权限类报错，账号密码那点事

第二大类是认证问题。典型表现是Authentication failed、fatal: could not read Username、remote: Permission denied、403。这类报错跟代码无关，纯粹是"你是谁、你有没有权限"没对上。这几年各大代码托管平台陆续取消了直接用账号密码推送的方式，改成令牌或密钥，导致很多老教程里的做法失效了，这里统一说清楚。

3.1 为什么密码明明没错还是认证失败

因为很多平台早就不支持用登录密码来做 Git 操作了。你输的是账号的登录密码，平台在 Git 这一侧要的是"访问令牌"（personal access token）。令牌是你自己生成的一串随机字符串，可以单独设置权限范围和有效期，泄露了也能随时吊销，比密码安全得多。

以常见的平台为例，你需要在账号设置的开发者选项里生成一个令牌，勾选仓库读写权限，然后把令牌当作"密码"来用。当你git push时弹出用户名和密码提示，用户名填账号，密码栏粘贴令牌。第一次成功后，系统一般会把凭据缓存起来，之后就不用反复输了。

注意：生成令牌时一定勾好仓库读取和写入权限，权限不足会报403，那种情况不是认证失败，而是认证通过了但没有操作权限，两者要分清楚。

3.2 把凭据缓存起来，别每次都手输

来回输令牌很烦，可以在本地保存。常见做法是配置凭据助手，让系统帮你记住：

# 让 Git 使用系统自带的凭据管理器 git config --global credential.helper manager

Windows 上装 Git 的时候通常会自带凭据管理器，macOS 上可以用osxkeychain。配置好之后，第一次输入会记住，之后自动带上。如果你在共享电脑上操作，记得别开启这项，或者用完清掉凭据，避免别人直接拿你的身份推代码。

还有一种更常见的"偷懒"写法，就是直接在远程地址里塞账号信息：

git clone https://username:token@github.com/yourname/yourrepo.git

这样确实省事，git remote -v里面也会带着账号。但我要提醒你，这么做有泄露风险：这个带凭据的地址会被写进.git/config文件，如果哪天你把整个项目目录打包分享，或者提交了配置文件，凭证就跟着飞出去了。更稳妥的做法是用凭据助手，或者改用 SSH。

3.3 改用 SSH 密钥，一劳永逸

如果你长期在同一个环境里开发，SSH 是最省心的方案。大致流程是：

# 1. 生成密钥对，一路回车即可 ssh-keygen -t ed25519 -C "your_email@example.com" # 2. 查看公钥内容并复制 cat ~/.ssh/id_ed25519.pub

把公钥内容粘贴到平台的 SSH 密钥设置里，然后把本地仓库的远程地址从 HTTPS 换成 SSH：

git remote set-url origin git@github.com:yourname/yourrepo.git

验证是否配对成功，可以跑一下：

ssh -T git@github.com

看到欢迎信息就说明认证打通了。之后你所有的 push、pull 都走密钥，不再需要输任何东西。这块值得一次性配好，后面能省下无数次折腾认证的时间。

实操心得：ssh-keygen生成密钥时，最后一步会问你设不设 passphrase（密码短语）。设了更安全，但每次用都要输；不设则方便但密钥文件本身就成了唯一凭证。我的建议是工作机可以设一个简短密码短语并配合本地的 ssh-agent 缓存，个人小机器图方便可以直接回车留空，前提是这台机器只有你用。

3.4 权限不足和仓库不存在的区分

同属"推不上去"，还有一种报错是Repository not found或403。前者可能是地址敲错了、仓库是私有的而你没有访问权，也可能是账号根本没被加入协作者列表。后者多半是令牌权限没给够。排查顺序是：先用git remote -v核对地址，再确认账号对这个仓库有没有写权限，最后检查令牌的权限勾选。三步走下来，认证类的报错基本都能收口。

4. 分支名与远程配置，master 和 main 的那些坑

git push origin master这条命令里有三个词，每一个都可能出问题：push是动作，错不了；origin是远程名，可能没配或叫别的名字；master是分支名，而现在很多平台新建仓库默认分支已经叫main了。这一节就是把这三个词挨个排查一遍。

4.1 src refspec 报错怎么处理

如果你看到的是<branch> does not match any或者src refspec master does not match any，翻译过来就是：你要推的本地分支不存在。最常见的原因是本地分支叫main，你却推master。先看看本地到底有哪些分支：

git branch

输出里前面带星号的就是当前分支。如果显示的是main，那你就该：

git push origin main

还有一种情况是全新的仓库，本地一次提交都还没有，这时候推任何分支都会报这个错。需要先完成第一次提交：

git add . git commit -m "first commit" git push origin main

4.2 master 与 main：改默认分支后的连锁反应

大概从几年前开始，主流平台新仓库的默认分支从历史悠久的master改成了main。这带来一串小麻烦：你从旧教程里学到的是推master，但本地 clone 下来的仓库默认就在main上；或者你本地还是master，远程却是main，两边对不上。

如果你确实想让本地分支改名对齐远程，可以这么做：

# 把本地当前分支改名为 main git branch -M main # 设置新分支跟踪远程 main 分支 git push -u origin main

-M是强制重命名（-m在目标分支已存在时会报错，-M则直接覆盖）。-u是--set-upstream的缩写，作用是把本地分支和远程分支关联起来，之后再推就不用每次都写origin main了，直接git push即可。

4.3 没有 origin？remote 配置的排查与修复

origin只是远程仓库的默认别名，它并不是什么魔法词。如果git remote -v跑出来一片空白，说明你压根没配远程地址。克隆下来的仓库会自动配好，但如果你是在本地git init建起来的仓库，就需要手动加：

git remote add origin https://github.com/yourname/yourrepo.git

反过来，如果远程名不叫origin，比如叫upstream或者某个自定义名字，那你推的时候就得用实际名字：

git push upstream master

修完地址可以用git remote -v再确认一遍。我强烈建议把这条命令加进你的肌肉记忆，它是排查一切 push 问题的第一步。

4.4 upstream 没设置的提示怎么消掉

还有一条提示很常见：fatal: The current branch master has no upstream branch。意思是你本地这个分支还不知道自己该对应远程哪个分支。解决就是给它设一个上游：

git push --set-upstream origin master

设置完之后，这个分支和远程分支就绑定好了，以后git status会告诉你"领先多少个提交、落后多少个提交"，git push、git pull也可以省掉参数直接用，体验顺滑很多。第一次推新分支时顺手加上-u，是个能长期受益的习惯。

5. 环境与工具链报错，Git 本身都没装好

前面聊的都是"Git 能用但推不上去"，这一类恰恰相反——Git 根本没就位，报错发生在一切动作之前。新手最容易被这类问题卡住，因为报错往往和 Git 本身无关，是环境没配好。

5.1 "无法识别 git 命令"的处理

Windows 上跑出'git' 不是内部或外部命令，也不是可运行的程序，或者在某些终端里看到exec: "git": executable file not found in %PATH%，这是典型的 Git 没安装或者没加进系统 PATH。先确认装没装：打开命令行敲git --version，如果没反应或报错，就是没装。

去官网下载对应系统的安装包，一路默认安装即可。安装时有个地方要注意，安装向导里会问你用哪个终端、怎么处理换行符，这些保持默认通常没问题，但如果你用 Visual Studio Code 的集成终端，建议勾选让它把 Git 加到 PATH 里。装完记得关掉终端重新开一个，让 PATH 生效。

5.2 系统差异带来的小摩擦

不同系统上 Git 的行为有细微差别，容易踩的小坑有这么几个。macOS 上第一次跑git可能会提示你安装命令行开发工具，跟着提示装完即可；没装开发工具时一些依赖命令也会缺失。另外 macOS 的 homebrew 偶尔会因为网络或权限报错，可以先用brew doctor看看它自己怎么说。

而在 Linux 上，通常通过包管理器安装，比如 Debian 系用apt install git，要注意权限不足时加上sudo。安装完同样是git --version验证。跨系统协作时，换行符（LF 与 CRLF）经常引发"整个文件都变了"的诡异 diff，可以配置一下：

# Windows 上提交时自动转为 LF，检出时保留原样 git config --global core.autocrlf input

注意：core.autocrlf这个配置一旦设错，可能让 Git 把整个文件的内容都标记成改动过的，看起来像是你改了几百行，其实只是换行符差异。团队里最好统一约定，别各设各的。

5.3 不在仓库目录里也会报错

fatal: not a git repository是另一条新手高频报错。它的意思是当前目录不是 Git 仓库。要么是你进错了文件夹，要么是项目 clone 没成功。先用pwd（Windows 上是cd）看看自己在哪，然后ls看一下有没有.git这个隐藏目录。如果目录里空空的，说明 clone 可能失败了，重新找一个网络稳定的时间再 clone 一次。

顺便说一句，clone 一个体积很大的仓库时，克隆本身慢或者中途断开是很常见的，可以先用浅克隆拉最近一次提交：

git clone --depth 1 https://github.com/yourname/yourrepo.git

--depth 1只拉最近一次提交，速度快很多，适合只是想看看代码、不需要完整历史的场景。需要完整历史时再git fetch --unshallow补全。

6. 一套顺手的常见 git 命令清单

前面花了大量篇幅讲报错，这一节把日常真正高频的命令整理成一张张清单。我按使用场景分组，标出哪些是我几乎每天都用的，方便你按需记忆，而不是一股脑全背下来。

6.1 提交与同步，日常用得最多

这里我特别想说git status。它是排查一切问题的起点，也是我按得最多的键。养成在每次add、commit、push之前先跑一遍的习惯，你会少吃很多"咦怎么没提交上"的亏。至于git log --oneline，加了这个参数后每条提交只显示一行，历史一目了然，比默认输出清爽太多。

6.2 分支操作，协作绕不开

分支是 Git 最强大的能力之一，但也是报错的高发区。常用命令整理如下：

git branch # 列出本地分支 git branch -a # 连远程分支一起列出 git checkout -b feature/x # 新建并切到新分支 git switch main # 切回主分支（新版命令） git merge feature/x # 把 feature/x 合并进当前分支 git branch -d feature/x # 删除已合并的分支

新版 Git 推荐用git switch和git restore替代老旧的git checkout，因为checkout一个命令干了太多件事，容易误操作。切分支用switch，撤销文件改动用restore，语义清晰，不容易切错。这个习惯值得尽早养成。

6.3 撤销与回退，救命的几招

写错了想撤回，是每个人都躲不过的场景。按"撤回的力度"从小到大排，是我推荐的记忆顺序：

# 只撤销工作区的改动，恢复成上次提交的样子 git restore file.txt # 把已暂存的改动退回工作区 git restore --staged file.txt # 撤销最近一次提交，但保留改动 git reset --soft HEAD~1 # 撤销最近一次提交，改动也一并丢弃（危险） git reset --hard HEAD~1 # 生成一条反向提交，安全地"撤销"已经推上去的提交 git revert <commit-id>

reset和revert的区别是很多人分不清的点。reset是直接把分支指针往回挪，历史被改写，适合同步前、没推出去的提交；revert是新增一条"反着做"的提交，历史保留完整，适合已经推上去、别人可能已经拉过的提交。共享分支上要撤销，永远优先考虑revert。

6.4 排查问题的几条法宝

出问题的时候，下面这几条能帮你快速看清现场：

git diff # 看还没暂存的改动 git diff --staged # 看已暂存的改动 git show <commit-id> # 看某次提交的具体内容 git reflog # 看所有引用的移动记录（找回误删的救命稻草） git blame file.txt # 看每一行是谁、哪次提交改的

git reflog我要重点夸一下。它记录了 HEAD 和分支指针的每一次移动，哪怕你用reset --hard把提交"删掉"了，也能在这里找到那条提交的哈希，然后git reset --hard <hash>把现场恢复回来。每次我以为代码丢了、心跳漏一拍的时候，都是 reflog 把我捞回来的。

7. 踩坑实录与常见问题速查表

讲了这么多原理和命令，最后这一节放一些实打实踩过的坑，以及一张遇到问题能直接查的表。经验这东西，往往是踩过才知道疼，我尽量把疼的地方提前告诉你。

7.1 常见报错速查表

这张表我建议你截图存着，绝大多数 push 报错都能在上面找到对应的处理方向，比盲搜快得多。

7.2 几条只有踩过才懂的实话

第一，别在出事的时候才去查配置。我见过好多人平时从不看git remote -v和git status，一出报错就慌。养成推送前扫一眼的习惯，能提前发现 remote 指向不对、分支不在预期上这类"无声的错误"。有一次我差点把测试分支推到了生产仓库，就是 push 前多看了一眼输出，侥幸躲过。这种习惯的成本几乎为零，收益却是实打实的。

第二，强制推送前，先在脑子里过一遍"这个分支还有没有别人用"。个人临时分支随便折腾，公共分支碰都别碰-f。真要用，也换成--force-with-lease。这条经验救过我无数次，也是我建议每个协作团队写进规范里的硬要求。

第三，冲突不是灾难，是 Git 在提醒你"这里有两个人在改同一处"。解决冲突的正确姿势是打开文件，理解两边的改动意图，合成一个逻辑正确的最终版本，而不是随手二选一。我发现很多新手遇到冲突就紧张地乱删，结果把同事的功能删掉了。其实只要冷静读一遍<<<<<<<标记之间的内容，冲突往往没那么可怕。

第四，命令行的历史记录是你的朋友。手滑输错命令、想找回上一条长命令时，按上箭头翻历史比重新敲快得多。配合git reflog，你以为丢掉的提交绝大多数都能找回来——这才是 Git 让人安心的底层设计，它不太容易让你真的"丢"东西。

第五，遇到实在搞不定的情况，最保险的做法是先把工作区备份一份。把整个项目目录复制到别的地方存着，然后你随便怎么折腾命令都不怕。这条看着笨，但在我刚学 Git、还不懂reflog的时候，这个笨办法救过我好几次。工具在变强，但"动手前先备份"这种朴素的习惯永远不会过时。