Git远程仓库实操笔记

Git远程仓库实操笔记：Gitee & GitHub 双平台 HTTPS/SSH 全流程

整理了最近实操踩坑的 Git 远程仓库配置，覆盖国内 Gitee 和 GitHub 两个主流平台，分别走 HTTPS 和 SSH 两种连接方式。整体逻辑大同小异，但分支命名、密钥类型、网络问题这些细节坑不少，统一记录下来方便复盘和查阅。

前置：本地 Git 基础配置

在操作远程仓库之前，先确保本地 Git 环境已经完成基础初始化，这一步是所有操作的前提：

1. 新建项目空文件夹，右键打开 Git Bash 窗口
2. 初始化本地 Git 仓库

git init

3. 全局用户配置（本机只需要配置一次，所有仓库共用）

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱地址"

不带 --global 就是仅当前仓库生效，学习阶段用全局配置即可。

---

一、Gitee 远程仓库配置

Gitee 是国内代码托管平台，网络稳定访问流畅，非常适合日常学习和个人项目托管。

1.1 HTTPS 连接方式

HTTPS 是最容易上手的方式，复制仓库地址直接关联即可，缺点是每次推拉代码都需要身份校验，频繁操作会稍显繁琐。

操作步骤

1. Gitee 端新建仓库

   登录 Gitee 后右上角新建仓库，填写仓库名称，建议勾选初始化 README、.gitignore 文件；创建完成后复制仓库的 HTTPS 地址，格式为：

   https://gitee.com/用户名/仓库名.git

   

2. 本地关联远程仓库

   在项目文件夹的 Git Bash 中执行，origin 是远程仓库的默认别名：

git remote add origin https://gitee.com/XS030106/my-test01.git

3. 拉取远程仓库内容
   先把远程的 README、.gitignore 拉取到本地，避免后续推送出现冲突：

git pull origin master

首次操作会弹出登录窗口，输入 Gitee 账号密码完成认证即可。

4. 本地提交并推送代码
   新建一个测试文件，完成本地提交后推送到远程仓库：

# 新建测试文件（示例）
vi test.txt

# 添加文件到暂存区
git add .
# 提交到本地仓库
git commit -m "新增测试文件test.txt"
# 推送到远程master分支
git push origin master

刷新 Gitee 仓库页面，就能看到推送成功的文件，HTTPS 方式配置完成。

踩坑备注

• 执行 git add . 出现 LF will be replaced by CRLF 警告：这是 Windows 与 Linux 系统换行符差异导致，不影响正常使用；如需统一可执行 git config --global core.autocrlf true。
• 仓库地址注意大小写，Gitee 地址对大小写敏感，写错会提示仓库不存在。

1.2 SSH 连接方式（推荐日常使用）

SSH 通过公钥-私钥对进行身份认证，配置完成后免密推拉代码，是长期开发的首选方式。

Gitee 的 SSH 公钥分为两种：账户公钥 和仓库部署公钥，作用范围与权限不同。

1.2.1 账户公钥（全仓库读写权限）

与个人账号绑定，配置后对该账号下所有仓库都拥有读写权限，最适合个人日常开发使用。

操作步骤

1. 本地生成 SSH 密钥对

# -t 指定加密算法，ed25519 轻量安全，是目前最推荐的算法
# -C 为备注信息，方便识别密钥用途
ssh-keygen -t ed25519 -C "Gitee SSH Key"

一路回车即可，密钥默认保存在 ~/.ssh/ 目录下，密码留空即可实现免密操作。

2. 查看生成的密钥文件

ls ~/.ssh/

输出的两个核心文件：

• id_ed25519：私钥，绝对不能外传
• id_ed25519.pub：公钥，需要粘贴到 Gitee 后台

3. 读取公钥内容并复制

cat ~/.ssh/id_ed25519.pub

复制输出的全部内容，从开头的 ssh-ed25519 一直到末尾的备注信息。

4. Gitee 后台添加公钥

   路径：个人设置 → 安全设置 → SSH 公钥 → 添加公钥

   标题可自定义（比如"个人笔记本"），公钥内容粘贴刚才复制的字符串，保存即可。

   

5. 测试连接是否成功

ssh -T git@gitee.com

首次连接输入 yes 信任主机，出现以下提示即为配置成功：

Hi 用户名! You've successfully authenticated, but GITEE.COM does not provide shell access.

后半句是正常提示，Gitee 不提供 SSH 终端登录权限，不影响代码推拉操作。

1.2.2 仓库部署公钥（单仓库只读权限）

只针对单个指定仓库生效，默认只有拉取权限、无法推送，一般用于生产服务器部署代码，防止误操作修改线上代码。

操作步骤

1. 本地生成密钥的步骤与账户公钥完全一致
2. 进入对应仓库页面：管理 → 部署公钥管理 → 添加部署公钥
3. 粘贴公钥内容保存，测试连接方式同上
   
   

1.2.3 两种公钥核心区别

公钥类型	作用范围	权限	适用场景
账户公钥	账号下所有仓库	可读可写	个人日常开发、多项目维护
部署公钥	单个指定仓库	默认只读	服务器部署、CI/CD 自动拉取

---

二、GitHub 远程仓库配置

GitHub 是全球最大的代码托管平台，整体逻辑与 Gitee 基本一致，但有两个特殊点：国内网络访问不稳定、HTTPS 方式必须使用令牌登录。

2.1 HTTPS 连接方式

GitHub 目前已不支持账号密码直接登录 HTTPS，必须使用个人访问令牌（PAT）作为密码进行认证。

操作步骤

1. GitHub 新建仓库

   右上角 New repository，填写仓库名称，选择公开/私有属性，按需勾选 README 和 .gitignore；创建完成后复制 HTTPS 地址，格式为：

   https://github.com/用户名/仓库名.git

   

2. 本地关联远程仓库

git remote add origin https://github.com/Xie724/myTest01.git

3. 生成 Personal Access Token（PAT）

   路径：右上角头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)

   • Note 填写备注，比如"Windows 本地开发"
   • Expiration 选择令牌过期时间，学习使用可设置较长有效期
   • 必须勾选 repo 权限，其他权限按需选择
   • 生成后立即复制令牌，页面关闭后无法再次查看，务必保存好
     

4. 拉取远程代码

# GitHub 新建仓库默认主分支是 main，不是 master！
git pull origin main

弹出登录窗口时，用户名填写 GitHub 账号，密码粘贴刚才生成的 PAT 令牌。

踩坑备注

• 国内网络经常出现 Failed to connect to github.com:443 连接超时，属于网络环境问题，无代理的情况下不推荐日常使用 GitHub HTTPS。
• 令牌丢失只能重新生成，无法找回原令牌。

2.2 SSH 连接方式

逻辑与 Gitee SSH 完全相同，仅公钥粘贴位置不同；配合网络代理使用时，稳定性远好于 HTTPS。

操作步骤

1. 生成 GitHub 专属密钥（可选）
   如果希望 Gitee 和 GitHub 使用独立密钥，生成时指定文件名即可：

ssh-keygen -t ed25519 -C "GitHub SSH Key" -f ~/.ssh/id_ed25519_github

懒人方案：直接使用同一对公钥，同时粘贴到 Gitee 和 GitHub 后台，无需额外配置。

2. GitHub 后台添加公钥

   路径：右上角头像 → Settings → SSH and GPG keys → New SSH key

   • Title 填写备注
   • Key type 选择 Authentication key
   • Key 栏粘贴公钥内容，保存即可
     
     

3. 测试连接

ssh -T git@github.com

出现 Hi 用户名! You've successfully authenticated 即为配置成功。

进阶：双平台多密钥共存配置

如果 Gitee 和 GitHub 使用了不同的密钥，需要通过 SSH config 文件实现自动分流，避免密钥串号：

1. 进入 ssh 目录，新建无后缀的 config 文件

cd ~/.ssh
nano config

2. 粘贴以下配置内容：

   Gitee 配置

   Host gitee.com
   HostName gitee.com
   User git
   IdentityFile ~/.ssh/id_ed25519_gitee
   IdentitiesOnly yes

   GitHub 配置

   Host github.com
   HostName github.com
   User git
   IdentityFile ~/.ssh/id_ed25519_github
   IdentitiesOnly yes

3. 保存退出后，SSH 连接会自动匹配对应平台的密钥。

---

三、高频踩坑与核心总结

3.1 master 还是 main？分支名踩坑

• 本地 git init 初始化的仓库，默认分支名叫 master
• Gitee、GitHub 新建的线上仓库，默认主分支都叫 main
• 报错 couldn't find remote ref master 几乎都是因为远程分支是 main，拉取/推送时写对分支名即可
• 本地分支改名命令：git branch -m master main
• 本地 master 推送到远程 main：git push -u origin master:main

3.2 远程仓库常用命令

# 查看当前远程地址
git remote -v

# 修改远程仓库地址
git remote set-url origin 新地址

# 删除远程仓库关联
git remote remove origin

3.3 HTTPS vs SSH 怎么选？

对比项	HTTPS	SSH
上手难度	简单，复制地址即用	稍复杂，需要生成密钥对
认证方式	账号密码/令牌，每次操作校验	密钥对认证，配置后全程免密
网络表现	GitHub 极易超时，体验差	相对稳定，受网络波动影响小
适用场景	临时拉取公开仓库	长期开发、日常代码推送

3.4 个人使用建议

• 国内日常学习、项目托管：优先选择 Gitee + SSH，网络稳定，体验流畅
• 需要同步 GitHub：配置双密钥，本地仓库可同时添加两个远程源，实现一键同步推送
• 单个仓库尽量统一使用一种协议，避免 HTTPS 和 SSH 混用导致凭证混乱