1. 前期准备把工具链装齐1.1 Git 安装这一步真的别再跳过版本验证了很多新手拿到教程第一件事就是装 Git装完直接往下走。我的建议是先装再验证验证通过再继续。因为后续八成报错都跟“Git 没装好”或者“装的是老版本”有关尤其是 Windows 环境路径配置、PATH 环境变量、换行符转换这三样最容易出问题。Windows 用户直接去官网下载 Git for Windows一路 Next 就行。有两点要留意一是安装过程中会让你选调整 PATH 的方式建议选“Git from the command line and also from 3rd-party software”这样你在 IDEA、VS Code 里也能直接调用 Git 命令二是换行符转换建议选“Checkout Windows-style, commit Unix-style line endings”这是最不容易出幺蛾子的方案团队协作时尤其重要。macOS 上我一般推荐用 Homebrew 装命令是brew install git比去官网下载省心后续升级也方便。Linux 就更简单了sudo apt install git或者yum install git都行但要注意不同发行版的默认版本差异老系统自带的 Git 版本可能偏低建议配个官方 PPA 或源码编译。装完之后打开终端Windows 可以用 Git Bash输入git --version如果能正常输出类似git version 2.40.0.windows.1的版本号说明装好了。这里补一句大实话如果你打算用 IDEA 的 GitLab 插件做图形化操作Git 版本最好在 2.20 以上太老会遇到一堆莫名其妙的证书和协议兼容问题。我见过不少同事用 IDEA 连接 GitLab 时提示 “login failed. check api token or gitlab version”排查到最后发现本地 Git 还是 1.x 古董版本升级就好了。接着做两件基础配置这也是入职新公司第一天必做的事git config --global user.name 你的名字 git config --global user.email 你的公司邮箱这里有个细节很多人忽视用户名的邮箱必须和 GitLab 账号邮箱一致不然 commit 提交之后头像和姓名会显示不出来在项目记录里看起来就像个匿名机器人。如果是公司内部 GitLab统一用企业邮箱个人邮箱提交有时候还过不了代码审查的门禁规则。1.2 GitLab 端要准备的三样东西本地工具准备好了接下来去 GitLab 网页端做准备工作。很多新手一上来就直接拿git push去怼结果要么报认证失败要么提示权限不足就是因为 GitLab 端有三个东西没准备好。第一要有一个空白项目仓库。在 GitLab 首页点“New project”可以选“Create blank project”。项目名建议和本地文件夹名字一致比如本地叫hello-serviceGitLab 上也叫hello-service免得后面对应不上。Visiblity 建议选 Private除非你非要公开给全世界看。创建成功之后页面会显示一个远程仓库地址有 HTTPS 和 SSH 两种格式这个地址后面要用先复制保存好。第二个人访问令牌Personal Access Token。这玩意儿本质上就是你的密码替代品但比密码更安全也更灵活。在 GitLab 右上角头像 → Edit Profile → Access Tokens 里创建名字随意比如local-push过期时间建议设置一个合理的周期别图省事选“永不过期”。权限勾选时请务必包含write_repository和read_repository如果需要通过 API 操作再勾api。生成后令牌只会显示一次必须马上复制保存关掉页面就再也看不到了。后续用 HTTPS 方式推送时用户名填你的 GitLab 用户名密码填这串令牌注意不是填 GitLab 登录密码。第三SSH Key如果用 SSH 方式的话。SSH 是很多老开发者偏好的方式因为配置好之后可以免密码推送不用每次输令牌。如何在 GitLab 里添加 SSH Key我们放到下一章详细展开这里你先知道有这个东西就够了。2. 上传前必须想明白的几个问题2.1 先确定协议HTTPS 还是 SSH别混着用本地项目上传 GitLab 之前第一步不是执行命令而是想清楚用哪种协议。Git 远程仓库地址有两种常见格式https://gitlab.example.com/group/project.git和gitgitlab.example.com:group/project.git。两者都能完成上传但体验差异很大。HTTPS 方式的优点是上手门槛低不需要配置密钥只要账号密码或令牌就能推送适合临时机器、公共电脑、或者不想折腾 SSH 的同学。缺点是每次 push 都要输用户名和令牌除非配置凭证缓存输多了确实烦。Windows 下 Git 默认会走 Git Credential Manager第一次输过之后会在 Windows 凭据管理器里缓存起来后面确实不用重复输但换个网络环境或换台机器又得重新认证。SSH 方式的优点是一劳永逸公钥放到 GitLab 之后推送拉取全程无感没有密码环节也没有 token 过期烦恼。缺点是首次配置需要多花几分钟理解公钥私钥原理。我的建议是个人主力开发机和公司电脑用 SSH临时环境、客户现场机器用 HTTPS 加令牌。这俩不要混着用一个仓库你从 A 电脑用 HTTPS 克隆到 B 电脑用 SSH 推送本地 Git 会提示“detected dubious ownership”或直接认证失败虽然能通过重新关联解决但没必要踩这种坑。所以一开始就把远程地址决定好别中途换。2.2 分支和忽略文件决定你以后会不会想骂人上传前必须看一下本地项目里面有没有一堆不该传的文件。我见过最经典的翻车现场一个 Java 项目的target目录、IDEA 自动生成的.idea文件夹、本地配置的application-local.yml全部被git add .一股脑传了上去。传到 GitLab 之后整个仓库体积直接膨胀到几百 MB后面每次拉取代码慢得像乌龟爬。正确做法是在上传之前先创建.gitignore文件。不同技术栈有不同的忽略清单比如 Java 项目要忽略target/、*.class、.idea/、*.imlNode 项目要忽略node_modules/、.envPython 项目要忽略__pycache__/、.venv/。原则很简单构建产物、依赖目录、IDE 配置、本地环境配置、日志文件一律不传。如果项目里没有.gitignore我通常先去 GitHub 的 gitignore 仓库找对应语言的标准模板再根据自己项目情况补充几行。这一步做不好上传之后清理历史记录可是个大工程尤其是公司 GitLab 开启了存储配额限制的时候。分支命名也要一开始就想清楚。GitLab 默认分支在新建项目时一般叫main或master本地初始化后我习惯显式指定主分支名git branch -m main后续功能开发就按feature/xxx、bugfix/xxx的格式建分支。一开始把分支规范定下来后面代码审查、发布流程都会顺得多。2.3 令牌与权限Developer 到底能不能推 master这个坑我见得太多了。有同事配好 SSH、也拿到令牌了push 的时候还是被拒绝提示You are not allowed to push code to protected branches on this project。这是因为 GitLab 默认把main或master设成了受保护分支Protected Branch只有 Maintainer/Owner 角色能直接推送Developer 角色的权限默认是“允许合并请求”但不能直接 push 保护分支。解决方法有两个。一个是在 GitLab 项目设置 → Repository → Protected Branches 里把允许推送的角色调整为 “Developers Maintainers”。另一个更符合团队规范的做法是不要直接推 main而是开功能分支推上去然后创建 Merge Request合并请求走代码审查流程。如果你在一个人维护的小项目里我建议直接改保护分支设置省心如果是公司多人协作的项目老老实实走 MR别跟流程对着干。3. 保姆级实操本地项目完整上传 GitLab3.1 用 Git Bash 一行一行完成初始化假设你的项目在本地目录E:\workspace\hello-service现在我要把它完整传到 GitLab 的hello-service仓库里。先进入项目目录cd /e/workspace/hello-service注意 Windows 下 Git Bash 的路径格式和 CMD 不一样盘符要改成小写并且不带冒号用/e/...这种写法。接着初始化本地仓库git init执行完这步之后你可能会看到Initialized empty Git repository的提示。此时如果运行git status会发现项目文件都还没被跟踪状态显示为 untracked。下一步是把项目所有文件加入暂存区git add .git add .表示把当前目录下所有未被忽略的文件加入暂存。如果你不确定.gitignore能不能挡住不该传的文件先别急着 add运行git status看一眼里面会列出即将被跟踪的文件清单。如果发现target/、.idea/之类的内容混在里面赶紧回去把.gitignore补好再重新 add。然后提交到本地仓库git commit -m Initial commit: hello-service project提交成功会显示一个 commit hash比如[main (root-commit) 8f2a1d9]。到这里本地仓库已经有了第一次提交接下来就是要把它和 GitLab 远程仓库关联起来。3.2 首次推送从 fatal 到成功现在把本地仓库和 GitLab 上的远程仓库建立关联。假设你的 GitLab 远程仓库地址是 SSH 格式那么执行git remote add origin gitgitlab.example.com:group/hello-service.git如果之前不小心已经 add 过了会提示fatal: remote origin already exists.这是很常见的报错解决方法git remote remove origin然后重新 add。可以用git remote -v查看当前关联的远程地址确认无误后首次推送git push -u origin main-u参数的意思是把本地 main 分支和远程 main 分支建立跟踪关系以后直接敲git push就能推送不用再加分支名。这里集中说一下首次推送最常见的几种结局报错情况常见原因解决思路Permission denied (publickey)SSH 密钥没配好检查公钥是否添加到 GitLab私钥是否被 ssh-agent 加载Authentication failed令牌错误或没配令牌确认用户名和 Personal Access Tokenfatal: repository not found仓库不存在或地址写错检查远程地址中项目路径是否正确是否漏掉了 group 层级Protected branch分支保护限制改用 MR 流程或调整保护设置LFS objects are missing启用了 LFS 但本地上传不全安装 Git LFS 并手动追踪大文件首次推送成功的标志是看到类似To gitlab.example.com:group/hello-service.git和* [new branch] main - main的提示。推送完成之后去 GitLab 网页刷新项目页面代码就出现了。3.3 IDEA 图形化上传适合不熟命令行的同学如果你用的也是 IntelliJ IDEA不习惯敲命令也可以全程图形化完成上传。IDEA 的做法其实是在命令外面包了一层壳但我发现很多同学上传失败都是因为没搞懂界面上每一步在干什么。首先在 IDEA 里打开项目确认项目根目录能看得到一个Git菜单。如果没有 VCS 菜单需要在File → Settings → Version Control里把项目关联到 Git或者直接用 VCS 菜单下的Enable Version Control Integration选择 Git 即可。此时你的项目就被纳入了 Git 管理。然后创建本地仓库并提交打开Git → Commit面板左侧窗口会列出所有变更文件把要提交的文件勾选上在 Commit Message 输入提交说明点 “Commit” 按钮。注意第一次是Commit提交到本地千万别直接点 “Commit and Push”万一远程还没配置好报错一堆你都不知道问题出在哪儿。接下来配置远程仓库菜单栏Git → Manage Remotes点加号Name 填originURL 填你在 GitLab 复制的 HTTPS 或 SSH 地址。确定保存后再做一次 Commit然后Git → Push。若是首次推送且远程地址是 HTTPS之前没有缓存认证信息IDEA 会弹出登录框问的是Login to GitLab这时候如果你填的是账号密码那就是踩了前面说的坑——密码位置要填 Personal Access Token而且 IDEA 还要求你通过 Token 登录而不是旧密码登录。这里插一个高频报错“login failed. GitLab versions older than 14.0 are not supported. Log in via Git if the version is older.”意思是 IDEA 新版插件不再支持 GitLab 14.0 之前的 API服务端版本太老就会弹这个。如果你公司用的是老版本 GitLab最快捷的方案是用命令行完成 push不要在 IDEA 里走登录流程另一种思路是升级 GitLab但这事属于运维权限个人做不了主。用小版本合适的 IDEA 也能绕过我实际测试过 2023 后的版本都会弹这个提示。3.4 上传之后的日常操作拉取、提交、合并、回滚上传不是终点接下去的每一天你都要跟 Git 打交道。我挑几个频率高的日常操作快速过一遍。拉取远程更新git pull先拉取别人的提交再处理本地冲突。任何时候写代码前我都会先跑一下git status看当前分支状态再git pull同步远程。不要一上来就闷头写写完一推发现冲突一堆处理起来心态容易崩。日常提交git add . git commit -m fix: 修复登录接口超时问题 git push提交信息建议按团队约定写一般用feat:新功能、fix:修复、docs:文档、refactor:重构前缀别人看历史记录一目了然。合并分支git merge feature/login如果你在main分支上要合并feature/login先切到 main再执行 merge。合并可能出现冲突打开冲突文件后里面会有、、这类标记手动保留需要的代码再重新 add 和 commit冲突就解决了。撤销上一次 commitgit commit --amend -m 新的提交信息这个命令适合修正上一次提交的信息千万不要用它去修改已经推送过的提交因为这会重写历史导致远端已经存在的 commit 被换成新 hash协作时其他人拉取会报错。如果是只想撤销本地提交但保留修改用git reset --soft HEAD~1。实际工作中我更推荐用git revert去回滚已经推送的提交虽然会多出一条“反向提交”记录但它不会篡改历史团队协作更安全。4. 常见问题与排查实录4.1 认证报错token 与 GitLab 版本兼容前文提到过 IDEA 连 GitLab 报login failed. check api token or gitlab version这里再单独把认证相关的报错汇总一下因为这是我在评论区被问得最多的一类。场景 AIDEA 提示login failed. GitLab versions older than 14.0 are not supported。原因很明确新版 IDEA 内置的 GitLab 插件通过新版 API 认证GitLab 老版本不支持。解决方案有三种一改用命令行完成 push/pull二用浏览器访问 GitLab 并创建 Token 后在 IDEA 里选择通过 Git 凭据方式登录而不是走 GitLab API 登录三申请升级 GitLab 服务端。注意这个报错跟你的 Git 版本无关别在本地来回重装 Git浪费感情。场景 BHTTPS 推送报fatal: Authentication failed。先确认用户名是否正确再确认密码位置填的是Personal Access Token而不是 GitLab 登录密码。如果用的是自己的 GitLab 账号在命令行输入密码时建议先复制好 Token右键粘贴即可Git Bash 的粘贴是 ShiftInsert。若还不行清除 Windows 凭据管理器里残留的旧凭据控制面板 → 凭据管理器 → Windows 凭据 → 删除与git:https://gitlab.example.com相关的条目再重新推一次。场景 Cgit clone私有仓库时需要反复输入密码。这是 Git 默认没有帮你缓存凭据导致的执行一次git config --global credential.helper store或者用更安全的 cache 模式设置过期时间git config --global credential.helper cache --timeout36004.2 SSH 认证失败与多密钥管理SSH 方式如果报Permission denied (publickey)按下面几步排查。第一确认公钥已添加到 GitLab把本地生成的~/.ssh/id_ed25519.pub内容复制到 GitLab 的 SSH Keys 设置页。第二确认私钥被当前 ssh-agent 加载ssh-add -l如果列表里面没有你的私钥执行ssh-add ~/.ssh/id_ed25519。第三测试连接受否正常ssh -T gitgitlab.example.com成功会返回欢迎你的用户名提示。如果你同时管理多个 Git 平台账号比如公司 GitLab 和 GitHub 各有一套密钥建议给每个平台单独配置 Host方法是在~/.ssh/config里添加Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_gitlab Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github这样切换平台时不会出现用错密钥导致认证失败的问题。顺带说一句GitLab 容器部署如果修改过 SSH 端口你需要在ssh -T测试和git clone时显式指定端口地址格式会变成ssh://gitgitlab.example.com:2222/group/project.git这一点部署私有 GitLab 的同学要特别留意。4.3 分支保护与权限不足怎么绕前文说了 Developer 默认推不了保护分支。实际工作中还会遇到另外几种权限相关报错。一是git push时提示You are not allowed to upload packs这通常是你的角色没有写权限联系项目 Maintainer 提升权限即可。二是403 Forbidden除了权限问题也可能是你用的 Token 权限不够比如只勾了read_repository没勾write_repository。三是推送被要求做 MR这通常不是报错而是 GitLab 配置了 push 规则强制走合并请求流程按提示新建 MR 就好。我自己的习惯是项目初期一个人开发把 main 分支保护改成 Developers can push一旦加入第二个开发者马上恢复保护分支走 MR 代码审查流程。这个转变最好在项目一开始就做好约定中途切流程会打断团队节奏。4.4 其他常见错误与小技巧集合这里把各种零碎的报错汇总成一张速查表都是我实测或帮人排查过的高频问题报错或现象原因解决办法fatal: not a git repository (or any of the parent directories): .git当前目录不是 Git 仓库确认是否执行过git init或是否在错误的目录层级里执行命令fatal: remote origin already exists.远程仓库已关联git remote -v查看git remote remove origin后重新添加git clone卡住不动仓库过大或 LFS 对象太多先git clone --depth 1做浅克隆或检查网络启用 LFS 的项目需git lfs installgit lfs fetch失败LFS 服务端地址或认证问题检查.lfsconfig服务端地址用 Token 认证公司内网 LFS 需要走内网域名提交后 GitLab 上头像不显示本地配置邮箱与 GitLab 不一致git config user.email改成 GitLab 绑定邮箱并删掉旧提交重新提交fatal: refusing to merge unrelated histories两段独立历史库强行合并确认确实需要合并后执行git pull origin main --allow-unrelated-historiesIDEA Push 按钮置灰没有 commit 记录存在先 Commit 一次再 Pushgit push后本地 commit 找不到了可能被误 reset 或切分支git reflog查看操作历史用git reset --hard hash找回再补充一个实用小技巧如果项目里有超大文件不小心提交上去了网上说的“先删再提交”并不能把它从 Git 历史里抹掉。真正的清理需要用到git filter-branch或git filter-repo但这个操作会重写历史属于高危操作涉及团队仓库时一定要先跟所有人对齐、备份完整仓库后再做。你用 GitLab 自带的项目归档功能也能关闭旧仓库避免额外占用存储空间。5. 关于 Git LFS 和公司内网 GitLab 的几个额外提醒很多公司用 GitLab 做资产托管会开启 Git LFSLarge File Storage来管理二进制大文件比如设计图、安装包、测试数据。LFS 的原理是用一个文本指针替换真实文件真实文件单独存到服务端 LFS 存储区这样仓库本体不会膨胀。如果你要上传的项目里带有视频、压缩包、模型文件我建议从一开始就启用 LFS而不是等仓库变大再来迁移。启用方式很简单先安装 Git LFSgit lfs install然后在项目里声明要跟踪的大文件类型git lfs track *.zip git lfs track *.tar.gz git lfs track *.mp4跟踪规则会写入.gitattributes文件记得把.gitattributes一起提交否则别人拉取仓库时不会知道这些文件该走 LFS。这里有个坑我踩过某次我在没有执行git lfs install的机器上直接 clone 一个带 LFS 文件的仓库结果大文件全部变成几百字节的文本指针文件还以为项目被劫持了。后来在项目根目录执行git lfs install再git lfs pull才把真实文件拉下来。关于公司内网部署的 GitLab还有几点要提醒。第一如果服务端是用 Docker 容器部署要注意 GitLab 本身可能占用的内存和端口默认会监听 80 和 443也会额外占用 2222 之类的 SSH 端口本地配置远程地址时要跟运维确认清楚端口号。第二GitLab 版本会不断推送安全补丁如果你负责自己团队的 GitLab 实例要关注官方的安全公告和漏洞修复版本高危漏洞的修复方案一般官方会直接给出升级路径千万别一直停在老版本上裸奔。第三内网 GitLab 的域名解析万一出问题git clone会出现找不到主机名的报错这种时候先去检查 hosts 解析别急着怀疑自己的 SSH 密钥。6. 最后分享一个让我少走弯路的习惯我做了这么多年开发上传本地项目到这个动作本身只需要几分钟真正能把人卡住的往往不是命令不熟而是对整个流程背后的逻辑不熟。比如为什么提交代码要写清楚 message为什么 master 不能随便 push为什么忽略文件要一开始就配好这些看似“流程”的东西本质上是避免未来某一天自己或者团队成员因为一个低级失误浪费半天时间。根据我个人的经验最值得养成的三个习惯是第一第一次写代码前就把 .gitignore 配好哪怕你的项目是空的第二每次 push 之前先 git status 看一眼确认要提交的东西就是你想要的第三遇到看不懂的报错优先把完整报错信息复制到搜索引擎里搜Git 的命令行报错其实已经写得非常直白大部分时候答案就在你面前。如果你正在为公司搭建 GitLab 或者维护老仓库建议花点时间把所有分支保护、MR 规则、LFS 配额设置一次到位后面维护成本会低很多。这期保姆级教程到这儿。如果你从零开始一步步跟着走现在应该已经成功把本地项目传上了 GitLab并且知道接下来每天怎么提交、怎么解决常见的认证和权限报错了。