将仓库与本地文件夹建立关联

概述

本节介绍如何将 Gitee（或 GitHub）远程仓库与本地项目文件夹建立关联。在实际开发中，这是使用 Git 进行版本管理的第一步。学习完成后，您将能够：

通过 IDE 图形界面克隆远程仓库到本地
在本地初始化项目后，通过 CLI/API 创建远程仓库并关联
根据项目阶段选择合适的关联方式

前置要求

在开始本节之前，请确保：

已完成 Git 版本控制基础的学习
已安装 Trae IDE 或 Qoder
已拥有一个 Gitee 或 GitHub 账号
已配置好 Git 凭证（参见”Gitee 国内代码托管平台使用指南”）

两种关联方式

将远程仓库与本地文件夹关联有两种常见路径，根据你的项目阶段选择合适的方式：

方法一：通过 IDE 克隆远程仓库（适合从零开始）

这是最直接的方式——远程仓库已存在，你只需要把它拉到本地。

在 Trae / Qoder 中操作步骤：

打开 Trae（或 Qoder），点击 “新建窗口”（或使用菜单 File → New Window）
在欢迎页面中，找到并点击 “克隆仓库”（Clone Repository）
在弹出的输入框中，粘贴 Gitee 仓库地址：
```
https://gitee.com/你的用户名/仓库名.git
```
选择本地存放路径（例如 ~/Projects/），点击确认
IDE 会自动执行 git clone，完成后打开项目文件夹

提示：如果你使用 SSH 方式（已配置 SSH 密钥），可以粘贴 SSH 地址：
git@gitee.com:你的用户名/仓库名.git

克隆完成后，本地文件夹就自动与 Gitee 远程仓库建立了关联，后续的 push、pull 操作都会自动同步。

方法二：先创建本地项目，再创建远程仓库并关联（适合已有项目）

如果你已经在本地开发了项目，想把它推送到 Gitee 上进行托管，可以按以下步骤操作：

步骤 1：在本地初始化 Git 仓库

# 进入你的项目目录
cd ~/Projects/my-iot-project

# 初始化 Git 仓库
git init

# 添加所有文件并提交
git add .
git commit -m "初始提交"

步骤 2：通过 CLI 创建 Gitee 远程仓库

无需打开浏览器，可以直接通过 Gitee API 在命令行中创建远程仓库。

首先，确保你有一个 Gitee 的 Personal Access Token（生成方法参见”Gitee 国内代码托管平台使用指南”中的”Mac 上使用 PAT 进行认证”小节）。

# 使用 Gitee API 创建远程仓库
# 将 YOUR_TOKEN 替换为你的 PAT，my-iot-project 替换为你的仓库名
curl -X POST https://gitee.com/api/v5/user/repos \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "YOUR_TOKEN",
    "name": "my-iot-project",
    "description": "我的 IoT 项目",
    "private": true,
    "auto_init": false
  }'

提示：你也可以让 AI 助手帮你完成这一步。在 Trae / Qoder 的 Agent 模式中，直接说：

“帮我在 Gitee 上创建一个名为 my-iot-project 的私有仓库”

AI 会自动调用 CLI 工具或 API 完成创建。如果尚未安装相关工具，AI 会引导你安装。

步骤 3：将本地仓库与远程仓库关联

# 添加远程仓库地址
git remote add origin https://gitee.com/你的用户名/my-iot-project.git

# 推送本地代码到远程仓库
git branch -M main
git push -u origin main

执行完成后，你的本地项目就已经与 Gitee 远程仓库关联，后续可以正常使用 git push / git pull 同步代码。

补充：如果你更喜欢使用 SSH 协议，关联命令为：
Terminal window
git remote add origin git@gitee.com:你的用户名/my-iot-project.git

两种方法对比

对比项	方法一：IDE 克隆	方法二：本地项目 + CLI 创建
适用场景	远程仓库已存在，从零开始开发	本地已有代码，需要上传到远程
操作入口	IDE 图形界面	终端命令行 / AI 助手
是否需要浏览器	不需要（仓库已在网页上创建）	不需要（通过 API 创建）
核心命令	`git clone`	`git init` + `git remote add` + `git push`

验证关联是否成功

无论使用哪种方式，都可以通过以下命令验证本地与远程的关联是否正确：

# 查看远程仓库地址
git remote -v
# 应输出类似：
# origin  https://gitee.com/你的用户名/my-iot-project.git (fetch)
# origin  https://gitee.com/你的用户名/my-iot-project.git (push)

# 测试拉取远程信息
git fetch origin
# 无报错即表示关联成功

小结

通过本小节的学习，您已经掌握了：

技能	关键操作
IDE 克隆仓库	新建窗口 → 克隆仓库 → 粘贴地址 → 选择路径
CLI 创建远程仓库	Gitee API `curl` 调用，无需浏览器
本地关联远程	`git remote add origin` + `git push -u origin main`
验证关联	`git remote -v` 和 `git fetch origin`

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →