企业官网建设流程全解析

1. 报名之前先想清楚：你要的是一个仓库，还是一条协作链路

很多人看到"代码协同开发体验活动"这几个字，第一反应是点进去建个仓库、提交两行代码、看看界面长得顺不顺眼，然后关掉页面，心想"哦，跟别的代码托管平台差不多"。这种打开方式基本等于白跑一趟。我在几年前第一次接触这类平台体验活动时也这么干过，结果三个月后团队真要迁移，才发现当初那一圈点击什么有效信息都没留下。

CodeArts Repo 这类平台提供的核心能力，说到底是把"代码托管、分支协作、代码评审、流水线触发、权限审计"这几件事缝在一条链路上。单看任何一环，市场上的选择都不少；真正拉开差距的，是这条链路上环节之间的衔接成本——评审能不能强制、合并能不能自动触发构建、权限能不能细到目录、审计日志能不能查清"谁在什么时候动了哪个保护分支"。这些东西你不带着真实场景去跑，是看不出来的。

所以这篇东西不打算写成功能罗列。我想聊的是：如果你打算花几个小时参加这么一次体验活动，怎么把时间用在刀刃上——怎么在活动环境里把一条完整的协同链路跑通，怎么提前把迁移时会撞上的坑踩掉，以及那些配置项背后到底在约束什么。适合准备做代码平台选型的技术负责人、刚接手团队仓库的维护者，也适合单纯想把自己那摊子代码管得更规范的个人开发者。

1.1 把团队的痛写成一张可验证的清单

体验活动最大的陷阱是"演示数据陷阱"：你在一个空仓库里随手提交几个文件，所有功能都顺滑得像广告。真实团队不是这样的。真实团队有历史包袱、有几百兆的二进制文件、有五个人的提交习惯各不相同。

我建议在报名之前，先花二十分钟把当前协作里最疼的三到五件事写成清单，每一条都要能对应一个可验证的动作。比如"新人入职第一天要花半天配环境"对应的验证动作是：让一个没接触过这个仓库的人，只依靠仓库里的文档和凭据说明，把代码拉下来并跑起来，计时。再比如"上线包是谁打的没人说得清"对应的验证动作是：翻一次两周前的发布，看能不能在平台上查到触发构建的那个提交和那个人。

这张清单不需要多漂亮，但必须具体。下面这张表是我自己用的模板，你可以直接改成自己的版本：

这张表填完，你就知道自己该在体验活动里重点看什么了，而不是被引导着一路点"下一步"。

1.2 别在体验环境里堆垃圾数据

另一个常见错误是拿真实仓库直接往里灌。听起来很务实，实际上有两个问题：一是数据合规，真实业务代码进第三方环境要走审批，很多团队卡在这一步；二是真实仓库往往体积巨大，导入一次要等很久，把宝贵的体验时间全耗在进度条上。

我的做法是造一个"结构真实、内容脱敏"的模拟仓库。具体来说：保留目录层级和文件数量级（比如五六个顶层模块、三百来个文件），把业务逻辑替换成占位实现，但故意保留几个真实存在的麻烦——一个 40MB 的资源文件、一段带 Windows 行尾的历史提交、两个已经废弃但还在被引用的子模块。这个仓库只有几十兆，导入很快，但它能暴露的问题和真实仓库八九不离十。

提示：模拟仓库一定要包含"历史提交"而不是一次性初始提交。很多平台的问题恰恰出在处理历史作者邮箱映射、处理奇怪的分支名、处理已经删除的标签上，全新仓库测不出来。

1.3 判断标准不要看功能列表长短

平台对比时最容易犯的错是数功能。A 平台有二十项，B 平台有十八项，所以 A 更好——这个逻辑在代码托管领域基本失效。真正影响日常体验的往往是很朴素的三件事：克隆和拉取的速度稳不稳定、评审流程能不能做成强制约束而不是君子协定、权限粒度能不能切到"这个目录只允许这两个人改"。

速度这件事特别值得单独测。我的测法是：在活动环境里挑一个中等规模仓库（几千个提交），分别在工作日的上午和晚上各做一次完整克隆，记录耗时。如果两次差距超过一倍，说明底层资源调度有问题，后面团队几十号人天天拉代码会被这件事折磨。这个测试花不了几分钟，但信息量比看十页产品介绍都大。

2. 仓库落地的第一公里：导入、凭据与那些会把历史带歪的设置

把代码从旧地方搬到新地方，听起来是个体力活，实际上是个精细活。我见过太多团队在这一步图省事，直接下载个压缩包再解压上传，结果三年的提交历史、分支、标签全没了，代码评审记录一条不剩。等半年后想追溯"这行代码为什么这么写"，发现只能靠猜。

2.1 导入现有仓库时，历史提交比代码本身更值钱

正确的做法是镜像克隆再推送。镜像克隆会把所有分支、所有标签、所有引用原样搬过来，而不是只搬当前分支的工作区。命令本身很简单：

# 从旧地址做一次完整镜像克隆 git clone --mirror https://old-host/team/project.git project.git cd project.git # 推送到新仓库地址（此时是裸仓库，没有工作区） git push --mirror https://new-host/team/project.git

这两行之后的坑才是重点。第一个坑是作者映射：旧仓库里的提交作者可能是zhangsan@old-company这种已经不存在的邮箱，导入后平台上显示的作者是一串 ID 而不是人名，贡献统计全乱。大部分平台在导入时会提供作者映射表，把旧邮箱映射到新账号，这件事必须在上线前一次性做完，事后补极其痛苦（要改写历史）。

第二个坑是大文件。Git 对文本友好，对二进制不友好。如果你的仓库里躺着一个 200MB 的设计稿，它会被完整复制进历史，之后每一次克隆都要把这 200MB 拉一遍，永远删不掉——因为历史不可变。这种情况要么用 Git LFS 把大文件挪出去，要么用历史重写工具把那个文件从所有提交里剔除。前者适合"以后还会有大文件"的场景，后者适合"就这一次，赶紧清掉"。

注意：历史重写会改变所有提交的哈希值，所有已克隆的副本都会失效。做这件事之前必须全员通知、全员停推，做完之后所有人重新克隆。我见过一个团队在周五下午偷偷做这件事，结果周一早上十几个人在推代码时全部冲突，场面相当混乱。

2.2 SSH 与 HTTPS 的取舍不是口味问题

凭据配置这件小事，能决定新人入职第一天的心情。SSH 和 HTTPS 两条路各有适用面：SSH 适合长期使用的开发机，配一次密钥管很久；HTTPS 适合临时环境、CI 流水线、容器内部，因为可以直接用访问令牌而不是私钥。

SSH 这边最容易被忽略的是多账号共存。一个人同时有个人账号和团队账号，两个密钥，默认的~/.ssh/id_rsa只能对上一个。解决办法是写配置文件按主机名分流：

# ~/.ssh/config Host team-repo HostName repo.example.internal User git IdentityFile ~/.ssh/id_ed25519_team IdentitiesOnly yes

然后克隆地址写成git@team-repo:group/project.git这种别名形式。IdentitiesOnly yes这一行很关键，不加的话 SSH 会把本机所有密钥挨个试一遍，某些服务器在尝试次数超限后会直接拒绝连接，症状是"密钥明明是对的却连不上"，非常迷惑。

HTTPS 这边要注意的是凭据缓存策略。把令牌明文写进远程地址（https://user:token@host/...）是最省事也最危险的做法——它会出现在.git/config里，会出现在 shell 历史里，会出现在同事帮你排查问题时你截的图里。稳妥一点的做法是用凭据助手，把令牌存在系统密钥链里，租期到了自动失效。

2.3 三个配置文件决定后面半年会不会天天解冲突

仓库根目录下有三个文件，新项目十有八九没人建，建了也没人看。但它们能省掉的麻烦，抵得上一整天的排查时间。

第一个是.gitattributes，管行尾符。Windows 上是 CRLF，Linux 和 macOS 是 LF。如果仓库里没有统一约定，一个 Windows 同事提交文件后，所有行尾都变了，git diff显示整个文件全红全绿，实际内容一个字没改。评审的人看到几千行变更直接放弃，真正的逻辑改动就藏在这堆噪音里。解决办法是：

# .gitattributes * text=auto eol=lf *.png binary *.xlsx binary *.bat text eol=crlf

* text=auto让 Git 自动识别文本文件并在仓库里统一存 LF，检出时按平台转换。二进制文件要显式标记，否则 Git 会尝试对它们做行尾转换，结果就是文件损坏。

第二个是.gitignore，管"什么东西不该进来"。编译产物、依赖目录、本地配置、日志、IDE 的隐藏文件夹。这件事的价值不在于省空间，而在于避免"我不小心提交了带本地数据库密码的配置文件"这种事故。建议在模板基础上按团队情况补几条，尤其是*.local、*.env、config/*.private.*这类命名模式。

第三个是仓库的体积守门人。Git LFS 的跟踪规则要提前定，别等仓库涨到 2GB 才想起来。我的经验是：单个文件超过 5MB 就该考虑走 LFS，超过 50MB 基本必须走 LFS，超过 200MB 应该压根不进仓库。

最后一行尤其要重视。密钥一旦进入提交历史，就算你下一个提交把它删了，它依然躺在历史里，任何人克隆都能翻出来。这种情况的唯一正确处理方式是：立刻去源头把这个密钥作废并换新，然后才考虑清理历史。顺序不能反。

3. 分支与保护规则：让"必须评审"从口号变成硬约束

"我们要求代码必须评审后才能合并"——这句话我在很多团队的白板上见过，然后在同一个团队的仓库里看到有人直接推主干。要求写在文档里是没用的，必须落成平台上的硬约束。这也是我在体验活动里最看重的一块：这套约束能不能配得足够细，配完之后能不能真的拦住人。

3.1 分支模型选型：先看发布节奏，再看团队规模

关于分支模型的争论可以吵一整天，但落到实操，判断依据其实只有两条：你多久发一次版，以及同时有多少人在同一个代码库上改东西。

如果产品是持续部署、每天甚至每次合并都上线，那主干开发（trunk-based）最合适：所有人往主干合，功能没做完就用开关藏在特性开关后面。这种模式的好处是冲突暴露得早、集成成本低；代价是对自动化测试要求高，主干的任何一次提交都必须是可发布的。

如果产品是按版本发布、有明确的迭代周期和回归测试窗口，那"主干 + 发布分支 + 短生命周期特性分支"更稳。特性分支活不过三天，发布分支拉出来之后只接受修复不接受新功能。

Git Flow 那套 develop、release、hotfix 全齐的模型，说实话在大部分中小团队里是过度设计。分支一多，合并路径就变成一张网，谁合到谁、什么时候合，全靠人记。我见过一个团队用完整 Git Flow，结果一个 hotfix 同时在三个分支上改了三遍，第三遍还改漏了一行。

我的建议是：五个人以下、日更节奏，就用主干开发加短分支；十人以上、有版本窗口，就用主干加发布分支；除非有非常明确的合规要求，别碰完整 Git Flow。

3.2 保护分支上那几个开关，关掉一个就等于没有评审

分支建好之后，真正起作用的是保护规则。平台上的开关通常有七八个，我挑最关键的四个说，因为只要漏掉其中一个，整套约束就会出现缺口。

第一个：禁止直接推送。这一条是基础中的基础。不开这个，其他所有规则都白搭，因为人可以绕过合并请求直接推。开了之后，所有改动必须走合并请求。

第二个：要求至少 N 人批准。N 取 1 还是 2，取决于改动的影响面。我的习惯是主干要求 1 人，发布分支要求 2 人，涉及权限、支付、数据删除这类敏感路径的目录，通过 CODEOWNERS 指定必须由对应负责人批准。这里有个细节：一定要开启"新提交使已有批准失效"，否则会出现"我批准了，然后作者又推了三个提交，批准依然有效"的情况，评审形同虚设。

第三个：要求流水线通过。光有人看是不够的，人看不出的编译错误、单元测试失败、静态检查问题，得让机器拦。这条开了之后，合并按钮在检查通过前是灰的，这个视觉反馈比任何流程文档都管用。

第四个：要求分支是最新的。这条容易被忽略。如果允许基于过期的目标分支合并，就可能出现"我本地测试通过，合进去之后因为别人先合了一个不兼容的改动而挂掉"。要求合并前先把目标分支合进来并重新跑检查，能规避掉绝大部分这类问题。

提示：保护规则建议先在体验环境里用一个测试账号故意违规操作一次，确认真的会被拦住。我遇到过保护规则只对普通成员生效、管理员可以绕过的情况，这种配置等于没配。

3.3 合并策略的后果：squash、rebase、merge commit 各自会让历史长什么样

这个选择没有对错，但后果差别很大，而且事后很难改。

合并提交（merge commit）保留完整的拓扑结构，能看出一个特性分支是从哪里分出去、中间有哪些提交、什么时候合回来。好处是信息完整，坏处是主干历史图会变得很花，而且git log里混着大量"wip""fix typo""再改一下"这种噪音提交。

压缩合并（squash）把一个分支上的所有提交压成一个，落到主干上。主干历史非常干净，一个特性一个提交，回滚特别方便。代价是丢失分支内部的细粒度提交，如果某个特性做了一周、改了三十次，最后只留下一条提交记录，中途的试错过程就没了。对大部分业务团队来说，这个代价可以接受，因为没人真的会去翻三十条中间提交。

变基合并（rebase）把分支上的提交逐个重放到目标分支顶端，得到线性历史且保留了细粒度提交。看起来两全其美，但有两个风险：一是提交哈希全变，如果分支已经被别人拉过，会产生混乱；二是如果合并过程中解决冲突时出错，错误会被分摊到多个提交里，比一次合并更难定位。

我的默认选择是：业务功能分支用压缩合并，保持主干干净；底层库或者需要精细追溯的仓库用变基合并；发布分支往回合并到主干时用合并提交，保留"这是一个发布"的边界。

4. 把检查推到提交之前：钩子、规范与流水线的分工

流水线跑得慢，根因往往不在流水线本身，而在于太多本该在本地解决的问题被推到了服务端。一个格式不合规的分号、一个拼错的提交信息、一个忘删的调试打印，都值得花三分钟排队等一次构建失败吗？显然不值得。所以我把质量检查分成三层：本地钩子管"出门前照镜子"，提交信息规范管"给自动化提供输入"，流水线管"真正需要完整环境才能验证的事"。

4.1 本地钩子负责别让脏东西出门

提交前钩子最实用的三个检查：格式化、静态检查、敏感信息扫描。前两个是习惯问题，第三个是安全问题。

配置方式通常是引入一个钩子管理工具，在项目初始化时自动装到.git/hooks下。这里有个团队协作的经典矛盾：钩子是本地的，不进版本库，你怎么保证每个人都装了？答案是两条腿走路——一是把安装脚本写进项目的依赖安装流程（比如npm install之后自动执行），二是在流水线上保留同样的检查作为兜底。指望百分之百的人都装钩子是不现实的，总有人的环境有问题，所以服务端必须有最后一道闸。

敏感信息扫描特别值得单独说。我见过最典型的事故是：某开发者本地调试时把数据库连接串硬编码进了配置文件，提交前钩子没装，直接推上去了。这个连接串在历史里躺了两周才被发现，期间所有克隆过仓库的人都有。所以本地钩子扫描的意义不在于"抓坏人"，而在于把发现时间从两周缩短到两秒。

4.2 提交信息规范不是洁癖，是自动化的输入

很多人觉得提交信息格式要求是形式主义。我以前也这么想，直到有一次要做变更日志，发现历史提交里一半是"fix"，三分之一是"修改"，剩下的是"."和"111"。这种历史，你没法自动生成任何东西。

约定式提交（Conventional Commits）的核心就一句话：提交信息的第一行用类型(范围): 描述的格式，类型从固定集合里选（feat、fix、docs、refactor、test、chore 等）。这么做的直接收益有三个：可以根据feat和fix自动生成变更日志；可以根据类型决定版本号是升主版本还是次版本；可以在评审时一眼看出这个改动是功能还是修补。

feat(order): 支持按时间段筛选订单 fix(auth): 修复令牌过期后未跳转登录页的问题 refactor(payment): 抽出支付渠道适配层

配合一个提交信息校验钩子，不合规的直接拒绝提交。我知道有人会嫌烦，但相信我，等到你需要回溯"上个版本到底改了什么"的时候，这份规范会救你。

4.3 流水线里最值得先加的三道关卡

流水线配置这件事，我建议从最小的可用集合开始，别一上来就搞十几个阶段。最值得先加的是三道：

第一道：编译与单元测试。这是底线，编译不过就不该允许合并。这一道要尽量快，控制在五分钟以内，超了就没人愿意等。优化手段是缓存依赖、只跑受影响的模块、并行拆分测试集。

第二道：静态扫描。空指针风险、未处理的异常、明显的资源泄漏、硬编码凭据。这一道适合设成"有严重问题才阻断，一般问题只提示"，否则一上来几百条告警，团队很快就会养成"看见红点直接忽略"的习惯，等于没做。

第三道：构建产物。把可部署的包或镜像构建出来并存档。这一道的价值是验证"这个提交真的能产出可运行的产物"，而不是"在我本地能跑"。

# 通用结构示意，具体语法按平台文档调整 stages: - verify - build verify: stage: verify steps: - run: npm ci --prefer-offline - run: npm run lint - run: npm run test:unit -- --coverage cache: key: deps-$CI_COMMIT_REF paths: - node_modules/ build: stage: build needs: [verify] steps: - run: npm run build - upload: dist/

这里有个容易踩的细节：缓存的 key 不要图省事用固定字符串。用固定 key 会导致所有分支共享同一份缓存，A 分支装了新依赖，B 分支校验和它对不上，构建随机失败，排查起来极其费劲。按分支或按锁文件哈希做 key，稳得多。

5. 权限这件事：给大了出事，给小了拖慢

权限管理是那种平时没人关心、出事时才想起来的东西。给得太松，一个误操作就能把保护分支删掉；给得太紧，改一行文档都要找管理员，日常效率被拖垮。我见过两种极端：一种是全员管理员，理由是"人少，方便"；另一种是除了负责人全是只读，理由是"安全"。前者迟早出事故，后者迟早把人逼走。

5.1 角色划分与实际映射

大部分平台的角色模型大同小异，一般分四档：拥有者、维护者、开发者、报告者。关键是搞清楚每一档能做什么，然后在团队里做映射。

拥有者能改仓库设置、删仓库、改权限，这档只应该给一到两个人，而且必须是那种"知道自己在干什么"的人。维护者能管理分支、合并请求、标签，适合技术负责人和资深开发。开发者能推分支、提合并请求，应该是绝大多数人的默认角色。报告者只能看和提问题，适合外部合作方、测试同学、产品经理。

有个小技巧：默认角色一定要设成"开发者"而不是"报告者"或者"维护者"。新成员加入时默认给最小可用权限，需要更多再申请，比默认给大权限事后收回要安全得多——因为"事后收回"这件事几乎永远不会发生。

5.2 CODEOWNERS 与目录级权限

角色是粗粒度的，真正解决问题的是按路径授权。CODEOWNERS 文件用一行一条规则的方式，声明某个目录或某类文件的改动必须由谁批准：

# 所有涉及部署的改动必须由运维负责人批准 /deploy/ @ops-lead # 数据库迁移脚本必须由两个人中的任意一个批准 /db/migrations/ @backend-lead @dba # 公共组件改动影响面大，要求架构组批准 /src/common/ @arch-group

这个机制的价值在于把"谁懂这块"变成"谁能批准这块"。一个前端同学改了个样式，不需要拉后端负责人来评审；但有人动了部署脚本，就必须过运维这关。规则配好之后，合并请求会自动带上必须的评审人，不会出现"提了没人看"的情况。

如果平台支持目录级权限（而不只是评审要求），那更值得用。比如把生产配置目录设成只有两个人可写，其他人的合并请求必须由这两人代合。这比"要求批准"更硬，因为它拦在推送层面。

5.3 密钥泄露的处置顺序

这件事必须写在团队手册里，因为一旦发生，人在慌乱中很容易做错顺序。正确顺序是：

1. 立即作废密钥。去签发方那里把这个凭据吊销或轮换，这是唯一能止血的操作。不管代码还在不在，凭据先废掉。
2. 查使用记录。看这个凭据在有效期内有没有被非预期的来源使用过，判断影响范围。
3. 清理仓库。把明文从当前代码里删掉，改成从环境变量或密钥管理服务读取。
4. 评估是否重写历史。如果仓库是公开的，或者克隆过的人很多，历史里的密钥虽然有备份价值但已失效，重写历史的收益不大、代价不小，通常可以不做。如果是内部仓库且访问面可控，可以考虑重写。

最常见的错误是顺序颠倒：先忙着删代码、改历史，忘了去作废凭据。代码删了，密钥还活着，攻击者该用还是用。

6. 实测踩坑录：六个我以为没问题的地方

下面这些都是我在真实环境里撞过的，每一个当时都觉得"这不可能会出问题"，然后出了问题。

坑一：大文件把仓库撑到没法克隆。表现是某个同事突然克隆失败了，报超时。排查过程很绕：先怀疑网络，换了三个网络环境都一样；再怀疑磁盘，空间充足；最后用体积分析工具扫了一遍，发现历史里有个 300MB 的视频文件，是半年前做演示时误提交的，后来删了，但历史还在。修复方式是历史重写加 LFS 迁移，全团队重新克隆。教训是：仓库体积要有定期巡检，别等出事。

坑二：行尾符导致整个文件全变更。表现是一个只改了一行的提交，评审界面显示三千行变更。原因是提交者的编辑器把整个文件的 CRLF 转成了 LF。修复是加.gitattributes并做一次全库规范化提交（这一个提交确实会有大量变更，但只此一次），之后所有新提交都干净了。这个坑的隐蔽之处在于：加完配置之后，本地工作区需要重新检出才能真正生效，很多人加完配置发现没变化就以为没用。

坑三：子模块指向了一个已经不存在的提交。表现是克隆之后构建失败，报某个依赖目录为空。查下来是子模块的引用指向了上游仓库被强制推送后消失的提交。修复是把子模块更新到存在的提交上。根本性的教训是：子模块的引用非常脆弱，上游一旦重写历史就断。能用包管理器解决的依赖，别用子模块；非要用，就在主仓库里锁定一个稳定标签而不是某个浮动提交。

坑四：强制推送覆盖了别人的工作。表现是同事说他推的三个提交不见了。原因是另一个人在自己分支上做了变基后强制推送，而这个分支恰好是共享的。这个坑没有技术解法，只有约定：共享分支永远不强制推送，要变基就在自己的私有分支做，或者用--force-with-lease这个稍微安全一点的选项——它会在远程有你不知道的新提交时拒绝推送。

坑五：评审卡在"等一个人回复"。表现是一个紧急修复的合并请求挂了两天，因为指定的评审人在休假。修复是在保护规则里配置"评审组"而不是"具体某个人"，组里任意一人批准即可，并设置超时自动升级提醒。规则设计时要考虑人的缺席，这是很多流程设计的盲点。

坑六：钩子只在装了的人机器上生效。表现是同一个格式问题被反复提交，有人说"我本地明明检查过了"，因为他确实装了钩子，但另外两个人没装。修复是把同样的检查逻辑搬到流水线上，本地钩子只作为"提前发现"的便利，不作为唯一防线。任何依赖客户端自觉的约束，都不能当作安全边界。

最后一个我自己摸索出来的小习惯：每次在平台里配置完一项保护规则，我都会用一个专门的测试账号去故意违反一次，确认真的拦得住。这件事花不了一分钟，但能避免那种"以为配了其实没生效"的情况。规则这东西，只有被验证过才算数。