企业官网建设流程全解析

刚开始用 Git 的时候，我的流程特别粗糙：git add .，然后git commit -m "update"，再git push。看起来什么都会，但一旦要回退版本、追查某一行代码是哪个提交引入的，历史记录完全帮不上忙——每个提交都塞满了十几个文件的改动，时间一长根本分不清谁是谁。

后来真正理解了暂存区（Staging Area / Index），我才发现自己浪费了大把可以省掉的排查时间。暂存区是 Git 里最有特色、也最容易被新手忽略的设计。它处在工作区和本地仓库之间，专门负责帮你“挑选”哪些改动进入下一次提交。这篇内容就围绕“Git 添加文件到暂存区”这件事展开，讲清楚git add的完整用法、常见坑、以及如何配合分支合并和代码审查用出真正舒服的工作流。适合刚入门的同学，也适合已经用了一阵子、想改善提交质量的人。

1. 先搞清楚暂存区到底是怎么一回事

1.1 Git 的三个区域，以及一张“购物车”类比

很多人把 Git 想象成一个简单的“文件版本保存器”，其实它内部有完整的生命周期。你正在编辑器里修改的文件，处于工作区（Working Directory）；执行git add后，文件内容被登记到暂存区；再执行git commit，暂存区里的内容才会固化成一次提交记录，进入本地仓库。代码的流动路径是：

工作区 -- git add --> 暂存区 -- git commit --> 本地仓库

如果拿超市购物来类比就很好理解了：工作区是超市的货架，暂存区是购物车，本地仓库是付款后带回的家。货架上的东西很多，你不可能全买，得先往购物车里挑。挑的过程中还能犹豫一下，把不想要的放回货架，最后到收银台结账。git commit就是那个“结账”动作。没有购物车，就意味着你必须一次性买下所有商品，不能挑选，也不能组合。暂存区解决的正是这个“先挑一挑再付款”的问题。

这个类比还能解释一个高频疑惑：为什么git add后改了文件，git commit出来的却不是最新内容？因为你购物车里的商品是“放进购物车那一刻”的状态，不是货架上当下的状态。想要让购物车里的东西保持最新，就得再执行一次git add，把新版本重新放进暂存区。记住这个心智模型，后面很多操作都会变得顺理成章。

1.2 为什么 Git 要设计暂存区

直接说结论：暂存区把“什么时候提交”和“提交什么内容”这两个决定彻底分开。实际开发里，你不可能一次只改一个文件。经常是修了一个 bug、加了一个小功能，还顺手调了格式化配置，全搅在一起。如果没有暂存区，Git 要么逼你把所有改动作为一条提交打出去，要么让你自己手动备份文件再还原，两样都极其痛苦。

有了暂存区，你可以只挑和当前需求相关的文件，甚至是一个文件里的几行代码加入暂存区。这样每个提交都是一个“完整的逻辑单元”，提交信息也能写得清晰明确。比如“修复登录接口空指针”这个提交里，就只有登录相关的几个文件和改动，不会顺手带进来一个无关的样式调整。

从团队协作的角度看，暂存区的价值更明显。代码审查时，评审人通常希望看到一条一条逻辑清晰的提交，而不是一个 2000 行 diff 的大杂烩。你提交得越精确，评审的负担越轻，被提出问题的概率也越低。这个习惯直接决定了你的 Git 历史能不能成为项目资产，而不是一团乱麻。

2. git add 的完整使用手册

2.1 基本语法与常用参数

“把文件加入暂存区”听上去简单，但git add的参数比你想象中丰富。我先列一份速查表，再逐个讲解容易混淆的点。

看到“git add .”和“git add -A”，很多教程都说等价。严格说，在仓库子目录里有区别：git add .只处理当前目录往下的范围，git add -A的视角是整个工作树。假设你人在src子目录里，根目录下还有一个被删除的脚本文件，执行git add .不会暂存这个删除，但git add -A会。多数习惯在根目录操作的人差异不大，但如果你想用命令精确控制范围，这点必须分清楚。

2.2 不同场景下的添加策略

场景不同，add 的用法完全不同。我个人把日常场景分成三类。

第一类，个人项目或实验代码。这类项目没有严格的评审流程，怎么快怎么来。一个功能写完，直接git add -A，把所有改动一次性暂存，提交即可。节省时间是第一目标。

第二类，团队项目或开源贡献。这里就不能偷懒了。一次改动尽量对应一个主题，提交信息要能说明白“为什么改”。我通常先git status --short看有哪些文件被改动，然后逐个git add <file>挑选。如果同一个文件里既有功能改动又有调试残留，就用git add -p精确暂存指定代码块。这样看起来多一点工作量，但后续 git blame、git log 排查问题时，能省下成倍的时间。

第三类，清理场景。删了一堆文件但忘了先用git rm，这时git add -u很实用，它只处理已经被 Git 跟踪过、当前发生删除或修改的文件，不会把新出现的临时文件卷进来。配合 .gitignore 规则，可以很干净地完成“删除并提交”这个动作。

2.3 撤销暂存，别用错命令

暂存之后后悔，是所有人都会遇到的日常。在 Git 2.23 版本之后，最推荐的做法是：

git restore --staged <file>

这条命令把文件从暂存区退回到工作区，但保留你工作区里的实际改动内容。老一点的教程里常见的是：

git reset HEAD <file>

效果基本等价，新手看到 “reset” 会有“是不是会把代码删掉”的恐惧，所以restore的语义更友好。官方文档也建议新项目尽量基于新命令操作。

容易搞混的是git rm --cached <file>。这条命令不是“撤销暂存”，而是“停止跟踪文件”。它会把文件从 Git 索引里移除，但保留本地文件。使用场景通常是：某个文件已经被 Git 跟踪，你想把它加进 .gitignore，以后不再提交它。此时必须先git rm --cached，再写 .gitignore。如果你只是想撤销一次误添加，用了这条命令，文件会在下一次提交时被从仓库中移除，后果完全不同。我见过几个同事在这里踩坑，所以特意提醒：看清需求再选命令。

2.4 别混淆的几组命令

“提交”和“暂存”之间的边界很容易模糊，我再用一组对比说明。

git commit只提交暂存区里的内容。工作区里没有 add 的改动，commit 一律不负责。

git commit -a是“自动暂存已跟踪文件的修改和删除并提交”的快捷方式。它对你手动新建的未跟踪文件无效，而且只要你的暂存区里有内容，它会一起打包提交，没法精细选择。

git restore --staged只针对暂存区，把索引恢复成 HEAD 版本的状态，不动工作区。它不会修改文件内容。

git rm --cached是直接从索引中删掉文件的记录，下一次提交后该文件不再被跟踪。

把这几条放在一起记忆，遇到“为什么我 commit 了但没带上新文件”“为什么文件没了”“为什么还在跟踪”时，就能快速定位问题所在。

3. 实战演练：从安装到第一次提交

3.1 环境准备：Git 安装与基础配置

既然热词里有“git安装”“git安装及配置教程”，我把环境准备也带过一遍。Git 的安装其实不难。

Windows 上直接去 Git 官网下载安装包，安装过程中保持默认选项即可；macOS 可以用brew install git；Linux 根据发行版选择apt install git或yum install git。装完先验证：

git --version

看到版本号后，一定要做两个基础配置，否则以后提交时要么报错，要么提交作者信息为空：

git config --global user.name "Your Name" git config --global user.email "you@example.com"

这里 user.name 和 user.email 会写进每一笔提交记录。Email 不一定要真实邮箱，但如果配合代码托管平台使用，最好用平台绑定的邮箱，否则贡献统计对不上。配好后用git config --list检查，看到两项已存在就说明环境就绪。

3.2 初始化仓库并添加第一个文件

现在开始动手。假设我创建一个my-blog目录，想用 Git 管理它：

mkdir my-blog cd my-blog git init

初始化完成后，仓库还是空的。新建一个README.md，写上一行“这是我的博客项目”。接着就是本文的核心操作：

git status git add README.md git status

第一次git status，你会看到 README.md 出现在 Untracked files 里，意思是 Git 知道有这个文件存在，但还没有纳入版本管理。执行git add README.md后，再看git status，文件会进入 Changes to be committed 区域。这就说明它已经被登记到暂存区了。

如果想看到暂存区里的具体内容，而不是只看状态，可以用：

git diff --cached

这个命令对比的是“暂存区的内容”和“当前 HEAD 指向的提交内容”。在没有任何提交的新仓库里，它会把 README.md 整个文件以新增方式展示出来。养成提交前先看git diff --cached的习惯，能挡住大量“提交了错误内容”的低级失误。

3.3 修改文件后，为什么必须再次 add

场景继续：我把 README.md 里的“我的博客项目”改成了“我的技术博客发布系统”，然后直接git status。这时会看到两行信息：

Changes to be committed: new file: README.md Changes not staged for commit: modified: README.md

第一行说明暂存区里还有最初 add 时的旧版本，第二行说明工作区现在的最新修改还没进入暂存区。这正好验证了 1.1 节里那个“购物车”类比：购物车里的商品是放进去那一刻的状态，货架上的东西后来变了，不会自动同步进购物车。

要让提交带上最新内容，必须再次执行：

git add README.md

然后git diff --cached再看，显示的才是最新版本。这个“存量”和“增量”的关系，是初学者最容易栽跟头的地方。我的建议非常直接：把“修改后重新 add”当成默认操作，不要以为 commit 会自动带走工作区里的全部变化。

3.4 提交并推送：完整链路

暂存区准备完毕，提交就干净利落：

git commit -m "初始化项目，添加 README.md"

如果只想快速提交已跟踪文件的修改，可以写：

git commit -am "更新 README 描述"

-a会自动暂存所有已跟踪文件的修改和删除，然后提交。但注意，它对未跟踪的新文件无效。首次添加的新文件，必须先git add。

提交完成后，关联远程仓库并推送：

git remote add origin git@github.com:username/my-blog.git git push -u origin main

如果远程平台用 SSH 方式连接，并且本地没有配置过密钥，这里大概率会遇到“SSH 认证失败”。这个问题很常见，我放在下一节详细说。

4. 避坑：常见问题与排查实录

4.1 误添加了不想提交的文件

最典型的情况是，一路git add .把node_modules、.idea、target目录和一堆 log 文件全加进了暂存区。发现得越早，处理越轻松。

先用git status看全貌，再用git restore --staged <file>把误加的文件退回工作区。例如：

git restore --staged node_modules/.cache

如果只是临时退掉，这样已经结束。如果以后也不想把这类文件放进版本管理，那就要再加一道防线：写 .gitignore。

echo "node_modules/" >> .gitignore echo "*.log" >> .gitignore git add .gitignore git commit -m "添加忽略规则"

这里有个坑：.gitignore 只对尚未被跟踪的文件生效。如果某个文件已经被 Git 跟踪了，你即使把它写进 .gitignore，后续修改时它依然会被提示。正确做法是先停止跟踪：

git rm --cached <file>

把该文件从 Git 索引中移除，提交一次后，再把它加入 .gitignore，此后它就不会再进入提交记录，同时本地文件还会保留。这个操作组合我用了很多次，每次都能帮团队避免“秘密文件被提交进仓库”的事故。

4.2 换行符与文件权限引发的“假修改”

有一种情况很迷惑：刚从远程拉完代码，什么都没改，git status却提示一大票文件 modified。这时候十有八九是换行符问题。

Windows 上文本文件默认使用回车换行（CRLF），而 Linux/macOS 使用换行（LF）。Git 在检出文件时，会根据配置决定是否自动转换。一旦配置不一致，Git 就会认为文件内容整个发生了变化。最简单的处理方式：

git config --global core.autocrlf true # Windows git config --global core.autocrlf input # macOS/Linux

Windows 团队建议true，提交时把 CRLF 转成 LF，检出时再转回 CRLF。macOS/Linux 建议input，只在提交时把 CRLF 转成 LF。但这只是通用做法，项目级更可靠的是在仓库根目录放.gitattributes文件，按文件类型显式声明行尾规则，避免不同开发者配置不同导致互相干扰。

还有一类假修改来自文件权限。脚本文件被执行权限变化后，Git 会显示 “mode changed”。如果你的项目不需要精确管理执行权限，可以关掉：

git config core.fileMode false

这个配置只对当前仓库生效，不会影响其他项目。改完之后，git status通常会恢复安静。

4.3 SSH 认证失败与远程推送受阻

如果你用的是 SSH 方式连接远程仓库，执行git push时看到Permission denied (publickey)或类似的认证失败，通常不是暂存区的问题，而是本地密钥和远程平台没配对。排查思路我按顺序整理如下：

第一步，确认远程地址是不是 SSH 格式：

git remote -v

如果看到的是https://github.com/...，那你应该使用 HTTPS 方式认证，或者把远程地址改成 SSH 格式：

git remote set-url origin git@github.com:username/my-blog.git

第二步，确认本地有没有密钥。通常用户目录的.ssh文件夹下会看到id_ed25519和id_ed25519.pub。没有就生成一对：

ssh-keygen -t ed25519 -C "you@example.com"

一路回车，生成完毕后，把id_ed25519.pub里的内容复制到代码托管平台的 SSH Keys 设置页面。第三步，测试连接：

ssh -T git@github.com

如果返回欢迎信息，说明本地到远程的加密通道已经打通。最后再检查一下当前用户是否有目标仓库的写权限。这套流程能覆盖绝大多数 SSH 认证失败场景。大致理解成“本地有把锁，远程有把钥匙，两边对上了才能推代码”就好。

4.4 用 git status --short 快速判断状态

完整git status输出很长，真正干活的时候我更推荐短格式：

git status --short

它的输出每一行左边第一位表示暂存区状态，第二位表示工作区状态。例如：

M README.md A main.go ?? todo.txt

“ A”表示README.md在工作区被修改，但还没 add；“A ”表示main.go已经在暂存区；“?? ”表示todo.txt尚未被 Git 跟踪。掌握这个格式后，一眼就能看清当前项目的整体阶段。再配合git diff查看未暂存改动，git diff --cached查看已暂存改动，你对整个仓库的把控会立刻上一个台阶。

5. 进阶：暂存区与分支合并的配合

5.1 合并冲突时，git add 是“标记已解决”的动作

热词里有“git分支合并”，这里必须讲讲暂存区在合并中扮演的角色。一般执行git merge feature时，Git 会自动把合并结果放到暂存区，最后你只要git commit即可。一切顺利还好，一旦出现冲突，状态就不同于平常。

冲突发生后，git status会显示冲突文件处于 “Unmerged paths”。打开文件，你会看到<<<<<<<、=======、>>>>>>>这样的冲突标记。解决方式就是编辑文件，留下你真正需要的代码，删掉那些冲突标记，然后执行：

git add conflicted_file

在冲突场景下，这个git add的含义和日常完全不一样。它不是在“新增内容”，而是向 Git 确认“这个文件的冲突已经处理完毕，现在可以记入暂存区，允许我完成合并”。当所有冲突文件都执行了git add后，git status会变成 “All conflicts fixed but you are still merging”，此时就可以：

git commit -m "合并 feature 分支并解决冲突"

很多新人因为平时理解“add = 把修改放进去准备提交”，到了合并冲突时反而不敢执行 add，生怕提交了半成品。实际上，不执行这个命令，Git 永远不知道你已经完成冲突解决，整个合并会一直卡在中间状态。所以请把“合并场景下的 add 是一种确认动作”这个观念刻在脑子里。

5.2 合并时能对暂存区做哪些精细操作

有些团队要求合并提交必须干净，不想把某些合并产生的文件一并提交。理论上，你可以在合并完成后执行git restore --staged <file>把某个文件移出暂存区，再git commit剩下内容。但这个操作打破了合并提交“包含所有解决结果”的完整性，后续排查时容易留下断档。除非你对 Git 内部机制非常清楚，否则我不建议在合并时玩这种“手术刀式”操作。更稳妥的做法是合并先正常提交，如果发现某个文件引入的问题，再用单独的一次修复提交处理。

如果你需要在分支之间切换，但手头工作还没到提交状态，git stash是暂存区最好的搭档：

git stash push -m "临时保存：正在做用户列表功能" git checkout feature-b # 解决完紧急问题后 git checkout - git stash pop

它把暂存区和未暂存的改动一起打包，暂存到一个临时区域，等切换回来时再恢复。理解了“暂存区是一份快照”之后，你就能明白为什么要这么做：分支切换要求工作区相对干净，否则 Git 害怕把当前分支的改动带到另一个分支去。

5.3 分支切换前，处理暂存区的完整方案

除了git stash，分支切换前还有一个更常见的方案：直接提交。如果你的改动是完整的、可提交的状态，直接git add+git commit再切分支，是最干净的选择。

但有时候你只是改了半截，提交会破坏当前分支的稳定性，此时再用 stash。还有第三种情况：你只想把一部分改动带走。那就git add -p挑选要带走的代码块，然后git stash push把剩下部分藏起来，切分支时把挑选出来的那部分提交。这种做法虽然绕一点，但对于同时推进多个需求的人来说，每天都用得上。

6. 我个人用暂存区的工作流心得

6.1 从“一股脑提交”到“按逻辑提交”

我最初用 Git 也是图快，一个提交塞几十个文件，提交信息写“update”。直到有一次要回退一个功能，结果把另一个功能里的修复也一起回退了，才下定决心改变。

现在我的标准流程是：代码先在工作区写完，不急着 add。打开git diff自己看一遍，确认没有调试代码和无关改动，再用git add -p按逻辑片段加入暂存区。写提交信息时，尽量一句话说明“做了什么、为什么”。比如“修复注册接口空指针异常”而不是“fix bug”。这个习惯一开始会拖慢速度，但坚持两三周后，你会发现自己追溯历史的速度大幅提升，几乎不需要靠记忆去猜。

6.2 提交前的最后检查清单

在git commit前，我有一套不到 30 秒的检查流程。第一步，git status --short看整体状态，确认要提交的文件确实在暂存区。第二步，git diff --cached逐行看暂存区内容，重点检查有没有不小心放进去的密钥、日志、生成文件。第三步，确认 .gitignore 已经把常见产物目录覆盖住。

这三步做完，我才会写提交信息。如果检查过程中发现有文件不该进暂存区，就立刻用git restore --staged撤回，绝不抱着“先提交，后面再改”的心态。因为 Git 提交一旦进入历史，想彻底改写需要动用 rebase 等重操作，成本远比提前一次撤销高得多。暂存区是我和失误之间最重要的闸门，每次多花三十秒，就能避免后续几十分钟的返工。

6.3 一个小技巧：让 git add 更有把握

有时git add .会带来意外惊喜，比如把本不该提交的target、.idea目录卷进来。我习惯先预演：

git add --dry-run .

这条命令会把将要加入暂存区的文件列表打出来，但不会真的修改暂存区。看到列表里有不该出现的文件，我会先处理 .gitignore，再重新执行 add。这个操作在大规模重构时尤其管用，因为在文件很多的情况下，单靠肉眼很难注意到漏网之鱼。

为了减少敲击，我还用别名简化：

git config --global alias.stage "add --dry-run" git stage .

本质上，git add只是 Git 入门的第一小步，但它背后代表的是“精确控制每一次提交内容”的工作方式。把暂存区用明白了，提交历史会变得清爽、可审计、可回溯；反过来，一个混乱的暂存区习惯，会在后续分支合并、代码评审、问题排查中反复制造障碍。我自己的实践中，最值钱的经验就是：宁可多花十秒钟挑选要 add 的文件，也不要让一次随意的大批量git add .毁掉一个本来该清晰的提交历史。