VS Code + Git + Gitea 完全使用教程

前言

本教程适用于使用 VS Code 进行开发，并通过 Git 对接 Gitea（或 GitHub、GitLab 等）代码仓库的场景。从环境配置到日常提交推送，一步步带你上手。

一、VS Code 基础设置

1.1 打开设置文件

按 Ctrl+Shift+P 打开命令面板，输入 Preferences: Open Settings (JSON)，选择它打开设置文件。

1.2 常见设置项

{
    // 关闭 PHP 语法校验（如果本地未安装 PHP 环境）
    "php.validate.enable": false,
    "php.validate.executablePath": "",
    // Git 自动拉取
    "git.autofetch": true,
    // 自动暂存（提交前自动 stash）
    "git.autoStash": true,
    // 自动添加 Signed-off-by 信息
    "git.alwaysSignOff": true,
    // 主题
    "workbench.colorTheme": "Visual Studio Dark"
}

1.3 关闭语言校验提示

如果打开 PHP/Java/Python 等项目时出现 "找不到 XX 安装" 的提示：

1. 按 Ctrl+Shift+P 打开命令面板
2. 输入 Preferences: Open Settings (UI)
3. 搜索对应的语言名称（如 php validate）
4. 取消勾选 XX › Validate: Enable

💡 注意：这些校验只影响代码语法提示，不影响 Git 功能。如果不需要在本地运行项目，完全可以关闭。

二、连接 Gitea 仓库

2.1 获取 Gitea 仓库地址

1. 登录 Gitea，进入目标仓库页面
2. 点击绿色的 Clone 按钮
3. 复制 HTTPS 或 SSH 地址

💡 建议：使用 SSH 地址更安全（需提前配置 SSH 公钥），HTTPS 首次推送需输入账号密码。

2.2 克隆仓库到本地

方式一：命令面板克隆（推荐）

1. 按 Ctrl+Shift+P 打开命令面板
2. 输入并选择 Git: Clone
3. 粘贴 Gitea 仓库地址
4. 选择本地存放文件夹（可自由选择任意位置，如 D:/projects/）
5. VS Code 自动克隆完成，打开文件夹即可

方式二：源代码管理视图克隆

1. 点击左侧 源代码管理 图标（或按 Ctrl+Shift+G）
2. 点击顶部的 克隆仓库 按钮
3. 粘贴仓库地址，选择存放位置

💡 小贴士：建议在选择位置时新建一个以项目名命名的空文件夹再选中，避免代码散落在外层。

三、本地已有项目推送到 Gitea

如果已经在本地写好了代码，想推送到 Gitea 新建的空仓库：

3.1 Gitea 端操作

1. 在 Gitea 点击 创建仓库
2. 填写仓库名称
3. 不要勾选 "使用 README 初始化" 等选项，保持仓库为空
4. 创建成功后复制仓库地址

3.2 VS Code 端操作

1. 打开本地项目文件夹
2. 进入源代码管理视图，点击 初始化仓库（如果尚未初始化）
3. 按 Ctrl+Shift+P → Git: Add Remote
4. 远程名称填 origin，URL 填 Gitea 仓库地址
5. 输入提交说明，点击 ✓ 提交
6. 点击 推送（Push） 按钮上传到 Gitea

四、日常提交与推送

4.1 提交（Commit）到本地

查看改动状态

• 打开源代码管理视图（Ctrl+Shift+G）
• "更改"区域显示所有修改过的文件

提交所有文件

1. 在输入框中填写提交说明（如 "修复登录 bug"）
2. 点击 ✓ 按钮（或按 Ctrl+Enter）
3. 所有改动一次性提交到本地仓库

提交部分文件（分开提交）

如果想分多次提交，每个提交只包含部分文件：

1. 在"更改"列表中，鼠标悬停在某个文件上
2. 点击右侧的 + 号（暂存更改），文件移到"暂存的更改"区域
3. 重复操作，暂存想一起提交的所有文件
4. 输入提交说明，点击 ✓ 提交
5. 剩余文件仍在"更改"列表，可再次提交

示例场景：改了 3 个文件

index.php   → 提交："修复登录验证问题"
style.css   → 提交："优化登录页面样式"  
config.php  → 提交："更新数据库配置"

💡 建议：个人项目可全部提交；团队协作建议分开提交，方便代码审查和回滚。

4.2 推送（Push）到 Gitea

提交完成后，将本地提交推送到远程仓库：

方法一：命令面板

按 Ctrl+Shift+P → 输入 Git: Push → 回车

方法二：底部状态栏

点击 VS Code 底部左侧的 同步图标（循环箭头），同时执行拉取和推送

方法三：源代码管理视图

点击视图顶部的 ... 菜单 → 选择 推送

4.3 首次推送的身份验证

使用 HTTPS 地址克隆时，首次推送会弹出输入框：

• 用户名：Gitea 账号（邮箱或用户名）
• 密码：Gitea 登录密码

输入后 VS Code 会自动保存凭据，后续无需重复输入。

五、常见问题与解决方案

5.1 推送按钮灰色不可点击

原因：没有提交记录

解决：先在源代码管理视图完成提交（Commit）操作

5.2 提示"无法验证，找不到 PHP 安装"

原因：本地未安装 PHP 环境，但 PHP 插件开启了语法校验

解决方案一：关闭校验（不需要运行项目时）

"php.validate.enable": false

解决方案二：配置 PHP 路径（需要运行项目时）

先通过 where php（Windows）或 which php（macOS/Linux）找到 PHP 安装路径，然后在 settings.json 中添加：

"php.validate.executablePath": "C:/xampp/php/php.exe"

5.3 提示"权限被拒绝"

原因：账号密码错误或没有仓库权限

解决：

• 确认 Gitea 账号密码正确
• 确认该仓库已添加你为成员（私有仓库）
• 或改用 SSH 方式克隆

5.4 提示"有冲突"

原因：远程仓库有其他人提交的新代码，与本地改动冲突

解决：

1. 先点击 拉取（Pull） 拉取远程更新
2. VS Code 会标记冲突位置，手动解决冲突
3. 解决后提交合并，再推送

5.5 克隆时找不到想保存的文件夹

解决：VS Code 克隆时一定会弹出系统文件夹选择窗口，可自由浏览选择任意位置。没有默认下载路径，每次克隆都需手动指定。

六、Git 状态颜色速查表

七、快捷键汇总

八、总结

编辑代码 → 源代码管理视图查看改动 → 填写提交说明 → 点击 ✓ 提交 → 点击推送 → 代码上传到 Gitea

核心理念：

• 提交（Commit）：保存到本地仓库，可以随时回滚
• 推送（Push）：上传到远程仓库（Gitea），与团队共享
• 拉取（Pull）：从远程仓库下载最新代码，保持同步

💡 记住："提交"是本地操作，"推送"是网络操作。提交可以频繁做，推送在有完整功能时再做。

本教程适用于 VS Code + Git + Gitea 的基础使用场景，如有其他问题欢迎补充完善。