企业官网建设流程全解析

团队里最近聊得最多的话题，就是“AI 编程助手到底怎么融入我们现有的研发流程”。我自己用的两样东西——一个是在终端里跑的 Claude Code，一个是团队一直在用的 GitLab——刚好是这个问题最典型的两个角色。很多朋友跑来问我：这两个工具到底能不能打通？打通以后是真能提效，还是只是造了个看起来很酷的玩具？这篇教程就把我的实际做法和踩过的坑一次性讲清楚。

先说清楚这是给谁看的。如果你平时用 GitLab 做代码托管和 MR 评审，也愿意在本地装一个命令行 AI 编码工具来辅助写代码、写描述、做代码检查，那么这篇内容对你会有直接帮助。无论你是后端、前端还是 DevOps，只要工作流里绕不开“提交代码 -> 发起合并请求 -> CI 校验 -> 评审反馈”这条链路，下面的方案就都能用得上。

1. 先搞明白：集成到底集成在哪

1.1 Claude Code 不是“IDE 插件”那么简单

很多人第一次听说 Claude Code，脑子里跳出来的画面是“又一个 AI 写代码的 IDE 插件”。这个理解不能说全错，但格局小了。Claude Code 本质上是一个跑在终端里的 AI 编程代理：你可以用自然语言让它“分析一下这个仓库的结构”“把登录接口的单元测试补全”“帮我看下昨天的提交为什么 CI 挂了”。它会自己去读文件、搜索符号、执行 Git 命令、调用外部工具，把一整条任务链做掉，而不是像传统补全工具那样等你敲代码再给提示。

这个定位决定了它和 GitLab 的集成方式也会和普通插件完全不同。我们不是简单地在编辑器里装个扩展然后把代码复制粘贴过去，而是要把 Claude Code 放进真实的开发闭环里：本地写代码、提交分支、发起 MR、在 CI 里做校验、根据评审反馈改代码。只要有一个环节接入了 AI，效率变化都是肉眼可见的。而所有这些环节，恰恰都是 GitLab 的主场。

1.2 一个真实的 GitLab 工作流长什么样

聊集成之前，先把 GitLab 工作流拆开看看。一个典型的项目流程，无论团队大小，往往都绕不开三个环节。

第一个环节是代码托管与分支管理。开发者从主分支切出功能分支，写完代码推到远端，这是最基础的操作。第二个环节是合并请求（MR）评审。开发者在 GitLab 上发起 MR，团队成员在上面查看 diff、发表评论、讨论设计、批准合并。第三个环节是 CI/CD。每次 push 或 MR 创建时，GitLab Runner 自动跑测试、构建、部署流水线，把质量校验交给机器。

集成就是在这些环节里找“动手点”。我在实际项目中把 Claude Code 放在三个位置上：本地提交时用它生成规范的 commit message 和 MR 描述；分支推上去后让它分析代码 diff，自动帮评审人整理变更要点；CI 阶段让它以机器人的身份在 MR 下面留下代码审查建议。把这些点串起来，才是真正意义上的“AI 进入团队工作流”，而不是每个人电脑里单独摆个 AI 助手，各玩各的。

2. 动手前的准备工作

2.1 本地环境初始化：装好 Claude Code 和 Git 配置

第一步当然是先把 Claude Code 装好。前提条件是你本机有 Node.js 18 以上版本，我建议直接用 20 或者更新版本，省得后面遇到莫名其妙的兼容性问题。安装命令很简单：

npm install -g @anthropic-ai/claude-code claude --version

看到版本号输出，说明安装成功了。然后在任意项目里启动：

claude

用 VS Code 的朋友也可以装官方扩展，在编辑器里开侧边栏对话。不过我个人建议至少先在命令行里体验一段时间，因为后面处理 Git 操作、管道命令、CI 脚本这类任务时，终端的控制力比图形界面强太多，也更容易写进自动化流程。

另外一个经常被忽略的准备工作是确认 Git 用户信息。Claude Code 执行 Git 操作时依赖 git 的身份配置，如果user.name和user.email没设好，后面一堆自动化脚本会在第一步就报错。检查一下：

git config --global user.name git config --global user.email

没有输出就赶紧配上。这个细节不值钱，但卡住你半小时完全可能。

2.2 申请 GitLab 个人访问令牌：一切集成的钥匙

要让 Claude Code 或者 glab 命令行工具操作你的 GitLab 项目，靠密码登录是不现实的。正规做法是用个人访问令牌（Personal Access Token，也就是常说的 PAT）。

创建路径是：登录 GitLab -> 右上角头像 -> Edit profile -> Access Tokens。填上名字、有效期，然后勾选权限范围。这里的权限选择我建议按照最小化原则来，千万别图省事直接全选。

令牌生成后只会完整显示一次，务必立刻复制保存。我一般会把它放进系统钥匙串或者密码管理器，尽量不要以明文形式放在项目目录里。后面你配置 glab、配置 CI 变量都会用到这个令牌，丢了就得重新建。

2.3 安装并配置 glab：把 GitLab 搬进命令行

glab 是 GitLab 官方的命令行工具，可以理解成 GitLab 版的 gh。装了它以后，你就能在终端里直接列出 MR、查看 issue、创建合并请求、获取 diff。Claude Code 也就能通过这些命令和 GitLab 交互，而不是每次都需要我手动点浏览器。

macOS 上安装最简单：

brew install glab

Linux 或者 Windows 用户可以用官方提供的安装脚本，直接按 glab 文档里的指引操作就行。装完后需要认证登录：

glab auth login

它会先把 GitLab 实例地址问一遍。如果你们是 GitLab.com 官方 SaaS 服务，直接回车；如果是用 Docker 或者物理机自建的实例，需要填完整的实例地址。然后选择登录方式，推荐直接粘贴刚才生成的 PAT，比浏览器登录更适合无人值守环境。最后验证打通情况：

glab auth status glab mr list

如果这两个命令都能正常输出，说明 glab 和你们 GitLab 实例的通道已经打通了。到这一步，本地的三件套就齐了：Claude Code 负责“思考”，glab 负责“动手”，GitLab 令牌就是那把门禁卡。

3. 集成实操：让 Claude Code 接管日常 GitLab 操作

3.1 一键生成规范的 MR 描述

不知道你有没有过这种经历：代码写完了，push 到远端，点开 GitLab 新建 MR，然后盯着描述框发呆——到底怎么写才能让队友明白我改了什么、为什么这么改、有没有风险。我反正是经常卡在这一步。而这个场景，恰恰是 Claude Code 最容易做出即时效果的地方。

整体思路很简单：先用 git 命令把当前分支和主分支的 diff 取出来，把 diff 交给 Claude Code，让它按固定模板生成 MR 描述，最后用 glab 创建 MR。我直接把这个流程写成了脚本放在项目根目录的scripts/mr.sh里：

#!/bin/bash set -e BRANCH=$(git rev-parse --abbrev-ref HEAD) TITLE=$(git log -1 --pretty=%s) DIFF=$(git diff master...$BRANCH | head -c 12000) DESCRIPTION=$(claude -p "根据以下diff生成GitLab MR描述，包含：1. 变更背景；2. 主要改动；3. 测试建议。用中文输出，保持简洁： $DIFF") glab mr create --source "$BRANCH" --target master --title "$TITLE" --description "$DESCRIPTION" --yes

这里claude -p是非交互模式，直接传 prompt 拿输出，非常适合写自动化脚本。把 diff 截到 12000 字符以内也是有意为之，模型上下文有限，diff 太长会把重点淹没，而且生成速度也会明显变慢。实际跑一次，你会发现生成的描述比你自己憋半小时写出来的要完整很多，尤其是“变更背景”和“测试建议”这两块，AI 能根据代码 diff 倒推出不少上下文。

当然有个前提：生成完还是要自己扫一眼再提交。AI 的理解偶尔会跑偏，尤其当分支里有大量无关文件的格式化改动时，它会把这些噪音也写进描述里。我一般是在浏览器里快速过一遍再点确认，整个过程也就多花一分钟。

3.2 从 issue 到分支：让 AI 参与需求的“开头”

另一个高频场景是从 issue 开始开发。项目里经常同时挂着几十个 issue，传统流程是：读 issue -> 理解需求 -> 起分支 -> 写代码 -> 提 MR。这个流程里最耗精力的不是写代码，而是理解需求和决定从哪里下手。这部分让 Claude Code 来分担，效率提升非常明显。

使用方法很简单，在项目根目录启动 claude，然后直接发指令：

帮我看看 GitLab 上 issue #128 的需求，用 glab 获取它的内容，然后根据这个需求建议一个合适的分支名，要求符合我们仓库的分支命名规范。

Claude Code 会真的去执行终端命令，比如glab issue view 128，把 issue 全文拿回来，然后分析这段自然语言描述，给你一个分支名建议，甚至直接帮你把分支建好、把相关的基础文件初始化出来。你要做的只是最后确认一下，有偏差就当场纠正。

这个流程的意义不只是“少敲了几条命令”，而是把 AI 放进需求理解这个关键环节。我见过太多开发者在写代码前就理解错了需求，后面返工成本极高。让 AI 先帮你把需求文字、代码结构、分支命名串成一条可执行的路，你来负责审批和纠偏，节奏会舒服很多。

3.3 用 MCP 把 GitLab 变成 Claude Code 的“原生工具箱”

如果 glab 用得多了，你会发现一个瓶颈：Claude Code 本身并不知道 glab 有哪些命令、参数是什么，它只能靠猜或者靠系统提示里带的信息。解决这个问题的正路是 MCP（模型上下文协议）。简单来说，MCP 是一种让 AI 模型动态获得“工具列表”的标准方式，Claude Code 通过它可以把 GitLab 的能力变成一套原生工具，需要时自动调用。

在 Claude Code 里配置很快。启动 claude 后输入：

/mcp

然后添加新的 MCP server，填上 GitLab MCP Server 的地址和令牌。配置完成后，Claude Code 会拿到一组工具，比如“列出项目 MR”“获取某个 MR 的评论”“查看 pipeline 状态”。它会在对话中按需选择工具调用，而不是靠猜命令碰运气。

这个选项即便你暂时不打算深入研究也值得了解。刚开始集成时，用 glab 已经完全够用，不需要上 MCP；但一旦你的团队开始跑大量自动化任务，让 Claude Code 直接“操作”GitLab 的能力边界会比命令行方式宽很多。

4. 把 AI 放进 CI/CD：GitLab CI 里的代码审查助手

4.1 先想清楚 AI 审查在流水线里的定位

前面几节讲的都是本地集成，接下来是整篇文章的重头戏：把 Claude 的审查能力放进 GitLab CI，让每次 MR 创建时自动触发一次 AI 代码审查。好处很明显——审查动作不依赖开发者本地装没装 Claude Code，只要代码推上来，流水线就会自动跑，所有人都跑在同一套标准上。

但在设计阶段，我强烈建议把这个 job 定位成“建议机器人”，而不是“质量闸门”。意思是说，它的评论不阻塞合并，不影响 MR 状态，AI 意见仅供参考。原因是 AI 确实会误报，如果把 review job 设为 required，一次误报就会卡住整个团队的合并节奏，反而制造麻烦。稳妥的做法是让 AI 在 MR 下留一条带建议的评论，最终决策权始终在人类手里。

同时，触发条件必须精准，不然会白白浪费 API 配额。我们只希望它在 MR 事件触发时跑，不需要每次 push 都跑一遍。

4.2 一个可落地的 CI Job 配置示例

下面给一个我实际用过的简化版本。项目里需要两个文件：.gitlab-ci.yml和scripts/code_review.py。

先看.gitlab-ci.yml：

review: stage: test image: python:3.11-slim only: - merge_requests script: - pip install anthropic - python scripts/code_review.py variables: ANTHROPIC_MODEL: claude-3-5-haiku-latest

only: - merge_requests是关键规则，确保只有 MR 相关的事件才触发这个 job，普通分支推送不会白白消耗额度。新版 GitLab 推荐用rules写规则，这里为了兼容旧版本用了only，如果你的实例版本较新，可以换成等价的 rules 写法。

然后是scripts/code_review.py。它的核心逻辑是：从 CI 环境变量拿到 MR 信息和 diff，调用 Claude API 生成审查意见，再通过 GitLab API 把评论写到 MR 讨论区。我用标准库加 anthropic SDK 实现，方便理解：

import os import anthropic import urllib.request import json API_URL = os.environ["CI_API_V4_URL"] PROJECT_ID = os.environ["CI_PROJECT_ID"] MR_IID = os.environ["CI_MERGE_REQUEST_IID"] API_TOKEN = os.environ["GITLAB_REVIEW_TOKEN"] diff_url = f"{API_URL}/projects/{PROJECT_ID}/merge_requests/{MR_IID}/changes" req = urllib.request.Request(diff_url, headers={"PRIVATE-TOKEN": API_TOKEN}) diff_data = json.load(urllib.request.urlopen(req)) diff_text = json.dumps(diff_data.get("changes", []))[:8000] client = anthropic.Anthropic() resp = client.messages.create( model=os.environ["ANTHROPIC_MODEL"], max_tokens=1024, messages=[{ "role": "user", "content": f"你是代码审查助手，请针对以下diff输出评审意见，按严重程度分组：\n{diff_text}" }] ) comment = resp.content[0].text comment_url = f"{API_URL}/projects/{PROJECT_ID}/merge_requests/{MR_IID}/discussions" payload = json.dumps({"body": "AI Review: " + comment}) req = urllib.request.Request( comment_url, data=payload.encode(), headers={"PRIVATE-TOKEN": API_TOKEN, "Content-Type": "application/json"}, method="POST" ) urllib.request.urlopen(req)

项目配置里，进入 GitLab 项目页面的 Settings -> CI/CD -> Variables，添加两个变量：GITLAB_REVIEW_TOKEN（用有 api 权限的 PAT，最好来自专门的 bot 账号）和ANTHROPIC_API_KEY。这两个变量都要勾上 Masked 选项，避免值出现在 CI 日志里。

4.3 CI 里调用 Claude 的落地细节与成本控制

这个方案跑通不难，难在“长期稳定又省钱地跑”。我这里重点说三个细节。

第一个是模型选择。代码审查这种任务，用最大最贵的旗舰模型效果当然好，但代价是慢和贵。我实测下来，轻量级的 haiku 级别模型在多数场景里已经能给出足够有价值的建议，性价比要好得多。如果你是先在本地用 Claude Code 调优过 prompt，再迁移到 CI，建议测试时把模型调高一个级别看差异，再决定用哪个档位的。

第二个是 diff 长度的控制。一次改动 20 个文件的 MR，全量 diff 丢给模型肯定不理智，既费 token，又容易让模型“看不过来”。我把 diff 文本限制在 8000 字符以内，或者干脆只提取包含新增代码、TODO、FIXME 的部分做审查。你要是想更精细一些，可以用 GitLab API 按文件逐个取 diff，做到每文件单独跑一遍。

第三个是频率限制和并发冲突。团队活跃期往往同时有好几个 MR 在创建，如果你的 review job 在同一时间爆发，很可能触发 Claude API 的速率限制。简单做法是在 Python 脚本里加一个几秒钟的 sleep，或者用带指数退避的重试逻辑。别小看这个细节，第一次被限流卡掉三四个 MR 的评论时你就懂我为什么提它了。

另外提醒一句：不要在 CI 里把 prompt 原文或 comment 原文直接打印到日志里。万一 MR 里碰巧有敏感的业务代码片段，日志一泄露就是事故。

5. 踩坑记录：常见问题与排查思路

5.1 认证与权限问题速查表

集成过程中，我踩过、也帮朋友远程排查过不少坑。整理一张速查表，大家按症状对号入座，比从头翻日志快得多：

5.2 实践中踩过的“没想到”的坑

第一个坑是 glab 版本太老。在 CI Runner 或者某些受控环境里，镜像自带的 glab 版本可能落后好几个大版本，新字段和参数都没有，脚本跑一半就报unknown flag。我的建议永远是先确认版本再跑脚本，遇到奇怪行为先想着升级而不是改逻辑。

第二个坑是 GitLab 版本兼容性。glab 和 GitLab API 之间的兼容性要求比较高，旧版本实例（比如 14.x 之前）很多接口根本不支持。我自己遇到过本地 glab 一切正常、但 CI 环境连不上实例的情况，最后发现是 Runner 镜像里的 glab 版本跟实例 API 版本完全不匹配。解决方式是让 Runner 镜像安装和实例版本匹配的 glab，或者更保险一点，直接改用 curl 调 API，绕过 glab 的版本兼容问题。

第三个坑跟 Claude Code 自身的项目规范文件有关。很多团队会在项目里放一个CLAUDE.md，用来定义项目约定，Claude Code 每次对话都会自动读它。这个文件写好了，AI 生成的内容会非常贴合团队风格；但如果你在里面堆了大量主观描述、矛盾规则，输出反而会变得很不稳定。我的经验是这个文件只写客观事实和硬性约定，比如分支命名规则、commit 格式、测试命令、目录结构说明，千万别把个人偏好和风格倾向写进去。

5.3 渐进式落地：从“辅助生成”到“自动审查”

最后说说我的整体体会。集成 Claude Code 和 GitLab，真的没必要一上来就上全套，那样既增加团队学习成本，也容易因为某个环节不稳定而浪费信任。我建议按下面这个顺序渐进落地。

第一步，先把本地生成 MR 描述跑起来。这个动作几乎没有风险，两个人觉得好用就会自然扩散。第二步，把 glab 和 issue 联动做起来，让 AI 参与需求分析和分支规划。第三步，再上 CI 里的代码审查机器人。每一步都能独立产生价值，每一步都在帮团队建立对 AI 的信任感。

等整个流程跑顺了，你还能继续扩展：比如让 AI 自动给 MR 打标签、自动更新关联 issue 的状态、在合并后根据提交历史自动生成 changelog。GitLab 的 API 覆盖面很广，Claude Code 的工具调用能力也在快速变强，这两个东西组合起来的想象空间，确实比大多数人以为的要大得多。先把最笨、最稳的几条路走通，你会感受到团队的交付节奏真真切切地快了起来。