本文介绍将本地项目上传至 Gitee 的完整流程，涵盖 Git 安装配置、远程仓库创建、本地初始化、文件提交及代码推送步骤。重点解析了分支名称不匹配、远程地址重复、拼写错误等常见报错的解决方案，并提供了.gitignore 过滤无用文件的最佳实践，适合毕设项目及团队协作场景。
在日常开发或毕业设计中，将本地项目上传到代码托管平台是必备技能。Gitee（码云）作为国内优质的 Git 托管服务，不仅访问速度快，还支持私有仓库、协作者管理等实用功能，特别适合国内开发者和学生使用。本文将以「ESP32 车载声浪模拟控制系统」毕设项目为例，从环境准备到代码推送，一步步教你完成本地项目上传，同时揭秘新手常踩的坑及解决方案。
在开始操作前，先搞懂 3 个关键概念，避免后续 confusion：
main（新版 Git）或 master（旧版 Git），推送时需保证本地分支与远程分支名称一致。Git 是上传项目的基础工具，支持 Windows/macOS/Linux 全平台：
Win+R 输入 cmd，执行命令 git --version，若显示 git version x.x.x 则安装成功。让 Git 识别你的 Gitee 身份，避免后续推送权限报错：
git config --global --list，能看到上述配置信息即生效。执行以下命令（替换为你的 Gitee 用户名和注册邮箱）：
# 配置用户名（Gitee 个人主页显示的昵称）
git config --global user.name "你的 Gitee 用户名"
# 配置邮箱（注册 Gitee 时使用的邮箱）
git config --global user.email "你的 Gitee 注册邮箱"
以本地 car_sound_simulation_control（ESP32 毕设项目）为例，完整上传流程如下：
https://gitee.com/host_brace/car_sound_simulation_control.git），复制该地址备用。填写仓库信息（关键配置如下，其余默认）：
| 配置项 | 推荐值 | 注意事项 |
|---|---|---|
| 仓库名称 | 与本地项目文件夹一致（如 car_sound_simulation_control） | 小写 + 下划线，避免空格、中文、特殊符号 |
| 仓库介绍 | 简要描述项目（如'基于 ESP32 的车载声浪模拟控制系统毕设'） | 便于后续检索和他人理解 |
| 仓库类型 | 私有（毕设项目首选） | 防止代码被抄袭，后续可按需改为公开 |
| 初始化仓库 | 取消勾选「使用 README 文件初始化仓库」 | 勾选会导致后续推送冲突（新手必避坑） |
本地项目中通常包含编译产物、临时文件等无用内容，需通过 .gitignore 文件过滤，避免占用仓库空间：
car_sound_simulation_control）；.gitignore（注意前缀有小数点，Windows 提示'更改扩展名会导致文件不可用'时点击「是」）；src、platformio.ini 等核心文件同级。打开 .gitignore，粘贴以下通用配置（适配绝大多数项目，PlatformIO/VSCode 项目专用）：
# 编译产物
.pio/
.piolibdeps/
.env/
# 编辑器配置
.vscode/
.idea/
# 二进制文件
*.bin
*.elf
*.hex
# 系统临时文件
Thumbs.db
desktop.ini
.DS_Store
# 日志文件
*.log
*.tmp
让 Git 开始管理你的本地项目：
.git 目录（Windows 需开启'显示隐藏文件'才能看到），代表本地仓库创建完成。执行初始化命令：
git init
将本地项目文件纳入 Git 版本控制：
git add 文件名（如 git add src/main.cpp）；执行命令，添加所有文件到暂存区（.表示当前文件夹所有文件）：
git add .
执行成功后，会显示'x files changed, xxx insertions(+)'，代表文件已提交到本地仓库。接着执行提交命令，给本次提交添加备注（备注需清晰，便于后续追溯）：
git commit -m "初始化：基于 ESP32 的车载声浪模拟控制系统毕设项目"
将本地仓库与 Gitee 远程仓库建立连接：
执行关联命令（替换为你在 3.1 步骤复制的仓库地址）：
git remote add origin https://gitee.com/你的用户名/仓库名.git
示例：git remote add origin https://gitee.com/host_brace/car_sound_simulation_control.git；
若输出以下内容（无拼写错误、无特殊字符），代表关联成功：
origin https://gitee.com/host_brace/car_sound_simulation_control.git (fetch)
origin https://gitee.com/host_brace/car_sound_simulation_control.git (push)
验证关联是否成功：
git remote -v
最后一步，将本地提交的代码上传到云端仓库：
master（旧版 Git），则执行 git push -u origin master；首次推送会弹出登录窗口，输入你的 Gitee 账号密码（或验证码），点击「登录」； 等待执行完成，若显示'Branch 'main' set up to track remote branch 'main' from 'origin'.'，代表推送成功！
执行推送命令（适配新版 Git 的 main 分支）：
git push -u origin main
src、platformio.ini、.gitignore）；.pio、.vscode 等无用文件未被上传；后续修改代码后，只需重复以下 3 条命令即可同步更新：
git add .
git commit -m "修改说明（如：修复声浪模拟模块 bug）"
git push
main，却推送至 master 分支（名称不匹配），或未执行 git commit（无提交记录）；git push -u origin main，或先执行 git add .+git commit -m "备注"。git remote add origin 命令，远程仓库别名已存在；git remote rm origin
git remote add origin 你的仓库地址.git
–https://gitee.com/...）oringin代替origin）origin是标准别名，意为'源头'）；git remote rm origin
git remote add origin 你的仓库地址.git
开发完成后合并到主分支：
git checkout main # 切换回主分支
git merge dev # 合并 dev 分支代码
git push # 推送合并后的代码
新建开发分支（避免污染主分支）：
git branch dev # 创建 dev 分支
git checkout dev # 切换到 dev 分支
本地项目上传 Gitee 的核心流程可概括为：安装 Git→配置关联→创建远程仓库→本地初始化→提交文件→推送同步。新手只需严格按照步骤操作，避开别名拼写、分支名称、仓库地址这 3 类高频错误，就能顺利完成上传。
对于毕设项目，建议保持仓库私有，通过协作者授权给导师查看，既保证代码安全，又方便后续答辩和修改。如果遇到具体报错，可根据错误信息定位到本文「新手避坑」部分，或留言交流解决方案～
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online