企业官网建设流程全解析

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-service，GitLab 上也叫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和git@gitlab.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/、*.iml；Node 项目要忽略node_modules/、.env；Python 项目要忽略__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. 保姆级实操：本地项目完整上传 GitLab

3.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 git@gitlab.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就能推送，不用再加分支名。

这里集中说一下首次推送最常见的几种结局：

首次推送成功的标志是看到类似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 填origin，URL 填你在 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，冲突就解决了。

撤销上一次 commit：

git 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，这里再单独把认证相关的报错汇总一下，因为这是我在评论区被问得最多的一类。

场景 A：IDEA 提示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，浪费感情。

场景 B：HTTPS 推送报fatal: Authentication failed。先确认用户名是否正确，再确认密码位置填的是Personal Access Token而不是 GitLab 登录密码。如果用的是自己的 GitLab 账号，在命令行输入密码时建议先复制好 Token，右键粘贴即可（Git Bash 的粘贴是 Shift+Insert）。若还不行，清除 Windows 凭据管理器里残留的旧凭据：控制面板 → 凭据管理器 → Windows 凭据 → 删除与git:https://gitlab.example.com相关的条目，再重新推一次。

场景 C：git clone私有仓库时需要反复输入密码。这是 Git 默认没有帮你缓存凭据导致的，执行一次：

git config --global credential.helper store

或者用更安全的 cache 模式，设置过期时间：

git config --global credential.helper 'cache --timeout=3600'

4.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 git@gitlab.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://git@gitlab.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 其他常见错误与小技巧集合

这里把各种零碎的报错汇总成一张速查表，都是我实测或帮人排查过的高频问题：

再补充一个实用小技巧：如果项目里有超大文件不小心提交上去了，网上说的“先删再提交”并不能把它从 Git 历史里抹掉。真正的清理需要用到git filter-branch或git filter-repo，但这个操作会重写历史，属于高危操作，涉及团队仓库时一定要先跟所有人对齐、备份完整仓库后再做。你用 GitLab 自带的项目归档功能也能关闭旧仓库，避免额外占用存储空间。

5. 关于 Git LFS 和公司内网 GitLab 的几个额外提醒

很多公司用 GitLab 做资产托管，会开启 Git LFS（Large File Storage）来管理二进制大文件，比如设计图、安装包、测试数据。LFS 的原理是用一个文本指针替换真实文件，真实文件单独存到服务端 LFS 存储区，这样仓库本体不会膨胀。如果你要上传的项目里带有视频、压缩包、模型文件，我建议从一开始就启用 LFS，而不是等仓库变大再来迁移。

启用方式很简单，先安装 Git LFS：

git 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，并且知道接下来每天怎么提交、怎么解决常见的认证和权限报错了。