GitHub 仓库上传、更新与维护指南

GitHub 仓库管理完整教程

本教程覆盖 Git 安装配置、SSH 密钥设置、仓库创建、项目上传及后续维护的完整流程。

一、准备工作

1. 注册 GitHub 账号

1. 打开浏览器，访问 GitHub 官网。
2. 点击'Sign up'或'注册'，按提示输入邮箱、用户名和密码，完成验证。
3. 登录后进入个人主页，即可进行后续操作。

二、安装并配置 Git

1. 在不同操作系统上安装 Git

• Windows：

  1. 搜索'Git Windows 安装'并找到官网下载页面。
  2. 下载 .exe 安装包，双击运行，保持默认设置完成安装。

• macOS：

  • 推荐通过 Homebrew 安装。执行：

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    brew install git
    

  • 或直接下载 macOS 安装包按提示安装。

• Linux（以 Ubuntu 为例）： 打开终端执行：

  sudo apt update
  sudo apt install git -y
  

安装完成后，在终端输入以下命令检查版本：

git --version

若输出类似 git version 2.x.x，说明安装成功。

2. 全局配置 Git 用户信息

依次执行以下命令配置提交者信息：

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱@example.com"

• user.name：填写 GitHub 注册的用户名或昵称。
• user.email：填写与 GitHub 账号绑定的邮箱地址。

配置完毕后，可用以下命令检查：

git config --global --list

三、配置 SSH 密钥（推荐）

使用 SSH 方式推送代码可避免每次输入密码。

1. 生成 SSH 密钥对

执行以下命令生成密钥（一路回车即可）：

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

默认生成 .ssh/id_ed25519（私钥）和 .ssh/id_ed25519.pub（公钥）。 查看公钥内容：

cat ~/.ssh/id_ed25519.pub

复制输出的字符串（以 ssh-ed25519 开头）。

2. 将 SSH 公钥添加到 GitHub

1. 登录 GitHub，点击右上角头像，选择 Settings。
2. 左侧栏找到 SSH and GPG keys，点击进入。
3. 点击 New SSH key，填写标题（如 'My Laptop'），粘贴公钥，点击 Add SSH key。
4. 测试连接：

   ssh -T [email protected]
   

   若提示 Hi <用户名>! You've successfully authenticated...，则配置成功。

四、创建远程仓库

1. 登录 GitHub，点击右上角 +，选择 New repository。
2. 填写仓库信息：
   • Repository name：项目名称（如 my-project）。
   • Description：可选描述。
   • Public/Private：根据需要选择公开或私有。
   • Initialize this repository with a README：不勾选，否则需先拉取再推送。
3. 点击 Create repository，复制页面上提供的 HTTPS 或 SSH 地址。

五、本地项目上传

假设本地项目路径为 ~/projects/my-project。

1. 初始化本地仓库

切换到项目目录：

cd ~/projects/my-project

执行初始化：

git init

2. 添加文件并提交

将所有文件加入暂存区：

git add .

提交更改：

git commit -m "首次提交：项目初始化"

若主分支名为 master，建议重命名为 main 以符合通用约定：

git branch -M main

3. 关联远程仓库

将远程地址添加为 origin：

# 使用 SSH
git remote add origin [email protected]:你的用户名/my-project.git

# 或使用 HTTPS
# git remote add origin https://github.com/你的用户名/my-project.git

确认关联：

git remote -v

4. 推送到远程

建立跟踪关系并推送：

git push -u origin main

若分支为 master，则使用 git push -u origin master。 推送成功后，刷新 GitHub 仓库页面即可查看文件。

六、后续开发与同步

1. 修改与上传

修改或新增文件后：

git add .
git commit -m "本次更新：简要说明修改内容"
git push

由于已建立跟踪关系，后续只需 git push。

2. 处理远程更新与冲突

多人协作时，远程可能有新提交。推送前先拉取：

git pull --rebase origin main

若出现冲突，手动编辑冲突文件，移除标记（<<<<<<<, =======, >>>>>>>），保存后执行：

git add 冲突已解决的文件
git rebase --continue

解决后再执行 git push。

七、常见问题与注意事项

1. 隐藏字符问题：复制命令前若有不可见字符（如破折号），会导致 command not found，请手动输入命令。
2. .gitignore 文件：在项目根目录创建 .gitignore，排除编译临时文件、IDE 配置等（如 node_modules/, *.log, .env）。
3. Token 安全：GitHub 已弃用 HTTPS 密码验证，需使用 Personal Access Token。
4. README 初始化冲突：若远程已初始化 README，直接推送会被拒绝。请先执行 git pull --rebase origin main 合并远程更改。
5. 分支管理：开发新功能建议新建分支：

   git checkout -b feature/新功能名称
   

   完成后切回主分支合并：

   git checkout main
   

git merge feature/新功能名称 git branch -d feature/新功能名称

## 八、小结

1. 安装 Git 并配置 `user.name`、`user.email`。
2. 配置 SSH 密钥并添加到 GitHub。
3. 在 GitHub 创建空仓库（不初始化 README）。
4. 本地执行 `git init`，`git add .`，`git commit`。
5. 使用 `git remote add origin` 关联远程。
6. 执行 `git push -u origin main` 推送代码。
7. 后续更新遵循 `add` → `commit` → `push` 流程，合并前注意 `pull --rebase`。

以上步骤涵盖从环境搭建到代码同步的全流程，按步骤操作即可顺利维护 GitHub 仓库。