本地项目上传 Gitee 完整操作指南

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

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

1. 进入本地项目文件夹（如 car_sound_simulation_control）；
2. 新建「文本文档」，重命名为 .gitignore（注意前缀有小数点，Windows 提示'更改扩展名会导致文件不可用'时点击「是」）；
3. 保存并关闭文件，确保该文件与 src、platformio.ini 等核心文件同级。

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

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

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

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

1. 进入本地项目文件夹，右键空白处选择「Git Bash Here」；
2. 执行成功后，文件夹会生成隐藏的 .git 目录（Windows 需开启'显示隐藏文件'才能看到），代表本地仓库创建完成。

执行初始化命令：

git init

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

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

• 若只想添加特定文件，可替换为 git add 文件名（如 git add src/main.cpp）；

2. 执行成功后，会显示"x files changed, xxx insertions(+)"，代表文件已提交到本地仓库。

执行提交命令，给本次提交添加备注（备注需清晰，便于后续追溯）：

git commit -m "初始化：基于 ESP32 的车载声浪模拟控制系统毕设项目"

执行命令，添加所有文件到暂存区（.表示当前文件夹所有文件）：

git add .

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

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

• 示例：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

执行关联命令（替换为你在 3.1 步骤复制的仓库地址）：

git remote add origin https://gitee.com/你的用户名/仓库名.git

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

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

• 若你的本地分支是 master（旧版 Git），则执行 git push -u origin master；

2. 首次推送会弹出登录窗口，输入你的 Gitee 账号密码（或验证码），点击「登录」；
3. 等待执行完成，若显示"Branch 'main' set up to track remote branch 'main' from 'origin'."，代表推送成功！

执行推送命令（适配新版 Git 的 main 分支）：

git push -u origin main

四、验证上传结果

1. 打开 Gitee 远程仓库页面，刷新后即可看到本地项目的所有文件（如 src、platformio.ini、.gitignore）；
2. 检查文件完整性：确认核心代码文件存在，且 .pio、.vscode 等无用文件未被上传；

后续修改代码后，只需重复以下 3 条命令即可同步更新：

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 命令，远程仓库别名已存在；

解决方案：先删除旧关联，再重新添加：

git remote rm origin
git remote add origin 你的仓库地址.git

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

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

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

• 原因：远程仓库别名拼写错误（origin是标准别名，意为'源头'）；

解决方案：删除错误别名，重新关联：

git remote rm origin
git remote add origin 你的仓库地址.git

坑 5："Repository not found"报错

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

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

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

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

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

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

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

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

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

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

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

七、总结

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

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