Git clone 怎么用？克隆项目及常见问题完整教程

Git clone 怎么用？克隆项目及常见问题完整教程

从基本语法到 HTTPS、SSH、浅克隆、子模块与错误排查

大家好，我是 lazy，一名大二科班学生

摘要

git clone 是开始使用远程 Git 项目时最常见的命令之一。它看起来只是把代码下载到本地，实际上还会创建本地仓库、保存版本历史、建立远程仓库关联，并检出默认分支。本文从基本用法开始，系统讲解 HTTPS 与 SSH 克隆、指定目录、指定分支、浅克隆、子模块克隆以及克隆完成后的常用检查方法，同时整理新手经常遇到的报错和对应解决思路。

|-----------------------------------------------------------------|
| **适合读者：**刚接触 Git、需要从 GitHub、Gitee 或公司代码平台获取项目，以及经常遇到克隆失败问题的开发者。 |

前言

当我们加入一个已有项目时，通常不会从空目录重新创建代码，而是从远程仓库获取完整项目。此时最常用的命令就是 git clone。与直接下载 ZIP 压缩包不同，克隆得到的不只是当前文件，还包含仓库的版本历史和分支信息，因此可以继续执行提交、拉取、推送和分支操作。

为了让命令更容易复制，本文所有代码块内部只放纯命令或终端输出，解释全部放在代码块外。

一、git clone 到底做了什么？

git clone 会把一个已有仓库复制到本地的新目录。克隆完成后，本地通常会得到工作区和隐藏的 .git 目录；同时，远程仓库地址会被保存为名为 origin 的远程地址。Git 还会创建远程跟踪分支，并检出远程仓库当前的默认分支。

图 1 git clone 创建本地仓库的基本过程

因此，git clone 不是简单的"下载文件"。它相当于一次性完成了创建目录、初始化本地仓库、获取远程对象、配置远程地址和检出默认分支等操作。

二、克隆项目之前需要准备什么？

1. 确认 Git 已安装

先在 Git Bash、PowerShell、命令提示符或终端中查看 Git 版本。

复制代码

git --version

能够看到版本号，说明 Git 命令已经可以正常使用。

2. 获取正确的仓库地址

在 GitHub、Gitee 或公司代码平台的仓库页面中找到"Code""克隆/下载"或类似按钮，然后复制 HTTPS 或 SSH 地址。不要直接复制浏览器地址栏中的页面地址，因为网页地址与 Git 克隆地址不一定完全相同。

3. 选择本地保存位置

执行命令前先进入准备存放项目的父目录。Git 会在当前目录下创建新的项目文件夹。

复制代码

cd D:/workspace

|----------------------------------------------------------------------|
| **路径建议：**Windows 用户尽量选择路径较短、没有特殊符号的开发目录，例如 D:/workspace，减少路径长度和权限问题。 |

三、git clone 的基本语法

最基本的语法是在 git clone 后面填写远程仓库地址。

复制代码

git clone <仓库地址>

1. 使用 HTTPS 地址克隆

复制代码

git clone https://github.com/user/demo.git

Git 会根据仓库名称创建 demo 目录，并把项目克隆到该目录中。公共仓库通常可以直接读取；私有仓库则需要有效的账号凭据和访问权限。

2. 使用 SSH 地址克隆

复制代码

git clone git@github.com:user/demo.git

SSH 克隆要求本机已经生成 SSH 密钥，并且公钥已经添加到对应代码托管平台的账号中。配置完成后，日常拉取和推送通常不需要反复输入凭据。

3. 克隆后进入项目目录

复制代码

cd demo

4. 检查远程仓库地址

复制代码

git remote -v

默认情况下，克隆时使用的远程仓库会被命名为 origin。输出中通常会分别显示 fetch 和 push 地址。

复制代码

origin  https://github.com/user/demo.git (fetch)
origin  https://github.com/user/demo.git (push)

四、HTTPS 和 SSH 应该怎么选？

图 2 HTTPS 与 SSH 克隆方式对比

|---------|---------------|----------------|
| 对比项 | HTTPS | SSH |
| 地址形式 | https://... | git@... |
| 前期配置 | 通常较少 | 需要先配置 SSH 密钥 |
| 身份验证 | 凭据管理器、令牌或平台登录 | SSH 私钥 |
| 网络适应性 | 通常更容易通过代理和防火墙 | 部分网络可能限制 22 端口 |
| 适合场景 | 新手、临时克隆、公共仓库 | 长期开发、私有仓库、频繁推送 |

两种方式克隆到本地的项目内容没有区别，区别主要在连接方式和身份验证。刚开始使用可以优先选择 HTTPS；如果经常参与团队项目，可以配置 SSH。

五、把项目克隆到指定目录

默认目录名来自仓库名称。如果希望使用其他文件夹名称，可以在仓库地址后面增加目标目录名。

复制代码

git clone https://github.com/user/demo.git my-project

执行后，项目会被保存到当前路径下的 my-project 目录，而不是 demo 目录。

|-------------------------------------------------------|
| **注意：**目标目录可以不存在，Git 会自动创建；如果目标目录已经存在并且不是空目录，克隆通常会失败。 |

六、克隆指定分支

默认情况下，Git 会检出远程仓库的默认分支。如果只想直接打开某个指定分支，可以使用 --branch 或简写 -b。

复制代码

git clone --branch dev https://github.com/user/demo.git

git clone -b dev https://github.com/user/demo.git

上面的命令会在克隆完成后直接检出 dev 分支。需要注意，普通克隆仍然会获取其他分支所需的仓库对象和远程分支信息。

只克隆指定分支

如果仓库较大，并且明确只需要一个分支，可以结合 --single-branch。

复制代码

git clone --branch dev --single-branch https://github.com/user/demo.git

|--------------------------------------------------------------|
| **适用场景：**部署脚本、临时测试环境或只需要固定分支内容时，可以使用单分支克隆；日常开发通常保留完整分支信息更方便。 |

七、使用浅克隆提高速度

大型仓库可能包含多年的提交历史。如果只关心最近版本，可以使用 --depth 限制获取的历史深度。深度为 1 表示只获取当前分支最近的一层提交历史。

复制代码

git clone --depth 1 https://github.com/user/demo.git

浅克隆能够减少下载数据量和克隆时间，但本地历史不完整，某些日志查询、版本比较和旧版本操作会受到限制。

浅克隆指定分支

复制代码

git clone --depth 1 --branch main --single-branch https://github.com/user/demo.git

以后补全历史记录

复制代码

git fetch --unshallow

|--------------------------------------------------------------|
| **选择建议：**临时查看、自动构建和网络较慢时可使用浅克隆；需要长期开发、排查历史问题或进行复杂合并时，建议完整克隆。 |

八、克隆包含子模块的项目

有些项目通过 Git Submodule 引用其他仓库。普通 git clone 只会获取主仓库，子模块目录可能为空或只记录一个提交引用。此时可以在克隆时递归初始化子模块。

复制代码

git clone --recurse-submodules https://github.com/user/demo.git

如果项目已经普通克隆完成，也可以进入项目目录后再初始化子模块。

复制代码

git submodule update --init --recursive

|--------------------------------------------------------|
| **权限问题：**私有子模块同样需要单独的访问权限。主仓库可以克隆成功，不代表其引用的所有子模块都能够访问。 |

九、克隆完成后建议检查什么？

1. 查看当前状态

复制代码

git status

2. 查看本地与远程分支

复制代码

git branch -a

3. 查看远程地址

复制代码

git remote -v

4. 查看最近提交

复制代码

git log --oneline -5

5. 创建自己的开发分支

复制代码

git switch -c feature/login

在团队项目中，通常不建议直接在 main 或 master 分支上开发新功能。克隆完成后先同步项目依赖和配置，再创建个人功能分支会更稳妥。

十、git clone 与下载 ZIP 有什么区别？

|---------|--------------------|--------------|
| 对比项 | git clone | 下载 ZIP |
| 版本历史 | 包含仓库历史，可查看提交 | 通常只有当前文件 |
| 远程关联 | 自动配置 origin | 没有远程仓库配置 |
| 后续同步 | 可以 pull、fetch、push | 需要重新下载或手动上传 |
| 分支操作 | 支持切换、创建、合并分支 | 不包含 Git 分支信息 |
| 适合场景 | 继续开发和长期维护 | 只想查看或运行当前代码 |

如果只是临时查看代码，下载 ZIP 更简单；如果准备修改、提交或持续同步项目，应使用 git clone。

十一、常见问题与解决方法

图 3 git clone 失败时的推荐排查顺序

复制代码

fatal: destination path 'demo' already exists and is not an empty directory.

这表示当前目录下已经存在同名且非空的文件夹。可以删除或重命名旧目录，也可以在克隆命令后指定新的目标目录。

复制代码

git clone https://github.com/user/demo.git demo-new

问题 2：Repository not found

复制代码

remote: Repository not found.
fatal: repository 'https://github.com/user/demo.git/' not found

常见原因包括仓库地址错误、仓库已经改名或删除、当前账号没有私有仓库权限，以及凭据属于另一个账号。先重新从仓库页面复制克隆地址，再确认自己是否能在浏览器中访问该仓库。

|---------------------------------------------------|
| **判断方法：**公共仓库地址正确时通常不需要登录即可读取；私有仓库必须确保账号已被授予访问权限。 |

问题 3：Permission denied (publickey)

复制代码

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

该错误表示 SSH 身份验证失败。需要确认克隆地址中的 SSH 主机正确、本机存在可用私钥、公钥已添加到代码托管账号，并且连接使用的是 git 用户。

复制代码

ssh -T git@github.com

如果暂时不想配置 SSH，可以改用仓库页面提供的 HTTPS 地址。

问题 4：Authentication failed 或密码无效

复制代码

fatal: Authentication failed for <仓库地址>

这通常说明保存的凭据无效、账号没有权限，或者平台要求使用访问令牌、凭据管理器等方式，而不是直接使用账号密码。可以先清理错误凭据，再根据代码托管平台的官方说明重新登录。

问题 5：Could not resolve host

复制代码

fatal: unable to access <仓库地址>: Could not resolve host

这表示域名解析失败。先检查浏览器能否打开代码托管网站，再检查网络、DNS、代理配置和公司防火墙。也可以尝试切换网络环境。

复制代码

git config --global --get http.proxy

git config --global --get https.proxy

如果发现残留了已经失效的代理配置，可以在确认不再需要代理后删除。

复制代码

git config --global --unset http.proxy
git config --global --unset https.proxy

问题 6：Failed to connect、超时或连接被重置

这类问题通常与网络质量、代理、防火墙或 SSH 端口限制有关。可以先重试，并确认目标网站是否可访问；HTTPS 和 SSH 之间互换也可能改善连接。

|-------------------------------------------------------------------|
| **不推荐做法：**不要为了省事长期关闭 SSL 证书校验。证书错误应优先通过更新 Git、检查系统时间、证书链或代理配置来解决。 |

问题 7：RPC failed、early EOF 或大型仓库中断

复制代码

error: RPC failed
fatal: early EOF
fatal: fetch-pack: invalid index-pack output

常见原因是网络连接不稳定或仓库体积较大。可以更换稳定网络后重试，或先使用浅克隆减少传输量。

复制代码

git clone --depth 1 <仓库地址>

如果项目使用 Git LFS，还需要确认 Git LFS 已安装，并且大文件存储服务能够访问。

问题 8：Windows 路径过长

复制代码

error: unable to create file <文件路径>: Filename too long

可以先把项目克隆到更短的目录，例如 D:/code。对于支持长路径的系统和 Git for Windows，也可以启用 Git 的长路径配置。

复制代码

git config --global core.longpaths true

|-------------------------------------------------------------------------------------------|
| **注意：**长路径配置不能解决所有 Windows 路径问题。如果仓库中包含 Windows 不允许的文件名，可能需要在 Linux、WSL 中处理，或由仓库维护者修改文件名。 |

问题 9：指定的分支不存在

复制代码

fatal: Remote branch dev not found in upstream origin

先确认远程分支名称是否正确，包括大小写。可以先普通克隆，再查看远程分支。

复制代码

git clone <仓库地址>
cd <项目目录>
git branch -r

问题 10：子模块克隆失败

主仓库克隆成功，但子模块失败时，应检查 .gitmodules 中记录的地址，以及自己是否拥有子模块仓库的权限。如果主仓库使用 HTTPS，而子模块使用 SSH，还需要确保 SSH 已配置。

复制代码

git submodule sync --recursive
git submodule update --init --recursive

十二、几个容易混淆的命令

|-----------|-------------------|-------------|
| 命令 | 主要作用 | 典型使用时机 |
| git init | 把当前目录初始化为新仓库 | 从零创建本地项目 |
| git clone | 复制已有远程仓库到本地 | 第一次获取已有项目 |
| git fetch | 获取远程最新数据，不自动合并工作区 | 查看远程变化或安全同步 |
| git pull | 获取并整合远程分支 | 已有本地项目继续同步 |
| 下载 ZIP | 只下载当前文件快照 | 只查看或临时运行项目 |

第一次获取一个远程项目使用 git clone；项目已经存在于本地后，通常使用 git fetch 或 git pull 更新，而不是重复克隆。

十三、实际开发中的推荐流程

场景 1：第一次加入团队项目

复制代码

cd D:/workspace
git clone <仓库地址>
cd <项目目录>
git remote -v
git branch -a
git switch -c feature/<功能名称>

场景 2：网络较慢，只想快速查看项目

复制代码

git clone --depth 1 <仓库地址>

场景 3：只部署指定分支

复制代码

git clone --depth 1 --branch main --single-branch <仓库地址>

场景 4：项目包含子模块

复制代码

git clone --recurse-submodules <仓库地址>

十四、git clone 常用命令速查表

|---------|-----------------------------------------------|
| 需求 | 命令 |
| 普通克隆 | git clone <仓库地址> |
| 指定目录 | git clone <仓库地址> <目录名> |
| 指定分支 | git clone -b <分支名> <仓库地址> |
| 只克隆一个分支 | git clone -b <分支名> --single-branch <仓库地址> |
| 浅克隆 | git clone --depth 1 <仓库地址> |
| 递归克隆子模块 | git clone --recurse-submodules <仓库地址> |
| 查看远程地址 | git remote -v |
| 查看所有分支 | git branch -a |
| 补全浅克隆历史 | git fetch --unshallow |

十五、总结

git clone 是获取远程项目的第一步，但它不仅仅是下载文件。克隆会建立完整的本地 Git 仓库、配置 origin、获取远程分支并检出默认分支。日常使用时，先掌握 HTTPS 和 SSH 两种地址、指定目录、指定分支、浅克隆和子模块克隆，就能够覆盖绝大多数场景。

遇到克隆失败时，建议依次检查仓库地址、访问权限、身份验证、网络连接和本地目录。不要看到错误就盲目修改全局配置，尤其不要长期关闭 SSL 校验。先根据错误信息确定问题类型，再采用对应解决方法，会更加安全和高效。

参考资料

Git 官方文档：git-clone Documentation。
Pro Git：Getting a Git Repository。
GitHub 官方文档：Cloning a repository、Troubleshooting cloning errors。
GitHub 官方文档：Permission denied (publickey) 与连接问题排查。

Git clone 怎么用？克隆项目及常见问题完整教程

摘要

前言

一、git clone 到底做了什么？

二、克隆项目之前需要准备什么？

1. 确认 Git 已安装

2. 获取正确的仓库地址

3. 选择本地保存位置

三、git clone 的基本语法

1. 使用 HTTPS 地址克隆

2. 使用 SSH 地址克隆

3. 克隆后进入项目目录

4. 检查远程仓库地址

四、HTTPS 和 SSH 应该怎么选？

五、把项目克隆到指定目录

六、克隆指定分支

只克隆指定分支

七、使用浅克隆提高速度

浅克隆指定分支

以后补全历史记录

八、克隆包含子模块的项目

九、克隆完成后建议检查什么？

1. 查看当前状态

2. 查看本地与远程分支

3. 查看远程地址

4. 查看最近提交

5. 创建自己的开发分支

十、git clone 与下载 ZIP 有什么区别？

十一、常见问题与解决方法

问题 1：目标目录已经存在且不是空目录

问题 2：Repository not found

问题 3：Permission denied (publickey)

问题 4：Authentication failed 或密码无效

问题 5：Could not resolve host

问题 6：Failed to connect、超时或连接被重置

问题 7：RPC failed、early EOF 或大型仓库中断

问题 8：Windows 路径过长

问题 9：指定的分支不存在

问题 10：子模块克隆失败

十二、几个容易混淆的命令

十三、实际开发中的推荐流程

场景 1：第一次加入团队项目

场景 2：网络较慢，只想快速查看项目

场景 3：只部署指定分支

场景 4：项目包含子模块

十四、git clone 常用命令速查表

十五、总结

参考资料