很多人觉得 Git 难，不是因为命令太多，而是常用操作和常见报错总会混在一起：刚开始提交就缺用户名，连上远程后又遇到 push 被拒、SSH 报错，真正出问题时反而不知道先查哪一步。本文按“先配好、再会用、最后避坑”的顺序整理 Git 的基础配置、日常命令、远程上传常见问题和推荐工作流，方便你在实际开发里快速定位问题，也能判断哪些操作可以直接用，哪些命令需要格外谨慎。

先把 Git 基础配置补齐

正式使用 Git 之前，建议先完成全局身份配置。这里看似只有几条命令，但它决定了你能否正常提交，以及新仓库默认采用什么分支名。

# 设置全局用户信息（必填，否则无法提交）
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱@example.com"

# 设置默认分支名（可选）
git config --global init.defaultBranch main

# 查看配置
git config --list

user.name 和 user.email 属于提交必备信息，没有它们时，Git 在执行 commit 时会直接报错。init.defaultBranch main 虽然是可选项，但如果你希望新仓库默认使用 main，最好一开始就设好，后面可以少一次分支名调整。

日常最常用的 Git 命令

如果只看日常开发，Git 的高频操作其实很集中，核心就是初始化、查看状态、提交、同步远程和处理分支。下面这份速查表适合直接收藏。

如果你刚上手，建议先记住一条最短路径：git status 看状态，git add 放入暂存区，git commit -m 生成提交，git push origin 推到远程。大多数操作都可以围绕这条主线展开。

上传 GitHub / Gitee 时最常见的 7 个坑

真正让人卡住的，往往不是本地提交，而是和远程仓库打交道的时候。下面这些问题覆盖了新手和老手最常遇到的场景。

1. 远程仓库已有内容，本地推送被拒

问题：git push 被拒绝，提示 failed to push some refs

原因：远程仓库初始化时已经创建了 README、LICENSE 等文件，而本地历史与之不一致。

解决：

# 方法一：先拉取合并（推荐）
git pull origin main --allow-unrelated-histories
git push origin main

# 方法二：强制推送（ 会覆盖远程）
git push -u origin main -f

优先使用方法一，它能保留远程已有内容。-f 强制推送虽然省事，但本质上是直接覆盖远程历史，只有在你明确知道后果时才适合使用。

2. 每次 push 都要求输入用户名密码

问题：每次执行 push 都要重复输入账号密码。

解决：配置凭据缓存。

# 缓存 15 分钟
git config --global credential.helper cache

# 永久存储（Windows）
git config --global credential.helper store

如果只是个人设备，启用缓存能明显减少重复输入的麻烦；但在公用电脑上，永久存储凭据要特别谨慎，避免账号被他人直接复用。

3. SSH 推送报错 Permission denied

问题：使用 SSH 地址推送时出现权限错误。

解决：

# 1. 生成 SSH 密钥
ssh-keygen -t ed25519 -C "你的邮箱@example.com"

# 2. 查看公钥
cat ~/.ssh/id_ed25519.pub

# 3. 将公钥添加到 GitHub/Gitee 的 SSH Keys 设置中

# 4. 测试连接
# GitHub
ssh -T git@github.com
# Gitee
ssh -T git@gitee.com

SSH 的优势是配置完成后无需反复输入密码。如果仍然提示 Permission denied，通常要重点检查两件事：一是公钥是否真的添加到了正确账号下，二是本地使用的密钥文件路径是否匹配。

4. 文件过大，远程拒绝接收

问题：

remote: error: File xxx is 100.00 MB; this exceeds the file size limit

解决：

# 安装 Git LFS
git lfs install

# 追踪大文件
git lfs track "*.psd"
git lfs track "*.zip"

# 然后正常 add/commit/push

Git 默认不适合直接管理大文件，超过 100MB 就会被平台限制。像设计源文件、压缩包这类资源，更适合尽早纳入 Git LFS，否则后面再迁移会更麻烦。

5. 误提交了密码或密钥等敏感信息

问题：密码、密钥等内容已经进入仓库历史。

紧急处理：

# 1. 立即修改泄露的密码/密钥！

# 2. 从 Git 历史中移除文件
git filter-branch --force --index-filter 
  "git rm --cached --ignore-unmatch 敏感文件路径" 
  --prune-empty --tag-name-filter cat -- --all

# 3. 推送清理后的历史
git push origin main --force --all

# 4. 添加 .gitignore 防止再次提交
echo "敏感文件名" >> .gitignore

这里最关键的一点不是清理历史，而是先让泄露出去的密码、令牌或密钥立即失效。因为一旦仓库被公开访问，哪怕你后面删除了记录，也不能假设内容没有被别人下载过。

6. push 时发现自己处于 detached HEAD

问题：当前不在任何分支上，导致无法正常推送。

解决：

# 切换回主分支
git checkout main
# 或创建新分支保存当前修改
git checkout -b new-branch

这个状态通常发生在你直接 checkout 到某个提交哈希之后。处理思路很简单：如果只是看历史，切回正常分支；如果当前改动需要保留，就先新建分支再继续工作。

7. GitHub 访问慢或连接不稳定

解决：

# 使用 GitHub 镜像加速（临时）
git config --global url."https://ghproxy.com/https://github.com/".insteadOf "https://github.com/"

# 或修改 hosts 文件绑定 IP

# Gitee 一般无需加速

这类问题在国内环境里并不少见，尤其是拉取依赖较多、文件较大的仓库时。镜像配置适合临时使用，长期看可以根据项目协作范围选择 Gitee 或自建 Git 服务。

一套更稳妥的日常工作流

如果你不想频繁踩坑，最有效的办法不是记住所有报错，而是使用一套更稳定的协作流程。下面这套做法适合多数个人项目和团队开发。

# 1. 克隆远程仓库
git clone git@github.com:用户名/仓库名.git

# 2. 创建功能分支
git checkout -b feature/my-new-feature

# 3. 开发并提交
git add .
git commit -m "feat: 添加新功能描述"

# 4. 推送分支到远程
git push -u origin feature/my-new-feature

# 5. 在 GitHub/Gitee 上创建 Pull Request / Merge Request

这套流程最核心的规则只有一条：不要直接在 main 分支上开发。通过功能分支提交改动，再进入 Pull Request 或 Merge Request 流程，既方便审查，也能在出现问题时更容易回滚。

提交信息怎么写更清楚

很多团队协作混乱，不是代码写得差，而是提交记录无法快速说明“这次改了什么”。如果没有额外规范，可以直接采用社区里最常见的一套提交前缀。

feat:     新功能
fix:      修复 bug
docs:     文档更新
style:    代码格式（不影响逻辑）
refactor: 重构
test:     测试相关
chore:    构建/工具变动

示例：

git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复首页加载超时问题"

这套格式的好处很直接：当你回头看 git log --oneline 时，可以很快区分这是新功能、问题修复，还是文档和工具链变更。项目越大，这种可读性越有价值。

结语：先建立习惯，再记复杂命令

对于大多数开发者来说，Git 真正常用的部分并不复杂，难点主要集中在远程协作和错误处理上。先把基础配置设好，按固定工作流使用分支和提交规范，再把几类高频报错的处理方式记熟，日常使用 Git 基本就不会再手忙脚乱。