Windows 下 GitLab 完整使用指南

本文覆盖Git 客户端安装、SSH 配置、GitLab 账号 / 仓库操作、Git 命令实战、GitLab Runner 部署、常见问题附可直接复制的命令与权威博文链接适合从入门到日常开发使用。一、Windows 上 GitLab 的两种使用场景1. 作为开发者连接远程 GitLab 仓库最常用安装 Git 客户端通过 Git Bash / Git GUI 操作本地仓库推送 / 拉取代码到公司 / 个人 GitLab 服务器gitlab.com 或自建 GitLab。无需在 Windows 本地搭建 GitLab 服务仅需客户端工具。2. 作为管理员在 Windows 本地搭建 GitLab 服务GitLab 官方不支持原生 Windows 安装仅支持 Linux 系统。Windows 搭建需通过Docker Desktop运行 Linux 容器部署 GitLab 服务。二、场景一Windows 开发者使用 GitLab核心流程一安装 Git 客户端必备1. 下载 Git官网https://git-scm.com/download/win选择 64-bit 版本Windows 10/11 主流下载安装包。2. 安装配置关键步骤双击安装包一路Next关键配置Choosing the default editor used by Git推荐选Visual Studio Code或 Notepad方便编辑提交信息。Adjusting your PATH environment选Git from the command line and also from 3rd-party software让 Git 命令在 CMD、PowerShell、Git Bash 都可用。Configuring the line ending conversions选Checkout Windows-style, commit Unix-style line endings适配跨平台换行。最后一步勾选 Launch Git Bash安装完成后自动打开 Git Bash。3. 验证安装打开 Git Bash输入命令git --version显示版本号如git version 2.45.1.windows.1即安装成功。4. 初始配置全局用户名 / 邮箱与 GitLab 账号一致git config --global user.name 你的GitLab用户名 git config --global user.email 你的GitLab注册邮箱 # 查看配置 git config --global --list二配置 SSH 密钥免密登录 GitLab推荐1. 生成 SSH 密钥打开 Git Bash执行命令一路回车无需设置密码ssh-keygen -t ed25519 -C 你的GitLab邮箱密钥默认存储路径C:\Users\你的用户名\.ssh\生成两个文件id_ed25519私钥保密、id_ed25519.pub公钥上传 GitLab。2. 复制公钥内容cat ~/.ssh/id_ed25519.pub # 或直接打开文件复制全部内容3. 上传公钥到 GitLab登录 GitLab 网页https://gitlab.com 或公司自建地址。点击右上角头像 → Settings → SSH Keys。在Key输入框粘贴公钥Title填标识如 “Windows 办公电脑”点击Add key。4. 验证 SSH 连接# 替换为你的GitLab域名公司自建则填公司地址 ssh -T gitgitlab.com出现Welcome to GitLab, 你的用户名!即成功。三GitLab 网页端基础操作账号 / 仓库1. 注册 / 登录 GitLab官网注册https://gitlab.com/users/sign_up公司自建 GitLab联系管理员获取账号。2. 创建远程仓库登录后点击右上角New project。填写Project name仓库名、Visibility LevelPrivate 私有 / Internal 内部 / Public 公开。点击Create project完成创建。3. 仓库基本信息获取仓库地址创建后在仓库首页点击Clone复制SSH 地址如gitgitlab.com:username/project.git。四Git 命令实战本地 ↔ GitLab 远程仓库1. 克隆远程仓库到本地首次操作# 进入目标目录如 D:\Projects cd /d/Projects # 克隆仓库替换为你的SSH地址 git clone gitgitlab.com:username/project.git # 进入仓库目录 cd project2. 本地开发 提交到 GitLab# 1. 查看文件状态 git status # 2. 添加文件到暂存区. 代表所有文件 git add . # 3. 提交到本地仓库填写提交信息 git commit -m feat: 新增功能模块 # 4. 推送到GitLab远程仓库默认main分支 git push origin main3. 拉取远程最新代码多人协作必备git pull origin main4. 分支操作GitLab 开发核心# 查看所有分支 git branch -a # 创建并切换到新分支 git checkout -b feature/login # 推送新分支到GitLab git push origin feature/login # 合并分支如合并到main git checkout main git merge feature/login # 删除本地分支 git branch -d feature/login # 删除远程分支 git push origin --delete feature/login5. 提交历史与回退# 查看提交日志 git log --oneline # 回退到指定版本保留修改 git reset --soft 提交哈希值 # 回退到指定版本丢弃修改谨慎使用 git reset --hard 提交哈希值五GitLab 高级操作Merge Request、Issue、CI/CD1. Merge RequestMR代码合并本地开发完成后推送分支到 GitLab。进入 GitLab 仓库 →Merge Requests → New merge request。选择源分支你的开发分支和目标分支main填写标题与描述点击Create merge request。等待代码 review通过后点击Merge合并代码。2. Issue任务管理仓库 →Issues → New issue创建任务、分配负责人、设置截止时间关联 MR 实现任务闭环。3. CI/CDGitLab RunnerWindows 部署GitLab Runner 是执行 CI/CD 任务的代理Windows 部署步骤GitLab创建目录C:\GitLab-Runner。下载 64 位 Runner 二进制https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe重命名为gitlab-runner.exe放入目录。以管理员身份打开 PowerShell执行powershellcd C:\GitLab-Runner # 注册Runner替换为你的GitLab地址、token .\gitlab-runner.exe register --url https://gitlab.com --registration-token 你的项目token # 安装为系统服务 .\gitlab-runner.exe install # 启动服务 .\gitlab-runner.exe start仓库根目录创建.gitlab-ci.yml配置 CI/CD 流程如构建、测试、部署。三、场景二Windows 本地搭建 GitLab 服务Docker 方式1. 安装 Docker Desktop官网下载https://www.docker.com/products/docker-desktop/安装后启动切换为Linux 容器模式右下角 Docker 图标右键切换。2. 拉取并运行 GitLab 容器打开 PowerShell执行命令# 创建持久化存储卷 docker volume create gitlab-config docker volume create gitlab-logs docker volume create gitlab-data # 启动GitLab容器替换hostname为你的域名/IP docker run --detach --hostname gitlab.local --publish 443:443 --publish 80:80 --publish 22:22 --name gitlab --restart always --volume gitlab-config:/etc/gitlab --volume gitlab-logs:/var/log/gitlab --volume gitlab-data:/var/opt/gitlab gitlab/gitlab-ce:latest3. 访问与初始登录等待容器启动约 5-10 分钟浏览器访问http://localhost。初始管理员账号root密码查看命令docker exec -it gitlab grep Password: /etc/gitlab/initial_root_password登录后立即修改初始密码。四、Windows 下 GitLab 常见问题与解决SSH 连接失败检查公钥是否正确上传、Git Bash 路径是否正确、防火墙是否放行 22 端口。git push 报错 Permission denied确认 SSH 密钥配置正确或使用 HTTPS 地址输入 GitLab 账号密码。Docker 启动 GitLab 报 502 Bad Gateway等待容器完全启动或增加内存分配Docker 设置 → Resources → Memory 调至 4GB 以上。Git Bash 中文乱码Git Bash 右键 → Options → Text → 字符集选UTF-8。