VS Code 连接自建 Gitea：现有项目推送、拉取与日常使用完整教程

本文适用于已经通过 Docker 部署好 Gitea，并希望使用 VS Code 管理代码的场景。
示例环境：

Gitea 地址：http://100.66.1.1:2000

本地系统：Windows

开发工具：Visual Studio Code

Git 远程名称：gitea

一、准备工作

在开始之前，需要确认以下条件已经满足：

Gitea 已经正常运行。
浏览器能够访问 Gitea。
Windows 已经安装 Git。
VS Code 已经安装。
已经拥有一个 Gitea 用户账号。

浏览器访问：

http://100.66.1.1:2000

检查 Git 是否已经安装：

git --version

正常情况下会显示类似：

git version 2.x.x.windows.x

如果提示无法识别 git 命令，需要先安装 Git for Windows，并重新启动 VS Code。

二、在 Gitea 创建空仓库

右上角“+” → 新建仓库

填写仓库名称，例如：

AquaControlAI

如果本地已经存在完整项目，创建仓库时建议：

不勾选“初始化仓库”
不创建 README
不添加 .gitignore
不添加许可证

这样可以避免本地仓库与远程仓库出现无关联提交历史。

创建完成后，复制 HTTP 仓库地址，例如：

http://100.66.1.1:2000/用户名/AquaControlAI.git

三、在 VS Code 打开现有项目

在 VS Code 中选择：

文件 → 打开文件夹

打开现有项目目录。

也可以直接在 PowerShell 中进入项目目录：

cd "E:\Vibe Coding\AquaControlAI"
code .

打开 VS Code 终端：

终端 → 新建终端

快捷键：

Ctrl + `

四、检查本地项目是否已经是 Git 仓库

在 VS Code 终端中执行：

git status

1. 已经是 Git 仓库

如果显示类似：

On branch main

说明项目已经初始化过 Git，可以直接配置远程仓库。

2. 还不是 Git 仓库

如果显示：

fatal: not a git repository

执行：

git init
git branch -M main

设置 Git 提交用户名和邮箱：

git config --global user.name "你的名称"
git config --global user.email "你的邮箱"

将文件加入版本管理并创建第一次提交：

git add .
git commit -m "初始化项目"

五、配置 Gitea 远程仓库

先查看当前远程仓库：

git remote -v

情况一：没有任何远程仓库

添加 Gitea：

git remote add gitea http://100.66.1.1:2000/用户名/AquaControlAI.git

检查配置：

git remote -v

应该看到类似：

gitea  http://100.66.1.1:2000/用户名/AquaControlAI.git (fetch)
gitea  http://100.66.1.1:2000/用户名/AquaControlAI.git (push)

情况二：已经存在 GitHub、Gitee 或其他 origin

如果希望保留原远程仓库，建议新增一个名为 gitea 的远程地址：

git remote add gitea http://100.66.1.1:2000/用户名/AquaControlAI.git

以后可以分别推送：

git push origin main

表示推送到原仓库。

git push gitea main

表示推送到自建 Gitea。

情况三：远程地址配置错误

修改 Gitea 地址：

git remote set-url gitea http://100.66.1.1:2000/用户名/AquaControlAI.git

六、第一次推送现有项目

确认当前分支：

git branch --show-current

如果当前分支不是 main，可以改名：

git branch -M main

第一次推送：

git push -u gitea main

参数说明：

-u

表示将本地 main 分支和远程 gitea/main 建立跟踪关系。

设置完成后，后续可以直接执行：

git push

七、使用访问令牌进行 HTTP 认证

第一次通过 HTTP 推送时，Git 可能要求输入用户名和密码。

建议不要直接使用 Gitea 登录密码，而是使用个人访问令牌。

进入 Gitea：

头像 → 设置 → 应用 → 管理访问令牌

创建一个令牌，例如：

名称：VSCode-Windows

令牌至少需要仓库读写权限。

生成后立即复制保存，因为令牌通常只显示一次。

Git 提示输入凭据时：

Username：Gitea 用户名
Password：个人访问令牌

终端输入令牌时不会显示字符或星号，这是正常现象。

Windows 通常会通过凭据管理器保存认证信息，后续不需要重复输入。

八、从 Gitea 克隆项目到 VS Code

如果要在另一台电脑上拉取项目，可以使用克隆操作。

方法一：使用 VS Code 图形界面

按下：

Ctrl + Shift + P

输入并选择：

Git: Clone

粘贴仓库地址：

http://100.66.1.1:2000/用户名/AquaControlAI.git

选择本地保存目录，等待克隆完成后打开项目。

方法二：使用终端

git clone http://100.66.1.1:2000/用户名/AquaControlAI.git
cd AquaControlAI
code .

九、日常提交和推送流程

推荐每次修改代码后按照以下顺序操作。

1. 查看修改内容

git status

2. 拉取远程最新代码

git pull

多人协作时，更推荐：

git pull --rebase

--rebase 可以减少无意义的合并提交，但遇到冲突时需要手动处理。

3. 将修改加入暂存区

添加全部修改：

git add .

也可以只添加指定文件：

git add app.py
git add frontend/src/App.vue

4. 创建提交

git commit -m "feat: 完成历史数据查询功能"

常见提交类型：

feat: 新增功能
fix: 修复问题
docs: 修改文档
refactor: 重构代码
style: 调整格式
test: 增加测试
chore: 构建或工具调整

5. 推送到 Gitea

git push

完整流程：

git pull --rebase
git status
git add .
git commit -m "feat: 完成历史数据趋势分析"
git push

十、通过 VS Code 图形界面操作

VS Code 左侧点击：

源代码管理

基本操作流程：

修改代码。
打开“源代码管理”。
点击文件旁边的 +，加入暂存区。
在输入框中填写提交说明。
点击“提交”。
点击“同步更改”或“推送”。

VS Code 的“同步更改”通常会执行：

先拉取远程更新，再推送本地提交

在重要项目中，建议仍然先在终端执行：

git pull --rebase

确认无冲突后再推送。

十一、拉取远程代码

只获取远程更新但不合并：

git fetch gitea

查看远程分支：

git branch -r

拉取并合并当前分支：

git pull

明确指定远程和分支：

git pull gitea main

使用 rebase：

git pull --rebase gitea main

十二、推送所有分支和标签

如果本地仓库包含多个分支：

git push gitea --all

推送全部标签：

git push gitea --tags

查看本地分支：

git branch

查看标签：

git tag

十三、新建并推送开发分支

不要长期直接在 main 分支开发。

创建功能分支：

git checkout -b feature/history-page

或者使用新版命令：

git switch -c feature/history-page

开发完成后：

git add .
git commit -m "feat: 完成历史数据页面"
git push -u gitea feature/history-page

然后可以在 Gitea 网页中创建 Pull Request，将功能分支合并到 main。

十四、解决常见错误

1. `remote gitea already exists`

表示已经存在名为 gitea 的远程地址。

查看：

git remote -v

修改地址：

git remote set-url gitea http://100.66.1.1:2000/用户名/AquaControlAI.git

2. `src refspec main does not match any`

通常表示：

当前没有 main 分支
项目还没有任何提交

执行：

git add .
git commit -m "初始化项目"
git branch -M main
git push -u gitea main

3. `Authentication failed`

检查以下内容：

Gitea 用户名是否正确
是否使用个人访问令牌
访问令牌是否具有仓库写权限
仓库地址是否正确

可以在 Windows 中删除旧凭据：

控制面板
→ 凭据管理器
→ Windows 凭据

删除与以下地址有关的凭据：

100.66.1.1:2000

然后重新执行：

git push

4. `rejected non-fast-forward`

表示远程分支存在本地没有的提交。

先拉取：

git pull --rebase gitea main

解决冲突后：

git add .
git rebase --continue
git push

如果远程仓库在创建时自动生成了 README，而本地已有完整历史，也可能出现无关联历史：

git pull gitea main --allow-unrelated-histories

解决冲突并提交后，再推送：

git add .
git commit -m "合并远程初始化内容"
git push

5. `unable to rewind rpc post data`

可能出现类似错误：

error: unable to rewind rpc post data - try increasing http.postBuffer
error: RPC failed; curl 65 seek callback returned error 1
send-pack: unexpected disconnect while reading sideband packet

先检查远程是否已经收到提交：

git rev-parse main
git ls-remote gitea refs/heads/main

如果两边提交哈希一致，说明已经推送成功。

如果不一致，可以针对当前仓库增大 HTTP 缓冲区：

git config --local http.postBuffer 10485760

重新推送：

git push -u gitea main

仍然失败时，可提高到 50 MiB：

git config --local http.postBuffer 52428800
git push -u gitea main

6. `Everything up-to-date`

表示当前分支没有新的本地提交需要推送。

检查状态：

git status

查看最近提交：

git log --oneline -10

确认本地和远程提交：

git rev-parse main
git ls-remote gitea refs/heads/main

十五、配置 `.gitignore`

在推送项目之前，应该排除不需要进入仓库的内容。

例如：

# Python
__pycache__/
*.pyc
.venv/
venv/

# Node.js
node_modules/
dist/
build/

# IDE
.vscode/
.idea/

# 环境变量
.env
.env.*
!.env.example

# 日志
*.log
logs/

# 数据库
*.db
*.sqlite
*.sqlite3

# 临时文件
tmp/
temp/

# 系统文件
.DS_Store
Thumbs.db

不要将以下敏感信息提交到仓库：

数据库密码
API 密钥
Token
云服务访问密钥
邮箱密码
生产环境配置
私钥文件

可以使用：

.env.example

保存变量名称和示例配置，将真实 .env 文件加入 .gitignore。

十六、可选：改用 SSH 拉取和推送

HTTP 方式可以正常使用，但 SSH 配置完成后通常不需要重复输入访问令牌。

生成 SSH 密钥：

ssh-keygen -t ed25519 -C "你的邮箱"

查看公钥：

Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

在 Gitea 中添加公钥：

头像 → 设置 → SSH/GPG 密钥 → 添加密钥

测试连接：

ssh -p 2222 git@100.66.1.1

SSH 仓库地址类似：

ssh://git@100.66.1.1:2222/用户名/AquaControlAI.git

修改现有远程地址：

git remote set-url gitea ssh://git@100.66.1.1:2222/用户名/AquaControlAI.git

以后仍然使用：

git pull
git push

十七、推荐的实际开发流程

开始开发前

git switch main
git pull --rebase gitea main
git switch -c feature/new-feature

开发完成后

git status
git add .
git commit -m "feat: 完成新功能"
git push -u gitea feature/new-feature

合并完成后

git switch main
git pull --rebase gitea main
git branch -d feature/new-feature

十八、常用 Git 命令速查

# 查看状态
git status

# 查看远程仓库
git remote -v

# 查看当前分支
git branch --show-current

# 查看所有分支
git branch -a

# 拉取代码
git pull

# 拉取并使用 rebase
git pull --rebase

# 添加全部修改
git add .

# 创建提交
git commit -m "提交说明"

# 推送代码
git push

# 查看提交记录
git log --oneline -10

# 查看文件差异
git diff

# 新建分支
git switch -c feature/test

# 切换分支
git switch main

# 推送新分支
git push -u gitea feature/test

# 查看远程信息
git remote show gitea

十九、总结

VS Code 连接自建 Gitea 后，日常使用方式与 GitHub、Gitee 基本一致。

对于已有项目，核心命令是：

git remote add gitea http://100.66.1.1:2000/用户名/AquaControlAI.git
git push -u gitea main

日常开发流程是：

git pull --rebase
git add .
git commit -m "提交说明"
git push

通过自建 Gitea，可以将代码仓库保存在自己的 NAS 中，同时继续使用 VS Code 完成克隆、拉取、提交、分支管理和推送等标准 Git 操作。