从零到一：本地项目上传Gitee完整指南（新手避坑版）

在日常开发或毕业设计中，将本地项目上传到代码托管平台是必备技能。Gitee（码云）作为国内优质的Git托管服务，不仅访问速度快，还支持私有仓库、协作者管理等实用功能，特别适合国内开发者和学生使用。本文将以「ESP32车载声浪模拟控制系统」毕设项目为例，从环境准备到代码推送，一步步教你完成本地项目上传，同时揭秘新手常踩的坑及解决方案。

一、前置知识：核心概念快速理解

在开始操作前，先搞懂3个关键概念，避免后续 confusion：

Git：本地代码版本控制工具，负责跟踪文件修改、管理提交记录，是连接本地项目和Gitee的桥梁；
Gitee：远程代码托管平台，相当于"云端代码仓库"，用于存储、共享你的项目；
分支（Branch） ：项目的"并行开发线"，默认主分支为main（新版Git）或master（旧版Git），推送时需保证本地分支与远程分支名称一致。

二、准备工作（3步必做）

2.1 安装Git工具

Git是上传项目的基础工具，支持Windows/macOS/Linux全平台：

下载地址：Git官方下载（Windows自动识别系统，直接下载64位安装包）；
安装流程：全程点击「Next」默认安装（新手无需修改任何配置），直至「Finish」；
验证安装：按下Win+R输入cmd，执行命令git --version，若显示git version x.x.x则安装成功。

2.2 注册并登录Gitee账号

访问Gitee官网：https://gitee.com/；
注册方式：用手机号快速注册，建议绑定邮箱（便于找回账号）；
登录后进入个人主页，后续将在这里创建远程仓库。

2.3 配置Git与Gitee关联

让Git识别你的Gitee身份，避免后续推送权限报错：

右键桌面空白处，选择「Git Bash Here」打开Git命令窗口；

执行以下命令（替换为你的Gitee用户名和注册邮箱）：

bash 复制代码

# 配置用户名（Gitee个人主页显示的昵称）
git config --global user.name "你的Gitee用户名"
# 配置邮箱（注册Gitee时使用的邮箱）
git config --global user.email "你的Gitee注册邮箱"

验证配置：执行git config --global --list，能看到上述配置信息即生效。

三、详细上传步骤（6步搞定）

以本地car_sound_simulation_control（ESP32毕设项目）为例，完整上传流程如下：

3.1 步骤1：在Gitee创建远程仓库

登录Gitee后，点击右上角「+」号 → 选择「新建仓库」；

填写仓库信息（关键配置如下，其余默认）：

配置项	推荐值	注意事项
仓库名称	与本地项目文件夹一致（如car_sound_simulation_control）	小写+下划线，避免空格、中文、特殊符号
仓库介绍	简要描述项目（如"基于ESP32的车载声浪模拟控制系统毕设"）	便于后续检索和他人理解
仓库类型	私有（毕设项目首选）	防止代码被抄袭，后续可按需改为公开
初始化仓库	取消勾选「使用README文件初始化仓库」	勾选会导致后续推送冲突（新手必避坑）

点击「创建」，生成远程仓库，页面将显示仓库地址（如https://gitee.com/host_brace/car_sound_simulation_control.git），复制该地址备用。

3.2 步骤2：本地项目准备（过滤无用文件）

本地项目中通常包含编译产物、临时文件等无用内容，需通过.gitignore文件过滤，避免占用仓库空间：

进入本地项目文件夹（如car_sound_simulation_control）；
新建「文本文档」，重命名为.gitignore（注意前缀有小数点，Windows提示"更改扩展名会导致文件不可用"时点击「是」）；

打开.gitignore，粘贴以下通用配置（适配绝大多数项目，PlatformIO/VSCode项目专用）：

复制代码

# 编译产物
.pio/
.piolibdeps/
.env/
# 编辑器配置
.vscode/
.idea/
# 二进制文件
*.bin
*.elf
*.hex
# 系统临时文件
Thumbs.db
desktop.ini
.DS_Store
# 日志文件
*.log
*.tmp

保存并关闭文件，确保该文件与src、platformio.ini等核心文件同级。

3.3 步骤3：初始化本地Git仓库

让Git开始管理你的本地项目：

进入本地项目文件夹，右键空白处选择「Git Bash Here」；
执行初始化命令：
bash 复制代码
```
git init
```
执行成功后，文件夹会生成隐藏的.git目录（Windows需开启"显示隐藏文件"才能看到），代表本地仓库创建完成。

3.4 步骤4：添加并提交本地文件

将本地项目文件纳入Git版本控制：

执行命令，添加所有文件到暂存区（.表示当前文件夹所有文件）：
bash 复制代码
```
git add .
```
- 若只想添加特定文件，可替换为git add 文件名（如git add src/main.cpp）；
执行提交命令，给本次提交添加备注（备注需清晰，便于后续追溯）：
bash 复制代码
```
git commit -m "初始化：基于ESP32的车载声浪模拟控制系统毕设项目"
```
执行成功后，会显示"x files changed, xxx insertions(+)"，代表文件已提交到本地仓库。

3.5 步骤5：关联远程Gitee仓库

将本地仓库与Gitee远程仓库建立连接：

执行关联命令（替换为你在3.1步骤复制的仓库地址）：
bash 复制代码
```
git remote add origin https://gitee.com/你的用户名/仓库名.git
```
- 示例：git remote add origin https://gitee.com/host_brace/car_sound_simulation_control.git；

验证关联是否成功：

bash 复制代码

git remote -v

若输出以下内容（无拼写错误、无特殊字符），代表关联成功：

复制代码

origin  https://gitee.com/host_brace/car_sound_simulation_control.git (fetch)
origin  https://gitee.com/host_brace/car_sound_simulation_control.git (push)

3.6 步骤6：推送本地代码到Gitee

最后一步，将本地提交的代码上传到云端仓库：

执行推送命令（适配新版Git的main分支）：
bash 复制代码
```
git push -u origin main
```
- 若你的本地分支是master（旧版Git），则执行git push -u origin master；
首次推送会弹出登录窗口，输入你的Gitee账号密码（或验证码），点击「登录」；
等待执行完成，若显示"Branch 'main' set up to track remote branch 'main' from 'origin'."，代表推送成功！

四、验证上传结果

打开Gitee远程仓库页面，刷新后即可看到本地项目的所有文件（如src、platformio.ini、.gitignore）；
检查文件完整性：确认核心代码文件存在，且.pio、.vscode等无用文件未被上传；
后续修改代码后，只需重复以下3条命令即可同步更新：
bash 复制代码
```
git add .
git commit -m "修改说明（如：修复声浪模拟模块bug）"
git push
```

五、新手必避的5个坑及解决方案

坑1：推送时提示"src refspec master does not match any"

原因：本地分支是main，却推送至master分支（名称不匹配），或未执行git commit（无提交记录）；
解决方案：推送命令改为git push -u origin main，或先执行git add .+git commit -m "备注"。

坑2：提示"remote origin already exists"

原因：重复执行了git remote add origin命令，远程仓库别名已存在；
解决方案：先删除旧关联，再重新添加：
bash 复制代码
```
git remote rm origin
git remote add origin 你的仓库地址.git
```

坑3：远程地址含特殊字符（如`--https://gitee.com/...`）

原因：复制仓库地址时不小心复制了页面特殊符号；
解决方案：删除错误关联，重新复制Gitee仓库页面「克隆/下载」中的HTTPS地址，再执行关联命令。

坑4：拼写错误（`oringin`代替`origin`）

原因：远程仓库别名拼写错误（origin是标准别名，意为"源头"）；
解决方案：删除错误别名，重新关联：
bash 复制代码
```
git remote rm oringin
git remote add origin 你的仓库地址.git
```

坑5："Repository not found"报错

原因：仓库地址错误（用户名/仓库名拼写错误），或未登录Gitee账号；
解决方案：核对仓库地址中的用户名和仓库名，确保与Gitee一致；重新登录Gitee后重试。

六、进阶技巧（毕设/团队协作必备）

6.1 仓库权限管理（毕设防抄袭）

保持仓库「私有」：进入Gitee仓库→「管理」→「基本信息」→「仓库可见性」选择私有；
添加协作者（给导师/同学授权）：仓库→「管理」→「协作者」→「添加协作者」，输入对方Gitee用户名/邮箱，选择「读」权限（仅查看，不修改）。

6.2 生成临时访问链接（临时分享）

场景：答辩前给评委临时查看代码，无需添加协作者；
操作：仓库→「克隆/下载」→「生成临时访问令牌」→ 设置有效期（如1天）和「只读」权限→ 生成链接并分享。

6.3 分支管理（多版本开发）

新建开发分支（避免污染主分支）：

bash 复制代码

git branch dev  # 创建dev分支
git checkout dev  # 切换到dev分支

开发完成后合并到主分支：

bash 复制代码

git checkout main  # 切换回主分支
git merge dev  # 合并dev分支代码
git push  # 推送合并后的代码

七、总结

本地项目上传Gitee的核心流程可概括为：安装Git→配置关联→创建远程仓库→本地初始化→提交文件→推送同步。新手只需严格按照步骤操作，避开别名拼写、分支名称、仓库地址这3类高频错误，就能顺利完成上传。

对于毕设项目，建议保持仓库私有，通过协作者授权给导师查看，既保证代码安全，又方便后续答辩和修改。如果遇到具体报错，可根据错误信息定位到本文「新手避坑」部分，或留言交流解决方案～

如果觉得本文有用，欢迎点赞、收藏、转发给需要的同学！📚

从零到一：本地项目上传Gitee完整指南（新手避坑版）