小白入门：GitHub 远程仓库使用全攻略

一、Git 核心概念

1. 三个工作区域

• 工作区（Working Directory）：实际编辑文件的地方。

• 暂存区（Staging Area）：准备提交的文件集合（使用git add操作）。

• 本地仓库（Local Repository）：已提交的内容（通过git commit提交）。

• 远程仓库（Remote Repository）：如 GitHub 等托管平台上的仓库。

2. 分支

在 Git 版本控制系统中，分支（Branch） 是指从主分支（如main或master）分离出来的独立开发线路，每个分支都有独立的提交历史，允许开发者并行开展不同的开发任务。例如，当开发新功能、修复特定 Bug 或进行实验性开发时，都可以创建独立分支。

分支的核心优势在于代码隔离与并行开发：

• 功能隔离：以main（或master）作为默认分支，新功能开发可在独立分支上进行，避免直接修改主线代码。例如，开发电商网站的「直播带货」功能时，可创建feature/live-selling分支，确保核心购物流程（main分支）不受影响。

• 版本管理：不同分支可对应不同版本迭代，便于团队分工协作。如dev分支用于日常开发，release分支用于预发布测试，hotfix分支用于紧急修复线上问题。

• 风险可控：若分支开发中出现错误，可随时丢弃或回滚，不会破坏主分支稳定性，降低对整个项目的影响。

二、GitHub 远程仓库搭建步骤

1. 注册 GitHub 账号访问 GitHub 官网 注册账号。

1. 创建新仓库

• • 点击右上角 New repository → 填写仓库名（如 LM_Steer）→ 创建。

1. 本地环境配置

• • 安装 Git：下载地址

• • 配置用户名和邮箱：

git config --global user.name "Your Name"

git config --global user.email "[e-mail]"

三、Git 基本操作

1. 本地仓库初始化

git init # 在项目目录初始化Git仓库

1. 提交文件到本地仓库

git add . # 添加所有文件到暂存区

git commit -m "初始提交" # 提交到本地仓库

1. 关联远程仓库

git remote add origin [e-mail]:用户名/仓库名.git # 添加远程仓库

1. 推送至远程仓库

git push -u origin main # 首次推送需指定上游分支

1. 拉取远程更新

git pull origin main # 拉取并合并远程更新

1. 分支 track（追踪分支）介绍

在 GitHub 协作开发中，追踪分支是连接本地分支与远程分支的桥梁。它具有两大核心优势：

1. 自动同步更新：避免手动频繁拉取代码，执行git pull或git push命令时，本地分支会自动与追踪的远程分支交互。

1. 明确关联关系：清晰展示本地与远程分支的对应关系，便于团队快速掌握代码同步状态。

创建方式

追踪分支的创建分为两种场景：

• 新建分支时直接追踪：使用命令 git checkout -b feature/xxx origin/feature/xxx，在创建本地feature/xxx分支的同时，直接设置为追踪远程origin/feature/xxx分支。

• 已有分支设置追踪：通过命令 git branch --set-upstream-to=origin/xxx local_xxx，将现有本地分支local_xxx关联至远程origin/xxx分支。

1. 如何查看并删除远程关联的仓库：

• • 查看远程仓库：在本地仓库的命令行中，输入 git remote -v 命令，即可列出所有已关联的远程仓库及其对应的 URL 地址。例如，输出可能类似 origin https://github.com/yourusername/yourrepository.git (fetch) 和 origin https://github.com/yourusername/yourrepository.git (push)，其中 origin 是默认的远程仓库别名。

• • 删除远程仓库：若要删除某个远程仓库关联，使用 git remote remove <远程仓库别名> 命令，如 git remote remove origin 即可删除别名为 origin 的远程仓库关联。也可以使用 git remote rm <远程仓库别名> 达到同样效果 。

四、典型问题与解决方案

1. 问题 1：认证失败（Authentication failed）

• • 原因：用户名 / 密码错误，或 GitHub 已禁用密码认证。

• • 解决方案：

• • • 生成 SSH 密钥：打开终端（Windows 用户可使用 Git Bash），输入ssh-keygen -t ed25519 -C "[e-mail]"，其中邮箱地址替换为你的 GitHub 注册邮箱，按三次回车键完成密钥生成。密钥文件默认存储在用户主目录的.ssh文件夹下。注意添加环境变量，否则可能无法使用ssh-keygen

• • • 添加公钥到 GitHub：找到生成的公钥文件（后缀为.pub），使用文本编辑器打开，复制全部内容。登录 GitHub，进入Settings -> SSH and GPG keys，点击New SSH key，粘贴公钥内容并添加。

• • • 测试 SSH 连接：在终端输入ssh -T [e-mail]，首次连接会提示确认，输入yes。若出现Hi [你的用户名]! You've successfully authenticated, but GitHub does not provide shell access.，则表示 SSH 密钥配置成功，后续可通过 SSH 协议安全高效地操作远程仓库 。

ssh-keygen -t ed25519 -C "[e-mail]" # 生成密钥

# 将公钥（~/.ssh/id_ed25519.pub）添加到GitHub

• • • 使用个人访问令牌（PAT）：GitHub Settings → Developer settings → Personal access tokens → 生成令牌，推送时用令牌替代密码。

1. 问题 2：无法使用 ssh-keygen 命令

• • 原因：Windows 未安装 OpenSSH 客户端。

• • 解决方案：

# 以管理员身份运行PowerShell

Add-WindowsCapability -Online -Name OpenSSH.Client~0.0.1.0

或安装 Git for Windows。

1. 问题 3：推送被拒绝（non-fast-forward）

• • 原因：远程分支有新提交，本地历史落后。

• • 解决方案：

git pull origin 分支名 # 先拉取合并

# 若有冲突，解决后再推送

1. 问题 4：合并无关历史（refusing to merge unrelated histories）

• • 原因：本地与远程仓库无共同提交历史。

• • 解决方案：

git pull origin 分支名 --allow-unrelated-histories # 强制合并

1. 问题 5：修改 .gitignore 不生效

• • 原因：已跟踪的文件不受新规则影响。

• • 解决方案：

git rm -r --cached . # 清除缓存

git add . # 重新添加

git commit -m "更新.gitignore

1. 问题6：使用push命令时，它会推送本地仓库中所有未推送的commit。若不想将所有修改一次性推送，避免影响主分支稳定性，建议新建一个分支进行操作。具体可通过git branch new_branch_name创建新分支，再使用git checkout new_branch_name切换到新分支，在该分支上进行开发与提交，最后按需将分支合并到主分支。

五、分支管理

1. 查看分支

git branch # 查看本地分支

git branch -r # 查看远程分支

git branch -a # 查看所有分支

1. 创建与切换分支

git checkout -b 新分支名 # 创建并切换到新分支

1. 合并分支

git checkout main # 切换到目标分支

git merge 源分支名 # 合并源分支到当前分支

六、最佳实践

1. 保持 main 分支稳定：仅合并经过测试的代码。

1. 使用分支开发新功能：避免影响主线。

1. 定期同步远程分支：

git fetch origin # 更新远程分支引用

1. 通过 Pull Request 合并代码：便于代码审查。

七、常见命令速查表

操作	命令
初始化仓库	git init
添加文件到暂存区	git add <文件>
提交到本地仓库	git commit -m "描述"
查看状态	git status
查看提交历史	git log
拉取远程更新	git pull origin 分支名
推送至远程	git push origin 分支名
创建并切换分支	git checkout -b 分支名
切换分支	git checkout 分支名
合并分支	git merge 分支名
删除分支	git branch -d 分支名

通过以上步骤，你可以完成 GitHub 远程仓库的搭建与基本操作，解决常见问题，并建立规范的开发流程。