使用 VS Code 将本地项目上传至 Gitee 仓库指南

使用 VS Code 将本地项目上传至 Gitee 仓库指南

在现代软件开发流程中，版本控制是不可或缺的一环。Gitee（码云）作为国内领先的代码托管平台，为开发者提供了稳定、快速的 Git 服务。本文将详细介绍如何使用 Visual Studio Code（VS Code）将本地项目代码上传至 Gitee 仓库，涵盖从环境配置、初始化仓库到推送代码的完整流程。

一、准备工作

1. 安装必要工具

• Git：确保系统已安装 Git。可通过终端运行 git --version 或 git -v 验证是否安装成功。
• VS Code：下载并安装 Visual Studio Code。
• Gitee 账号：前往 Gitee 官网 注册账号（如尚未注册）。

2. 安装 VS Code 插件（可选但推荐）

虽然 VS Code 内置了 Git 支持，但以下插件可提升体验：

• GitLens：增强 Git 功能，提供提交历史、代码作者等信息。
• Git Graph：用于可视化，方便后续版本切换。
• GitHub Pull Requests and Issues：虽然名为 GitHub，但对 Gitee 也有一定兼容性（主要用于 PR 管理，非必需）。

注意：Gitee 与 GitHub 在 API 上不完全兼容，因此部分 GitHub 插件可能无法直接用于 Gitee。

二、创建 Gitee 远程仓库

1. 登录 Gitee 账号，点击右上角 '+' → '新建仓库'。
2. 填写仓库名称，选择公开或私有。
3. 不要勾选'使用 README.md 初始化'（如果你已有本地代码），否则后续推送时会因远程存在提交而冲突。
4. 点击 '创建'，记录生成的仓库地址（如 https://gitee.com/yourname/my-project.git）。

三、配置本地 Git 环境

在终端（或 VS Code 内置终端）中执行以下命令：

# 配置全局用户名和邮箱（仅首次需要）
git config --global user.name "你的 Gitee 用户名"
git config --global user.email "你的 Gitee 注册邮箱"

注意：邮箱必须与 Gitee 账号绑定的邮箱一致，否则提交记录可能无法正确关联。

四、在 VS Code 中初始化并上传项目

步骤 1：打开项目文件夹

1. 启动 VS Code。
2. 使用 File → Open Folder 打开你的本地项目目录。

步骤 2：初始化 Git 仓库（如果尚未初始化）

如果项目目录下没有 .git 文件夹，说明尚未初始化 Git：

在 VS Code 中，点击源代码管理，初始化仓库。

或者，打开 VS Code 终端（Ctrl + ~ 或 Terminal → New Terminal），使用命令初始化：

git init

步骤 3：添加文件并提交

1. 在 VS Code 左侧活动栏点击 源代码管理（Source Control） 图标（或按 Ctrl+Shift+G）。
2. 建议先创建 .gitignore 文件，把不需要上传的环境、静态资源等文件排除。
3. 你会看到所有未跟踪的文件列在 'Changes（更改）' 区域。
4. 点击文件旁边的 + 图标（或点击顶部的 + 全选）将文件暂存（Stage）。
5. 在输入框中填写提交信息（如 首次提交），然后按 Ctrl+Enter 提交。

你也可以在终端中执行：

git add .
git commit -m "首次提交"

步骤 4：关联远程 Gitee 仓库

方法 1：使用 SSH 地址通过界面关联

在 Gitee 找到 SSH 地址，粘贴地址，点击回车，再输入一个仓库名字，接着点击发布即可。

方法 2：在终端中执行

替换为你的实际仓库地址：

git remote add origin https://gitee.com/yourname/my-project.git

验证是否添加成功：

git remote -v

应显示：

origin https://gitee.com/yourname/my-project.git (fetch)
origin https://gitee.com/yourname/my-project.git (push)

步骤 5：推送代码到 Gitee

执行推送命令：

git push -u origin main

注意：Gitee 默认分支名可能是 master 或 main，取决于创建仓库时的设置。 如果提示 src refspec main does not match any，尝试查看本地分支名或修改为 master。

首次推送时，VS Code 或系统可能会弹出认证窗口，输入你的 Gitee 账号和密码。（手机号和密码）

⚠️ 重要：自 2021 年起，Gitee（以及 GitHub）不再支持账号密码直接认证。你需要使用 个人访问令牌（Personal Access Token） 代替密码。

如何生成 Gitee 个人访问令牌？

1. 登录 Gitee，进入 设置 → 私人令牌（Private Token）。
2. 点击 '生成新令牌'，填写令牌名称（如 vscode-push），勾选 repo 权限。
3. 点击 '生成'，复制生成的令牌（只显示一次，请妥善保存）。
4. 推送时，用户名填 Gitee 用户名，密码填该令牌。

五、补充问题：处理 .gitignore 遗漏

由于是首次操作，我们可能会忘记创建 .gitignore 文件，或者在上传代码后才发现 .gitignore 文件存在遗漏，导致远程仓库中出现许多不必要的文件。在补充完 .gitignore 文件后，我们需要重新移除对这些文件的跟踪，以确保后续这些被忽略的文件不会上传到远程仓库。

这里因为我们是首次上传进仓库，且是单独开发，所以可以直接全部移除，再重新添加：

git rm -r --cached .
git add .

这表示先取消所有文件的缓存（但保留本地文件），再重新 add，此时 .gitignore 生效，被忽略的文件就不会被加入暂存区。

直接运行提交命令：

git commit -m "移除无用文件，新建 .gitignore"

强制推送：

git push --force origin main # 或者你用的是 master 分支：git push --force origin master

六、总结

通过 VS Code 与 Gitee 的结合，开发者可以高效地进行本地开发与远程协作。整个流程核心在于：

1. 初始化本地 Git 仓库；
2. 创建 Gitee 远程仓库；
3. 关联远程地址；
4. 使用个人访问令牌安全认证；
5. 推送代码。

掌握这一流程后，你不仅能上传新项目，还能轻松管理日常的版本控制与团队协作。