在日常开发中，我们通常会使用 Git 管理代码版本，并将代码上传到 GitHub 进行备份、协作和版本追踪。
本文介绍如何在 VS Code 中将本地项目上传到 GitHub，同时说明代码更新后如何再次提交，以及常见错误的解决方法。
一、准备工作
开始之前，需要准备以下环境：
可以在终端执行以下命令，检查 Git 是否已经安装：
git –version
如果能够看到类似下面的输出，说明 Git 已经安装成功：
git version 2.34.1
Ubuntu 系统可以使用以下命令安装 Git：
sudo apt update
sudo apt install git
安装完成后，重新打开 VS Code。
二、在 GitHub 创建远程仓库
登录 GitHub，点击右上角的加号，选择：
New repository
填写仓库名称，例如：
construction-safety-agent
如果本地已经存在完整项目，第一次创建远程仓库时，建议不要勾选以下选项：
- Add a README file
- Add .gitignore
- Choose a license
否则，远程仓库会提前产生提交记录，第一次上传时可能需要额外处理代码合并问题。
创建完成后，GitHub 会生成远程仓库地址，例如：
https://github.com/你的用户名/仓库名.git
复制该地址，后面需要使用。
三、在 VS Code 中打开本地项目
启动 VS Code，选择：
文件 → 打开文件夹
选择需要上传的项目根目录。
然后打开 VS Code 内置终端：
终端 → 新建终端
也可以使用快捷键：
Ctrl + `
查看当前路径：
pwd
查看当前目录中的文件：
ls
需要确保当前终端位于项目根目录，而不是项目的某个子目录。
四、配置 Git 用户信息
第一次使用 Git 时，需要配置用户名和邮箱。
执行以下命令：
git config –global user.name "你的用户名"
git config –global user.email "你的邮箱"
查看配置结果：
git config –global –list
这里的用户名和邮箱会记录在 Git 提交信息中。
五、初始化本地 Git 仓库
进入项目根目录后，执行：
git init
该命令会在当前项目中创建一个隐藏的 .git 目录，用于保存版本记录。
可以使用以下命令检查当前状态：
git status
如果项目已经初始化过 Git，执行 git init 不会删除原来的代码和提交记录。
六、配置 .gitignore
上传代码前，建议先创建 .gitignore 文件，排除不需要上传的文件。
对于 Python、目标检测、大模型、RAG 和 Agent 项目，可以使用下面的配置：
# Python 缓存
__pycache__/
*.pyc
*.pyo
*.pyd
# Python 虚拟环境
venv/
.venv/
env/
# Conda 环境
.conda/
# VS Code 配置
.vscode/
# 环境变量和密钥
.env
*.env
# 日志文件
*.log
logs/
# 缓存目录
.cache/
.pytest_cache/
# 模型权重
*.gguf
*.bin
*.pt
*.pth
*.onnx
*.safetensors
# 数据集
data/
dataset/
datasets/
# 系统文件
.DS_Store
Thumbs.db
需要特别注意，不要将以下敏感信息上传到公开仓库：
- API Key；
- 数据库密码；
- SSH 私钥；
- 服务器账号密码；
- Token；
- .env 文件中的真实配置。
可以创建一个 .env.example 文件，只保留配置名称：
RAG_API_KEY=your_api_key
VISION_BASE_URL=http://127.0.0.1:8081/v1
SAFETY_RAG_URL=http://127.0.0.1:8000
这样其他人可以了解项目需要哪些环境变量，又不会泄露真实密钥。
七、第一次提交本地代码
查看项目文件状态：
git status
将所有文件加入暂存区：
git add .
再次查看状态：
git status
创建第一次提交：
git commit -m "初始项目代码"
其中，-m 后面的内容是本次提交说明。
提交说明应尽量写清楚本次修改内容，例如：
git commit -m "修复 RAG 服务连接问题"
八、关联 GitHub 远程仓库
将本地项目与 GitHub 仓库关联：
git remote add origin https://github.com/你的用户名/仓库名.git
查看远程仓库地址：
git remote -v
正常情况下会看到：
origin https://github.com/你的用户名/仓库名.git (fetch)
origin https://github.com/你的用户名/仓库名.git (push)
如果提示：
remote origin already exists
说明当前项目已经配置过名为 origin 的远程仓库。
可以查看现有地址：
git remote -v
如果地址不正确，可以修改：
git remote set-url origin https://github.com/你的用户名/仓库名.git
九、将代码上传到 GitHub
将当前分支名称修改为 main：
git branch -M main
第一次上传代码：
git push -u origin main
其中：
- origin 是远程仓库名称；
- main 是远程分支名称；
- -u 会建立本地分支与远程分支之间的关联。
第一次执行后，后续通常只需要运行：
git push
如果 GitHub 弹出浏览器登录页面，按照提示完成授权即可。
上传完成后，刷新 GitHub 仓库页面，就可以看到本地代码。
十、完整的首次上传命令
首次上传代码时，可以按照下面的顺序执行：
cd /你的项目路径
git init
git config –global user.name "你的用户名"
git config –global user.email "你的邮箱"
git add .
git commit -m "初始项目代码"
git branch -M main
git remote add origin https://github.com/你的用户名/仓库名.git
git push -u origin main
需要注意，Git 用户名和邮箱只需要配置一次，不必每个项目都重新配置。
十一、代码更新后如何再次上传
本地代码修改后，不需要重新执行 git init，也不需要重新添加远程仓库。
只需要执行以下命令：
git status
git add .
git commit -m "说明本次修改内容"
git push
这会在原有代码基础上增加一条新的提交记录，而不是清空之前的代码。
GitHub 仓库页面默认显示最新版本，但之前的版本仍然保存在提交历史中。
查看提交记录：
git log –oneline
输出示例：
a2b35cd 增加图像质量预检功能
712cc8a 增加目标检测接口
05fd882 初始化项目代码
因此，正常的 git push 不会删除之前的提交记录。
十二、只提交指定文件
git add . 会添加当前目录下所有发生变化的文件。
如果只想上传某个文件，可以指定文件路径：
git add app.py
git commit -m "更新 app.py"
git push
同时提交多个文件：
git add app.py config.yaml README.md
git commit -m "更新接口、配置和使用说明"
git push
也可以提交某个目录：
git add src/
git commit -m "更新 src 目录中的代码"
git push
提交前建议执行：
git status
确认没有把模型、数据集、日志或密钥文件加入提交。
十三、远程仓库有更新时的正确操作
如果仓库可能被其他人修改过，或者自己在另一台电脑上提交过代码，建议上传前先拉取远程更新：
git pull –rebase origin main
然后再提交本地修改：
git status
git add .
git commit -m "更新代码"
git push origin main
一种更安全的日常操作顺序是：
git status
git add .
git commit -m "说明本次修改"
git pull –rebase origin main
git push origin main
这里使用 –rebase，可以尽量保持提交历史整洁，避免产生不必要的合并提交。
如果本地还没有任何提交，不能直接执行部分 rebase 操作，应先完成本地提交。
十四、使用 VS Code 图形界面提交代码
除了终端命令，也可以使用 VS Code 左侧的“源代码管理”功能。
操作步骤如下：
如果是第一次将项目上传到 GitHub，仍然建议先使用终端完成远程仓库关联：
git remote add origin https://github.com/你的用户名/仓库名.git
git branch -M main
git push -u origin main
完成第一次关联后，后续可以直接使用 VS Code 图形界面提交和推送。
十五、常见问题及解决方法
1. 提示 git: command not found
错误信息：
git: command not found
说明系统没有安装 Git。
Ubuntu 安装命令：
sudo apt update
sudo apt install git
安装完成后检查：
git –version
2. 提示 nothing to commit
执行提交命令后出现：
nothing to commit, working tree clean
说明 Git 没有检测到新的修改。
可以检查：
git status
常见原因包括：
- 文件修改后没有保存；
- 修改内容与原文件相同；
- 文件被 .gitignore 忽略；
- 当前终端不在正确的项目目录中。
先在 VS Code 中按下：
Ctrl + S
保存文件，再执行：
git status
3. 提示远程仓库已存在
错误信息：
remote origin already exists
先查看远程地址：
git remote -v
如果远程地址错误，执行：
git remote set-url origin https://github.com/你的用户名/仓库名.git
如果需要删除后重新添加：
git remote remove origin
git remote add origin https://github.com/你的用户名/仓库名.git
4. 推送时提示 rejected
错误信息可能类似：
Updates were rejected because the remote contains work
说明远程仓库中存在本地没有的提交。
先拉取远程内容：
git pull –rebase origin main
然后重新推送：
git push origin main
如果远程仓库和本地仓库分别独立创建了提交，例如远程仓库中已经有 README，可以执行：
git pull origin main –allow-unrelated-histories
处理冲突并提交后，再执行：
git push origin main
5. 出现代码冲突
当本地和远程修改了同一个文件的相同位置时，可能会出现冲突。
冲突文件中通常会看到：
<<<<<<< HEAD
本地代码
=======
远程代码
>>>>>>> main
需要手动决定保留哪些内容，并删除以下冲突标记：
<<<<<<< HEAD
=======
>>>>>>> main
修改完成后执行：
git add .
git rebase –continue
最后推送：
git push origin main
如果不想继续当前 rebase，可以取消：
git rebase –abort
6. GitHub 密码认证失败
GitHub 的 HTTPS 推送通常不能直接使用账号密码。
可以使用以下方式认证：
- VS Code 浏览器登录授权；
- Personal Access Token；
- SSH 密钥。
对于普通开发者，使用 VS Code 弹出的浏览器授权最方便。
7. 文件过大无法上传
模型权重、数据集和压缩包通常体积较大，不适合直接上传到普通 Git 仓库。
常见的大文件包括：
model.gguf
weights.pt
model.safetensors
dataset.zip
建议将其加入 .gitignore：
*.gguf
*.pt
*.pth
*.safetensors
*.zip
models/
weights/
dataset/
datasets/
如果确实需要管理大文件，可以使用 Git LFS：
git lfs install
git lfs track "*.gguf"
git lfs track "*.pt"
git lfs track "*.safetensors"
然后提交 .gitattributes：
git add .gitattributes
git commit -m "配置 Git LFS"
git push
对于深度学习项目，更推荐只在 GitHub 中保存：
- 源代码；
- 配置文件；
- 环境依赖文件；
- README；
- 小型示例数据；
- 模型下载地址；
- 数据集获取方式。
不要直接上传完整模型权重和完整训练数据集。
十六、撤销错误操作
1. 取消暂存文件
如果执行了：
git add .
但发现添加了不应该提交的文件，可以取消暂存：
git restore –staged 文件名
取消所有暂存：
git restore –staged .
2. 撤销本地文件修改
恢复某个文件到最近一次提交状态：
git restore 文件名
例如：
git restore app.py
该操作会丢弃尚未提交的修改，执行前需要确认修改内容不再需要。
3. 修改最近一次提交说明
如果提交信息写错，但还没有推送，可以执行：
git commit –amend -m "新的提交说明"
4. 查看历史版本
查看简洁提交历史：
git log –oneline
查看某个提交的具体修改：
git show 提交ID
5. 恢复某个文件的历史版本
将某个文件恢复到指定提交：
git restore –source=提交ID 文件名
恢复后，需要重新提交：
git add app.py
git commit -m "恢复 app.py 的历史版本"
git push
十七、推荐的日常 Git 工作流程
个人项目更新代码时，可以使用以下流程：
git status
git add .
git commit -m "说明本次修改内容"
git pull –rebase origin main
git push origin main
如果确认远程仓库没有其他更新，也可以简化为：
git add .
git commit -m "说明本次修改内容"
git push
团队协作时，建议在开始修改代码前先执行：
git pull –rebase origin main
修改完成后再执行：
git status
git add .
git commit -m "说明本次修改内容"
git pull –rebase origin main
git push origin main
十八、总结
使用 VS Code 将代码上传到 GitHub，核心流程可以概括为：
git init
git add .
git commit -m "初始化项目代码"
git remote add origin 远程仓库地址
git branch -M main
git push -u origin main
代码更新后的核心流程是：
git add .
git commit -m "本次修改说明"
git push
Git 每次提交都会生成一条新的版本记录。正常使用 git add、git commit 和 git push，不会清除之前的提交历史。
对于 Python、深度学习、大模型和 Agent 项目，还需要重点注意：
掌握这些基本操作后，就可以在 VS Code 中完成项目初始化、版本管理、代码更新、远程备份和团队协作。
