GitHub开源项目复现指南

最新推荐文章于 2025-03-21 09:57:41 发布

西电小胡

最新推荐文章于 2025-03-21 09:57:41 发布

阅读量2.2k

点赞数 36

文章标签： github python windows git

本文链接：https://blog.csdn.net/m0_74480168/article/details/145484003

版权

前言：

GitHub是当前的开源项目、代码分享和协作的核心平台。对于开发者来说，能够用好GitHub进行项目复现，是一项重要技能。然而，新手在尝试复现项目时会遇到各种各样的障碍，比如环境配置问题、网络连接问题等（常常复现一个项目就要花上几个小时~让人头大）。因此，本文将以一个小白的视角去介绍GitHub的项目基本复现过程，以及如何解决常见问题，作为指南供大家参考（也包括我自己）。

一、简介

（一）GitHub

GitHub是一个基于Git的代码托管平台，广泛用于版本控制和协作开发。开发者可以通过GitHub存储、管理和分享代码，同时也能与全球的开发者进行协作。简单来说，GitHub就是一个代码仓库平台，每个人都可以在上面建立私人的或公开的代码仓库，而Git（版本控制工具）就是我们的仓库管理助手。

关于GitHub的使用，大家可以阅读该篇博客：

github新手用法详解（建议收藏！！！）-CSDN博客

（二）Git

Git的核心概念：仓库（Repository）、提交（Commit）、克隆（Clone）等。对于新手来说，最重要的一个概念或功能可能就是克隆（Clone）。

（三）GitBash

Git Bash是Git for Windows中自带的一个命令行工具，适用于Windows用户在Windows操作系统上使用Git命令。Git Bash提供了一个终端，用户可以在其中使用Git的常见命令（如git clone、git commit、git push等）来管理Git仓库。

二、流程

下面我将以GitHub热门项目——ChatTTS的复现为例，介绍常见的项目复现流程。

1. Git 安装：

git的安装与配置教程-超详细版_git安装及配置教程-CSDN博客

测试是否安装成功：快捷键（Win+R），输入 cmd，运行命令行程序。执行下列指令：

git --version

2. 本地账户设置：

远程仓库通常支持两种身份认证方式：SSH与HTTPS协议：

SSH协议：基于密钥对（公钥和私钥），通过机器身份进行认证。适合长期使用和自动化操作，且安全性较高。
HTTPS协议：基于账号和密码进行认证，适合新手和简单配置，且兼容性强，但频繁输入凭证导致便捷性较差。

以上通过两种认证方式，用户可以在认证后获得操作仓库权限，但GitHub还需记录操作者身份信息，因此要求我们在Git上完成本地账户设置。搜索并打开Git Bash，执行下列指令：

git config --global user.name "User Name"
git config --global user.email "email@XXX.com"

git config user.name  // 查看用户名
git config user.email  // 查看用户邮箱

3. SSH 配置：

SSH密钥对由公钥和私钥组成，用于远程仓库的身份认证（例如GitHub）。关于SSH密钥的相关操作（包括生成、查看、删除）如下。

① 检查

检查本地主机是否已经存在SSH Key，若存在 id_rsa 和 id_rsa.pub文件，说明该主机已配置SSH Key，无需再次生成，直接进行步骤 ③。

// 切换路径
cd ~/.ssh
// 查看文件列表
ls

② 生成

若无SSH Key，则可通过在Git Bash中执行下列指令生成并查看SSH Key：

// 生成RSA密钥
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"  
// 查看公钥内容
cat ~/.ssh/id_rsa.pub

-t ：指定密钥类型为RSA。
-b：指定密钥的长度，默认使用4096位的RSA密钥。
-C：为密钥添加注释，通常使用你的GitHub注册邮箱，以便识别该密钥。

执行上述指令后，Git Bash会提示你输入保存密钥的路径并设置密码，但你可以不用设置，直接回车即可。私钥默认保存为：~/.ssh/id_rsa；公钥默认保存为：~/.ssh/id_rsa.pub。公钥：用户将生成的公钥上传到远程仓库平台（如GitHub）上，相当于一个“身份标识”。私钥：保留在本地计算机上，本地主机能够使用它来进行加密和解密操作。当用户尝试通过SSH协议连接远程仓库时，系统会使用你机器上的私钥进行加密，然后通过上传至远程仓库平台的公钥来验证。如果验证内容匹配，则通过身份验证。

接下来，我们需要做的就是查看公钥内容，并将公钥“交给”远程仓库，即GitHub。具体步骤参考下列博文：

Github配置ssh key的步骤（大白话+包含原理解释）_github生成ssh key-CSDN博客

③ 验证*

测试用户与 GitHub 之间的 SSH 连接是否配置正确，并验证SSH 密钥是否已经成功添加到 GitHub 的账户中。在Git Bash中运行下列指令（建议提前关闭加速器）：

ssh -T git@github.com

若正确完成配置，并成功验证，会得到类似下图的输出结果：

但经常会有宝子在该验证步骤出现报错。常见的错误有：“ ssh: connect to host github.com port 22: Connection refused或Connection timed out ”。导致这类情况的可能原因有：

访问github.com的22号端口被拒

方法1：尝试切换端口至443访问github.com，需要我们修改~/.ssh目录下的config文件，将其以记事本的形式打开，改为以下内容后重新测试（ssh -T git@github.com）：

Host github.com
  Hostname ssh.github.com
  Port 443

方法2：使用HTTPS协议进行访问，而非通过SSH协议。这要求我们修改~/.git目录下的config文件，需修改url属性。如下图所示：

// 改前
url = git@github.com:username/repo.git
// 改后
url = https://github.com/username/repo.git

网络连接问题

如果通过网页无法正常登录并使用GitHub的话，一般是网络问题。这种情况下，通过SSH也是无法进行访问的，此时可能需要各位小伙伴“科学上网”（不过这个我就不能教了\(^o^)/~）。

域名解析出错

如果并非上述两类问题，最有可能的就是域名解析过程出错了。关于这个问题的产生原因，参考其他博主的说法，是DNS解析出错。

当我们在浏览器中输入 http://github.com 时，操作系统会通过 DNS（域名系统）将这个域名转换成一个 IP 地址，从而定位到实际的服务器。如果 DNS 解析出现问题，可能会导致错误的 IP 地址返回。在该类情况中，DNS 解析一般会错误地将 github.com 解析成了 localhost 的 IP 地址（通常为 127.0.0.1 或 ::1），即本地回环地址。

如果我们使用的 DNS 服务器被错误配置或被篡改（DNS 污染），返回的 IP 地址可能不正确，当 github.com 被错误地解析为 localhost 的 IP 地址后，访问就会被发送到本机而非真正的 GitHub 服务器，也就陷入了回环，多数情况下会报错：访问超时（timed out）。

想要确定是否为该类错误，可以在Git Bash中执行下列指令（查看访问日志）：

ssh -v -T git@github.com

正常情况下：

$ ssh -v -T git@github.com
OpenSSH_9.9p1, OpenSSL 3.2.3 3 Sep 2024
debug1: Reading configuration data /c/Users/hjg_h/.ssh/config
debug1: /c/Users/hjg_h/.ssh/config line 1: Applying options for github.com
debug1: Reading configuration data /etc/ssh/ssh_config
debug1: Connecting to ssh.github.com [20.205.243.160] port 443.
debug1: Connection established.

错误情况下：

$ ssh -v -T git@github.com
OpenSSH_9.9p1, OpenSSL 3.2.3 3 Sep 2024
debug1: Reading configuration data /c/Users/hjg_h/.ssh/config
debug1: Connecting to github.com [::1] port 22.
debug1: connect to address ::1 port 22: Connection refused
debug1: Connecting to github.com [127.0.0.1] port 22.
debug1: connect to address 127.0.0.1 port 22: Connection refused
ssh: connect to host github.com port 22: Connection refused

如何解决上述问题呢？其实只需要让系统能够正确地解析 github.com 域名即可。方法如下：

方法1：刷新 DNS 缓存（命令行中执行：ipconfig /flushdns）

ipconfig /flushdns

方法2（推荐）：修改本地Hosts文件，跳过域名解析这一步骤，使所有关于 github.com 的访问直接指向正确的 IP 地址（简单来说，就是直接告诉系统该访问哪里）

首先，我们需要清楚 github.com 的 IP 地址是多少。在 https://www.ipaddress.com/ 上查询或直接访问：http://github.com.ipaddress.com/，即可得到自己对应的 github.com 的 IP 地址。

或者通过向Google公共DNS服务器（8.8.8.8或8.8.4.4）发送查询请求，返回的是该DNS服务器对github.com的解析结果。在命令行中执行下述指令：

nslookup github.com 8.8.8.8

注意：GitHub的域名通常对应多个服务器IP，DNS解析结果可能会根据访问地点、时间、网络状况等因素返回不同的IP地址，因此不同的查询方式可能会得到不同的结果，选择其一即可。

然后，按下面这篇博客的指引修改Hosts文件，添加 github.com 域名映射：

window10下用git bash下载package：能够网页访问github但是使用git bash here却无法把package下载下来_github下载不了文件但是可以打开网址-CSDN博客

XXX.XXX.XXX.XXX github.com
eg.140.82.112.3 github.com

方法3：重新设置 DNS 服务器。在“网络和 Internet 设置”中，找到当前所使用的网络连接，修改“适配器选项”，双击“Internet 协议版本 4 (TCP/IPv4)”，选择“使用下面的 DNS 服务器地址”，并输入希望使用的 DNS 服务器地址（例如：Google 的公共 DNS~8.8.8.8/8.8.4.4）。

④ 延展

管理 SSH Key 相关操作汇总

--生成SSH密钥对：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

--查看已有的SSH密钥：

ls ~/.ssh

--查看公钥：

cat ~/.ssh/id_rsa.pub

--删除SSH密钥：

rm ~/.ssh/id_rsa ~/.ssh/id_rsa.pub

--测试SSH连接：

ssh -T git@github.com

4. 项目部署：

做了那麽多铺垫，总算可以进入正题啦！！！不过前面的步骤一定要做好，保证 ssh -T git@github.com 验证结果正确，这样能省去很多后面的麻烦，至少在 git 指令的使用上不会出现太多问题。

本文以GitHub热门项目ChatTTS的复现为例，去介绍项目复现的基本流程。当然，不可能代表所有项目复现过程，但或多或少能帮助大家初步理解大多项目是如何部署到本地。

首先，我们在 GitHub 网页上打开目标项目（ChatTTS）主页，可以看到下面的内容：

文件很多，但等等再晕_(¦3」∠)_。无论是哪一个项目，一般都不会缺少 “README.md” 文件。顾名思义，就是提醒我们“阅读”它。该文件一般包含了项目简介、效果展示和使用安装说明等内容——指导用户如何使用该项目。因此，无论复现哪一个项目，都请宝子们一定要慢慢读这部分的内容，尤其是图-1中的 “Get Started” 部分（也有比较成熟的项目直接放上了使用文档的链接，比如图2中的Fish Speech）。

① 项目克隆

因为我们只需要复现项目，所以首先要做的就是完完整整地把别人的项目复制下来。因此，我们可以用 git clone 指令。大家可能知道在建立仓库之前，必须执行 git init ，但 git clone 实际上已经包含了 git init 这一步骤，它会自动创建一个隐藏的 .git 文件夹。

git clone [选项] <仓库地址> [本地目录]

git clone https://github.com/2noise/ChatTTS

git：调用 Git 程序。
clone：子命令，表示克隆目标仓库。
[选项]：可选参数，用于调整克隆行为（新手可忽略）。
[本地目录]：可选参数，指定克隆目标后存储在本地的目录名称。如果不指定，Git 会根据远程仓库名称自动创建一个目录。
<仓库地址>：远程仓库的 URL（指明克隆什么？从哪克隆？），可以是 HTTPS 格式或 SSH 格式，如下：

eg https://github.com/username/repo.git
eg git@github.com:username/repo.git

理解了 git clone 的原理后，大家最初可能都会有的疑问就是——在哪执行这个指令？其实，答案很简单，在哪都可以^_^。可以是在命令行（CMD）中执行，也可以是Anaconda，还可以是git bash。原因是：终端本质上是一个命令解释器，它负责读取用户输入的命令，并调用相应的可执行程序。无论是在 Windows 的 CMD、Git Bash，还是在 Linux/macOS 的终端，只要命令（git）在系统 PATH 中都可以被调用执行。

在执行 git clone 时需要注意的是，打开终端的位置会影响项目文件的保存位置。所以，比较在意C盘内存或是有强迫症的小伙伴，最好单独设置个文件夹保存项目，方便管理。下图中，我使用CMD在D:\~\400.Projects目录下执行了 git clone 指令（右键文件夹，点击“在终端中打开”即可，或者通过 cd 指令切换至目标路径）。

注意：如果你正在科学上网且使用了代理，那么你需要正确配置 git 代理，否则可能会出现该类报错“ fatal: unable to access 'https://github.com/XXX/XXX/': Failed to connect to github.com port 443 after 21121 ms: Could not connect to server ” 。配置 git 代理步骤如下：

--查看代理地址和端口：

--配置代理：将http://proxyserver替换为上图中的代理IP地址，port替换为端口号

git config --global http.proxy [http://proxyserver]:[port]
git config --global https.proxy [https://proxyserver]:[port]

eg. git config --global http.proxy 127.0.0.1:7897

--如果你未使用代理，请删除 git 代理设置：

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

② 依赖项安装

为什么需要安装依赖项？简单地说，因为一个项目程序的运行可能也依赖其他的python库（依赖项）。开发者可能不会将依赖项上传到仓库，但我们可以通过其他渠道获取并安装依赖项。

如上图所示，项目开发者提供了两种安装方式：1. 直接安装、2. 通过conda安装。这两种方式有什么区别呢？

如果采取方式1（直接安装），那么当你在CMD中执行 pip install --upgrade -r requirements.txt 时，依赖项会被安装到全局 Python 环境 中。具体储存在：Python 安装目录下的site-packages文件夹（路径一般是：~\Python\Lib\site-packages）。

如果采取方式2（通过conda安装），依赖项会被安装到 虚拟环境 的site-packages目录中。例如，如果使用Anaconda在base环境下安装，依赖项储存在~\Anaconda\Lib\site-packages。建议使用虚拟环境来管理项目依赖，这样可以避免不同项目之间的依赖冲突，确保环境独立性。如果你不了解什么是conda以及如何使用Anaconda管理虚拟环境，可以看我的另一篇博客：

Anaconda用法总结&虚拟环境配置_anaconda虚拟环境-CSDN博客

备注：如果你想知道Python环境或conda环境中安装了哪些依赖项，可以执行下列指令：

pip list
//pip list 只会列出当前环境中通过 pip 安装的包。
conda list
//conda list 列出的是当前环境中所有安装的包，包括通过 conda 和 pip 安装的包。

具体解析下 pip install --upgrade -r requirements.txt 指令：“--upgrade”是一个可选项，表示升级已安装的包。如果指定的包已经安装，pip 会检查当前安装的版本是否与 requirements.txt 中指定的版本匹配。如果不匹配，pip 会将其升级到文件中要求的版本。“-r requirements.txt”表示要从文件“requirements.txt”中读取需要安装的包列表（依赖项和对应版本号）。注意：无论采用哪种方式安装，均需要切换至对应目录下，否则会返回无法找到目标文件的报错“ ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt' ”。如下图所示，“cd ChatTTS”指令的作用就是切换至“requirements.txt”文件存放的目录。

方式2中，并没有选择“--upgrade”，因为新创建的虚拟环境未安装额外的依赖包，因此无需考虑版本更新问题。

下面我将采用方式2进行安装：（注意：使用 cd <路径>，切换至先前的~\ChatTTS文件夹下）

若正确安装，过程无报错，最终返回结果如下：

③ 项目运行

一个项目运行并使用的方式有很多，常见的有：1. 通过网页端（Web UI）运行；2. 本地执行Python脚本运行；3. 通过容器化（Docker）部署运行。比较成熟的项目一般会提供多种运行方式，这也是GitHub项目复现主要差异也体现在运行方式上。

以ChatTTS为例，开发者提供了两种运行方式：网页和本地运行。从用户的角度来看，通过网页运行项目的体验感和便捷性会更好，但本地运行通常会更稳定（无需考虑网络连接问题）。但这两者都绕不开在终端执行Python脚本这一步骤。因此，仍需要在特定目录下执行指令，如下图：

方式1 ：通过网页端（Web UI）运行

在Anaconda中，激活虚拟环境（chattts）后执行，下列指令:

python examples/web/webui.py

最终，会自动弹出下图所示网页：

注意： 可能无法弹出网页，报错：“ ValueError: When localhost is not accessible, a shareable link must be created. Please set share=True or check your proxy settings to allow access to localhost. ”这种情况一般是因为代理设置问题，导致程序无法正常访问 localhost 。解决这个问题有多种方法，但在我尝试后，最为有效且方便的是：修改程序代码，设置 no_proxy 环境变量，使程序针对本地地址的请求绕过代理服务器，直接与本地服务器建立连接。

import os
os.environ["no_proxy"] = "localhost,127.0.0.1,::1"

以记事本的形式打开 webui.py 文件，添加上述代码内容，如下图所示：

虽然，网上还有其他解决方式，例如：修改或添加demo.launch(share=True)、在终端中执行export no_proxy="localhost,127.0.0.1,::1"、关闭代理服务器……但基本没效果或者不方便后续使用o(╥﹏╥)o。

方式2：本地执行

不得不吐槽下，ChatTTS提供的本地执行示例真的很简陋（没说怎么调参、没有演示视频、没有不同功能的执行示例），或许它的官方网站 chattts.com 上可能有说明吧（但我没找到）。基本流程和方式1类似，也是执行python脚本，但此时需要用户同时输入生成内容，如下：

cd D:<路径>\ChatTTS
conda activate ChatTTS
python examples/cmd/run.py "Your text 1（对话内容1）" "Your text 2（对话内容2）"

在 Python 中，如果你需要在命令行传递参数给脚本（run.py），通常使用 sys.argv 或 argparse 来接收这些参数。因此，在上述指令中需要输入 "Your text 1（对话内容1）" "Your text 2（对话内容2）"，用于生成音频。

生成的音频文件保存在ChatTTS目录下，文件名格式为：output_audio_[数字].mp3。

方式3：作为python包使用

用户直接从 Git 仓库安装 Python 包或模块。安装时，pip 会查找仓库中的 setup.py 或 pyproject.toml 文件，作为安装指示。安装后，该Python包可以在Python脚本中导入并使用。

该方式适合需要快速安装和将 GitHub 项目作为包应用于其他项目的情况，本文中不再过多介绍。

三、结语

其实，对于曾经也是小白的我来说，初次接触GitHub也是有些畏惧和排斥，因为大多项目开发者都默认使用者有一定基础，因此许多项目说明都是“言简意赅”，对于小白的确不友好。但谁又没有经历过小白这一阶段呢(#^.^#)。

是小白没关系，但不能只是从表面去认识代码和指令，慢慢地理清各类工具之间的关系，了解指令背后的深层机制，明确报错的产生原因，而不要只为了解决问题。慢慢做，细细想，第一次复现可能会花很长时间，但这之后再次遇到相似的问题，你也许就能独自去尝试解决。具体问题具体分析，网络上的方案不一定有效，一个个试不如思考后择优尝试。

写下这篇博客，不仅是给我自己看，也是希望大家能在学习的开始少走些弯路。CSDN上关于这方面的文章确实不多，主要是项目千奇百怪，确实没有一个范式去说明复现流程。我所能做的也只有根据自己的经验和理解，去总结些常用方法，记录些常见报错，希望能帮到大家\(^o^)/~。

本文的部分内容来自我个人的主观思考，如有错误或不严谨的地方也欢迎大家评论区指出！