当前位置：首页 > news >正文

本地项目上传至GitHub仓库标准操作手册

news 2025/11/8 7:34:06

引言

本手册旨在建立一套标准操作规程，用于将本地项目首次同步至远程GitHub仓库。遵循此规程可有效规避常见的配置陷阱，并确保项目自始便拥有清晰的版本历史记录。

在执行上传操作之前，必须完成两个关键的前置步骤，以确保本地环境与云端平台之间的通信链路畅通无阻。

这套准备工作是保障整个上传流程顺利进行的前提。

远程仓库是项目在云端的存储与协作中心。

Repository name (仓库名称): 输入一个简明且唯一的项目名称。
Description (描述): (可选) 填写对项目的简要介绍。
重点操作: 务必勾选 Add a README file (添加一个README文件)。此操作会通过一个初始提交来初始化仓库，并创建README.md文件，该文件是项目详细描述的标准载体。

完成创建 确认信息无误后，点击 Create repository 按钮。至此，项目的远程仓库已成功创建。
在这里插入图片描述

Git是一个分布式版本控制系统（DVCS），是与GitHub通信和执行版本控制的行业标准工具。其分布式架构支持强大的离线工作能力和高效的团队协作。

在这里插入图片描述

至此，所有准备工作均已完成，接下来将进入核心的命令行操作环节。

本节详细介绍执行项目上传所需的一系列Git命令。这些命令用于初始化版本控制、记录文件变更，并最终将项目推送至远程GitHub仓库。

操作目的 将一个标准的本地文件夹转换为一个可由Git进行版本管理的仓库。
执行命令
- 在文件资源管理器中，进入待上传的项目文件夹。
- 在文件夹的空白区域（而非任何特定文件上）单击鼠标右键，从上下文菜单中选择 Git Bash Here。此操作将打开一个命令行终端，其当前路径已设为该项目文件夹。
- 在Git Bash终端中，输入以下命令并按回车键：git init
预期结果 命令成功执行后，项目文件夹内会创建一个名为 .git 的隐藏目录。该目录是Git仓库的核心，存储了所有版本历史和元数据。如需查看，请在文件资源管理器的“查看”选项中启用“显示隐藏的项目”。

概念解析

Git通过一个三区域模型来管理文件变更：工作目录:（您的项目文件）、暂存区:（用于准备下一次提交的变更快照）和本地仓库（永久记录项目历史的.git目录）。
- git add 命令将变更从工作目录移至暂存区。
- git commit 命令将暂存区的快照永久性地记录到本地仓库。
执行命令
- 执行git add .命令，将当前目录（.）下的所有文件和变更添加到暂存区
- 执行git commit -m "注释"命令，提交暂存区的内容。-m 参数用于附加一条描述性提交信息，这是版本控制的最佳实践。这一步可能会报错，请参考“3.2 首次提交失败（用户信息未配置）” 或者执行提示的两条命令设置全局的用户信息，操作完之后再按照步骤执行。
- 报错：

操作目的 在本地Git仓库与GitHub远程仓库之间建立链接通道。
获取URL
- 返回GitHub仓库页面。
- 点击绿色的 Code 按钮，在下拉菜单中确保已选中 HTTPS 标签页，然后点击复制图标以获取仓库URL。
执行命令
- 回到Git Bash终端，输入git remote add origin 命令，并将 <your_repository_url> 替换为已复制的URL
- 操作提示: 在Git Bash终端中，Ctrl+V快捷键可能无效。推荐使用鼠标右键单击并选择 Paste 选项来粘贴URL。

在这里插入图片描述

注：master是Git传统的默认主分支名称。业界正逐步转向使用main作为新标准。本手册使用master以与当前示例的初始化过程保持一致，但在新仓库中您可能会遇到main。
预期结果 终端将显示文件压缩和上传的进度。命令执行完毕且无错误报告，即表示本地项目已成功同步至GitHub。

在这里插入图片描述

命令成功执行后，项目文件已上传至GitHub。切换到master分支就可以看到了。
在这里插入图片描述

操作完成后的验证环节至关重要。本节同时提供一个常见配置问题的解决方案，以帮助用户建立独立排错的能力。

为验证上传结果，请执行以下步骤：

问题描述

在首次执行
```
git commit
```
命令时，终端可能会报错，显示包含
```
 Please tell me who you are.
```
的信息，并提示运行
```
git config --global user.email "you@example.com"
```
```
git config --global user.name "Your Name"
```
- 根本原因: Git要求每一次提交都必须明确标识作者身份。若本地Git客户端未配置此信息，提交操作将失败。可以根据提示信息进行配置，也可以采取下面的解决方法。
解决方案
- 定位文件: 在本地项目文件夹中，进入隐藏的 .git 目录，找到并使用文本编辑器（如VS Code或记事本）打开 config 文件。
- 修改配置: 如果文件中不存在 [user] 段落，请在文件末尾添加。如果已存在，请确保其下包含email和name键。将占位符替换为您的GitHub账户信息。
- (注：YourGitHubUsername是您GitHub个人资料页上显示的用户名，通常位于github.com/YourGitHubUsername)
- 保存并重试: 保存并关闭config文件。返回Git Bash终端，按键盘的向上方向键调出上一条失败的git commit命令，然后按回车键重新执行。此时命令应能成功完成。