企业官网建设流程全解析

两年前有一次线上事故让我印象特别深。那天我们发布了一个新版本，单元测试和接口测试全绿，结果上线不到半小时，就有人反馈下单成功后订单详情页一直转圈。后来排查发现，订单其实已经创建成功了，只是前端在下单服务和通知服务之间等待一个超时响应时提前跳了页，页面拿到的是旧状态，于是渲染永远停在加载中。这种跨服务、跨页面的链路问题，普通的单元测试根本覆盖不到，能把它拦下来的，只有从用户视角把整条流程真实跑一遍的端到端测试——也就是大家常说的 E2E（End-to-End）测试。也就是从那天起，我开始认真搭建团队的 E2E 测试体系。

这篇东西不是理论介绍，是我把 E2E 从“零散脚本”推进到“稳定回归防线”的全过程记录，包括怎么圈测试范围、怎么选工具、怎么把用例维护住、怎么让测试在 CI 里不添乱。如果你正在为频繁手工回归发愁，或者写过几个 E2E 用例但动不动就挂，这篇文章应该能帮上忙。我讲的是自己真实踩过坑、调整过、最后沉淀下来的做法，直接可以拿去当参考。

1. 先说那次事故：为什么单测全绿，线上还是出问题

1.1 事故的根因：链路状态不同步

那天的故障链路我简单还原一下。用户在前端提交订单，后端下单接口先创建订单，再异步通知库存和配送服务。前端代码在收到“创建成功”响应后就跳转到订单详情页，但详情页的加载依赖另一个“查询订单状态”的响应，这个响应在极端情况下会晚几秒。由于前端有自己的超时保护，网络一慢就自动重试查询，可重试接到的状态码对应的是旧版本返回结构，页面里没有处理这种结构的逻辑，于是就一直转圈。

这类问题有一套典型特征：所有单测都通过，接口测试也通过，但就是没人验证过“用户从下单到看到订单详情”这条完整链路。单测保证的是每个函数、每个组件在孤立环境下的行为，接口测试保证的是两个服务在约定报文下能通，它们都假设“上下游一定按预期工作”，可分布式系统里最不缺的就是意外。

1.2 E2E 和单测、接口测试的分工边界

很多人对 E2E 有个误解，觉得它就是把单测换个地方再跑一遍。实际上三者测的是完全不同的层面：

• 单元测试：验证“一个函数、一个组件、一个类”在给定输入下的输出，追求的是快速定位和覆盖分支逻辑。
• 接口测试：验证“服务与外部之间的契约”，关注请求格式、响应内容、鉴权、超时，不关心页面长什么样。
• E2E 测试：站在真实用户视角，打开真实浏览器、走真实接口、操作真实界面，验证从入口到落地的完整业务闭环。

E2E 的独特价值在于它能暴露“系统性问题”。比如数据库某个字段在迁移后没对齐，单测和接口测试都发现不了，但用户一登录就会看到“昵称加载失败”；再比如两个前端模块对同一个时间字段格式处理不一致，接口测试看着是好的，用户却看到了一串时间戳。这种问题只有 E2E 能拦下来。

1.3 一个合理的测试金字塔

我后来慢慢接受的观念是，测试体系要像金字塔：底层是大量快速的单测，中间是几十上百个接口测试，顶层是少量但关键的 E2E 测试。E2E 数量和占比都应该是最小的，因为 E2E 跑得最慢、执行成本最高、稳定性最难控制。可恰恰是这最少的一层，承担了“把关核心用户体验”的重任。

如果金字塔上下颠倒，把几百个用例全堆在 E2E 层，那测试会变成团队负担，每天都在和偶发失败搏斗，最终被人放弃。E2E 的定位应该是“精兵”，不是“人海”。

所以我建议每个从没搭过 E2E 的团队，不要一上来就追求覆盖率，先想清楚一个问题：哪些用户旅程，一旦坏了，用户会立刻骂人？答案里的那些点，才是 E2E 的第一批覆盖对象。

2. 圈定 E2E 的射程：哪些场景值得端到端覆盖

2.1 值得写的：用户可感知的核心链路

判断一个场景值不值得写 E2E，我有一个很朴素的检验标准：这个环节出错，用户会不会直接骂人。如果会，就值得；如果只是开发视角觉得“还是测一下放心”，那大概率不适合。

按这个标准，最值得优先覆盖的是这几类场景：

• 核心业务主流程：注册、登录、购物车结算、创建订单、支付回调后的状态更新、上传文件后可见。
• 跨模块或跨系统的数据流转：比如“前端下单 -> 订单服务生成订单 -> 支付回调 -> 订单状态变为已支付 -> 页面展示支付成功页”，这中间任何一个环节断掉，用户感知都非常明显。
• 高频率回归的核心区域：每次发布前，手工回归点最多的那几条路径，正是 E2E 最能省人力成本的清单。

举两个例子。同样是测试一个电商系统，我会优先写“从加入购物车到支付成功页出现”这条链路，而不是去写“购物车里某个商品角标数字在 hover 后颜色是否正确”。前者是用户可感知的核心结果，后者属于视觉细节，用组件测试甚至人工点两下就够了。

2.2 不值得写的：样式、细节和内部逻辑

E2E 的代价决定了它不适合干所有活。我踩过不少把 E2E 用错的坑，比较典型的包括：

• 像素级视觉回归：按钮的实际像素、阴影、字体大小这些，交给视觉回归或者截图对比工具，E2E 框架做这件事又慢又没有针对性。
• 纯内部逻辑：某个工具函数的边界条件、某个组件的状态流转，单测是更合适的场地。
• 第三方生态的细节交互：比如验证码图片的识别、某个第三方 SNS 登录弹窗的内部行为，E2E 去测很容易被对方改版拖垮。

还有一个高频误区：把数量放在第一位，觉得“测试用例越多越安全”。实际上，E2E 用例每增加一条，维护成本不是线性增长，而是近似指数增长。因为用例之间容易相互影响，一个页面的改动可能让几十条用例同时挂掉。我见过一个团队写了三千条 E2E，后来改一次按钮文案要花两天修测试，最后集体选择放弃维护，测试库沦为摆设。

2.3 把用例数量卡在“能维护住”的范围

经过来回折腾，我们最终定下了一条硬规则：核心冒烟集不超过 15 条，全量 E2E 不超过 150 条。这个数字没有科学依据，却是个很现实的平衡点——多于这个量，普通团队很难保证每周至少跑一次全量，少于这个量，又覆盖不了主要的用户旅程。

不单是数量，还要分层。冒烟集对应的是“登录、首页打开、核心业务提交、支付成功”这几条最短链路，部署到生产环境后先跑一遍冒烟集，五分钟内能确认系统基本盘是好的。全量集则覆盖更细的权限分支、异常分支、跨系统流转，可以放到夜间或者每周固定时间跑。分层让“快速反馈”和“全面覆盖”不再互相打架。

3. 选型避坑：在主流 E2E 框架之间我怎么选的

3.1 两个主流框架的核心差异

做 E2E 绕不开工具选型。我重写测试体系时对比过几个主流框架，最终的结论是：没有绝对的好坏，只有匹配不匹配。当时我在两个框架之间纠结了很久，一个是基于浏览器自动化协议、支持多语言的 Playwright，另一个是更偏纯前端社区、上手极快的 Cypress。两者的核心差异我整理成了一张表：

之前我用过更早一代的自动化框架，它的问题在于依赖大量的自定义等待时间和繁琐的驱动配置，一个“元素没找到”的报错能把人逼疯。新一代框架在等待策略上做了很大改进，这是选型时考虑的关键因素。

3.2 我的选择逻辑：跨系统、多标签页、多账号

当时我们团队要覆盖的链路有很明显的特征：

• 测试不只在自家单页应用里跑，还要跨子系统跳转，涉及多个域名；
• 部分场景要同时操作多个标签页，比如从一个系统复制订单号，再到另一个系统去查询；
• 需要模拟两个不同角色在同一个业务流程里协作，经常要开多个浏览器上下文，方便互相不干扰；
• 团队技术栈是 TypeScript，希望测试代码和业务代码用同一种语言。

这几个需求放在一起，几乎是为 Playwright 量身定做的。它的多浏览器上下文机制允许我在同一个测试里拉起两组浏览器状态，一组是管理员，一组是普通用户，然后像真实场景一样在两边来回操作。这个能力对某些业务系统尤其关键：比如“管理员审核后，用户端能实时看到状态变化”的链路，用其他框架写起来会比较别扭。

3.3 给不同团队的选型建议

但是反过来，如果你们的应用是纯前端单页应用，团队没有太多浏览器自动化经验，主要诉求是快速把 E2E 跑起来，那 Cypress 的上手体感会更舒服，它内置的调试体验在初期排错时非常友好，社区里也能找到现成的登录、表格、弹窗类封装。

我的看法是，选型不要看谁的功能列表更长，要看三件事：第一，测试场景里有没有多标签页、多域名、多角色这类高级需求；第二，团队对哪门语言最熟，不要为了测试去学一门新语言；第三，CI 环境能不能提供足够的并行能力。这三件事想清楚了，工具本身并不难学。

另外提醒一句，无论选哪个，都不要急着把所有旧测试迁移过来。先拿一条核心链路做试点，验证框架在新团队里跑得顺不顺，再决定是否全面迁移。工具迁移的成本很容易被低估，尤其是有几百条历史用例时。

4. 工程化落地：搭建一套能长期维护的 E2E 体系

4.1 目录结构和页面对象模式

E2E 脚本最容易烂掉的方式，就是像写一次性脚本那样，把 selectors、接口路径、测试数据全部混在用例里。改一个按钮的 id，就需要批量替换上百个地方，维护成本立刻失控。我采用的方案是全面引入页面对对象模式，把“页面长什么样”和“用例该怎么测”分开。

我们目前的目录长这样：

e2e/ ├── config/ # 环境配置，按 dev/staging/prod 区分 ├── fixtures/ # 测试数据工厂 ├── pages/ # 页面对象，每个业务页面一个文件 ├── tests/ │ ├── smoke/ # 冒烟集，部署后先跑 │ └── full/ # 全量集，夜间或每周跑 ├── utils/ # 公共辅助函数 └── reports/ # 测试报告和失败追踪文件

页面对象的思路很简单：把某个页面需要用的定位器、跳转方法、核心操作都封装在一个类里，用例层只调用业务语义的方法，不写任何 CSS 选择器。举个登录页的例子：

export class LoginPage { // 把 selector 集中管理，页面改版只改这里 constructor(private page: Page) {} async goto(targetUrl: string) { await this.page.goto(targetUrl); } async login(username: string, password: string) { await this.page.getByLabel('用户名').fill(username); await this.page.getByLabel('密码').fill(password); await this.page.getByRole('button', { name: '登录' }).click(); // 等登录后的某个稳定标志出现，避免断言时状态未就绪 await this.page.getByText(`欢迎回来，${username}`).waitFor(); } getErrorMessage() { return this.page.getByTestId('login-error'); } }

这样做的好处很直接：页面结构变了，只需要改对应页面对象，用例本身基本不动。团队成员一眼就能看到“这个页面有哪些核心操作”，新人也更容易上手。

4.2 测试数据的准备与隔离

E2E 数据准备是维护成本的大头，也是初期容易忽略的地方。我们的做法是给 E2E 单独建测试账号和生产环境隔离的测试数据，坚决不碰真实用户数据。所有用例都基于 fixture 工厂来生成自己的数据，不在用例之间共享状态。

// fixtures 示例：用唯一后缀避免用例之间互相踩数据 import { randomUUID } from 'node:crypto'; export const sampleUser = () => ({ username: `e2e_${randomUUID().slice(0, 8)}`, email: `e2e_${randomUUID().slice(0, 8)}@example.test`, password: 'TestPass_2024', });

每一条用例在开始前，通过接口或数据库直接创建自己需要的数据，结束后再用脚本清理。哪怕因为报错导致清理失败，也不会影响下一条用例，因为新用例用的是完全不重复的随机数据。共享固定数据是 E2E 最大的隐形杀手：两条用例同时跑，都可能因为同一份数据被对方改掉而偶发失败。

4.3 断言写在哪里最不容易“假活”

断言是 E2E 最容易写出“假活”的地方。我见过不少用例，断言的是某个 loading 图标消失了，或者某个按钮的 class 变了，这种断言在页面功能坏掉的时候照样能通过，因为跟用户真正感知的结果没有直接关系。

我们后来约定了一条规则：断言要写在用户可感知的稳定结果上。比如，提交订单后，断言“订单已提交”提示文本可见，断言跳转后的页面 URL 正确，断言订单列表里出现了刚创建的订单编号。这些都是用户真实会看到、会用到的结果，不会因为某个边缘动画或者 CSS 类名变化而误报。

await test.step('提交订单后能看到成功确认页', async () => { await orderPage.submitOrder(); // 等待稳定结果，而不是固定 sleep await expect(page).toHaveURL(/\/orders\/.*\/success/); await expect(page.getByText('订单已提交')).toBeVisible(); });

这里的关键是“等待稳定结果”，而不是“等固定时间”。固定 sleep 是 E2E 里最大的反模式，下一章我会专门展开讲。

4.4 配置管理：环境、账号、超时

测试环境的地址、测试账号、超时时间这些，如果写死在代码里，迟早会出问题。我们的 config 目录里放的是按环境区分的配置文件，运行时通过环境变量切换。本地调试、CI、夜间任务分别加载不同环境配置，风雨不漏。

// playwright.config.ts 关键片段 export default defineConfig({ testDir: './tests', timeout: 30_000, expect: { timeout: 10_000 }, retries: process.env.CI ? 1 : 0, workers: process.env.CI ? 2 : 1, use: { baseURL: process.env.E2E_BASE_URL || 'https://staging.example.com', trace: 'retain-on-failure', screenshot: 'only-on-failure', }, projects: [ { name: 'smoke', testMatch: /smoke\/.*\.spec\.ts/ }, { name: 'full', testMatch: /full\/.*\.spec\.ts/ }, ], });

这里的重点项目是trace: 'retain-on-failure'。一旦用例失败，框架会把完整的操作录下来变成 Trace 文件，里面能看到每一步的 DOM 快照、网络请求、控制台日志，排查问题时省力太多。E2E 排错最怕的就是“只看到一行报错但没有上下文”，留 trace 相当于给每个失败自动做了一次案发现场记录。

5. 稳定压倒一切：等待策略与高频踩坑

5.1 自动等待和手写等待的边界

E2E 脚本最容易让人崩溃的就是“偶发失败”——上次跑得好好的，这次莫名其妙挂了，重跑一遍又好了。这类不稳定绝大部分都出在等待策略上。

现代框架都提供了不错的自动等待能力。比如 Playwright 的定位器在点击、填写、断言时，会自动等待元素出现、可见、可交互。这种机制已经帮我解决了 80% 的同步问题。但我自己在实践中发现，自动等待不是万能的，它只解决“元素状态”问题，解决不了“业务状态”问题。

举个典型例子：用户点击了“提交订单”，按钮变成了 loading，后端请求还没返回。这时候页面上的提交按钮是不可用的，自动等待会等到它变为可用才继续。但后端结果回来后按钮又变成可用状态了，此时 DOM 和接口是同步的，而订单列表里的新数据可能还没渲染完。如果下一步立刻断言“订单列表出现新订单”，即使有自动等待也会拿到旧数据。

正确做法是抛弃“等固定时间”的思维，改成“等待业务条件满足”。上面的场景应该等待某个与业务强相关的标识出现，比如订单列表请求返回、成功页 URL 变化、或者“订单已提交”这个文本出现。框架的 web-first assertion 会持续轮询目标条件直到超时，天然就是在帮你做正确的事。

5.2 点击太快、动画拦截、响应未回：三个高频坑

我把实践中遇到最多的问题排了个序：

• 点击太快：页面刚跳转，下一个页面还没加载完，脚本就开始找下一个元素。解决办法是减少无意义的链式操作，在关键节点之间加上明确的条件等待，比如等待某个标题文本出现，再执行下一个动作。
• 动画拦截：按钮元素已经在 DOM 里，但有个浮层或动画还在播放，点击被“挡住”。这类问题常见于有入场动画的弹窗。处理手段有两条：要么等待动画类元素消失，要么在测试环境里关闭动画。两条我都用过，更推荐后者，因为关闭动画能显著降低测试时长。
• 响应未回：接口返回慢，页面先渲染了骨架屏。此时元素是可交互的，但内容不对。解决办法是像上一节说的，断言业务标志，不依赖自动等待。

举一个我们实际修过的用例：某功能在提交成功后，会先跳转到中转页，再自动跳转到详情页。第一版脚本在中转页上做了较多断言，而中转页存在时间只有一秒钟，导致脚本经常失败。后来把中转页的断言删掉，直接等待详情页 URL，用例立即稳定下来。E2E 不是要测所有中间态，而是要测用户在乎的最终结果。

5.3 网络不稳定下的“消毒”手段

测试环境跑在云上时，偶尔会遇到网络抖动导致 E2E 超时。尤其是登录、支付回调查询这类涉及多个外部系统的场景，一个环节变慢，整条用例都会失败。

我们做的不是盲目加大超时，而是把“不稳定”隔离起来。具体做法包括：

• 对关键操作设置单独的、更长的超时，而不是覆盖全用例的超时时间；
• 用网络拦截（route）把第三方统计脚本、广告脚本直接挡掉，减少无关网络请求对浏览器的干扰；
• 把“可能重复出现”的步骤封装成自定义方法，内部做有限次重试，比如点击后连续三次检测目标状态，只有三次都失败才报错。

这里要强调一个原则：重试是为了处理“环境抖动”，不是用来掩盖“代码 BUG”。如果一条用例在本地永远稳定、只在 CI 偶发失败，可以考虑用重试兜底；如果本地也时不时失败，那首先要修的是用例本身，而不是给它加一层“遮羞布”。我们内部有一条规则：一条用例连续三次偶发失败，必须标记出来人工审查，禁止默默重试糊弄过去。

5.4 脆弱用例要标记，而不是默默重试

配置里我设了retries: 1（CI 环境重试一次）。这是有意为之，不是每个用例都一定要重试。重试的目的是把偶发网络问题变成可接受的小概率，而不是让每条用例都有两次机会。我见过有团队把 retries 改成 3、5、10，结果一套 E2E 跑完，几乎每个失败都靠重试通过，失败率看着是 0，真实质量数据完全失真。

更好的机制是给每个用例打标签，区分“关键链路”和“次要链路”。关键链路失败，必须立刻报警，无论重试结果如何都要被看见；次要链路失败，可以先重试一次，再确认是否需要人工介入。我们通过标签机制把“偶发失败被忽略”和“真问题被漏掉”这两个极端风险同时控制住了。

6. 让 E2E 安静地待在 CI 里：执行、分片与报告

6.1 分片并行：让 E2E 从 1 小时降到 5 分钟

E2E 最大的痛点之一就是跑得慢。150 条用例串行执行，每个用例就算只要 30 秒，整体也要一个多小时。CI 里根本没法等这么久，这是很多团队放弃 E2E 的根本原因。

我们的解法是分片并行。CI 里开多个执行器，每个执行器只跑一部分用例，最后汇总结果。以 Playwright 为例，CI 里只需要这样：

# 假设有 8 个分片，在 CI 的 8 个并行 job 中执行 npx playwright test --shard=1/8 npx playwright test --shard=2/8 ... npx playwright test --shard=8/8

分片逻辑不复杂，关键是让执行器数量匹配 CI 的并发额度。机器开得太多容易拖垮整个 CI 集群，太少又起不到提速效果。我们当时从 2 个分片开始试，逐步加到 8 个，观察平均执行时间没有明显回升，才把 8 个定为默认配置。一套 150 条的 E2E 集，从串行需要 90 分钟优化到并行约 6 分钟，完全可以塞进普通部署流程。

6.2 预览环境和分支级触发

E2E 在哪个环境跑，直接影响结果可信度。早期我们直接在测试环境上跑，问题在于测试环境被多个团队共用，随时可能有人正在造数据、改配置，E2E 结果经常受别人干扰。

后来我们改成每提一个合并请求就自动部署一套独立的预览环境。预览环境是这份代码的唯一租户，数据库也是独立隔离的，E2E 跑出来的结果对应的是“我这次改动之后的真实状态”，不会把别人的脏数据算到自己头上。这套方案带来的稳定性提升非常明显，失败的“我不是我没有”大大减少了。

当然，预览环境也有成本，主要是机器资源。我们做了一个折中：冒烟集在每次合并请求都跑，全量集只在合入主干后跑一次。冒烟集 15 条，五六分钟就能出结果，既能及时拦下明显问题，又不至于让每个 PR 都等二十几分钟。

6.3 报告、截图、视频和 Trace 怎么用

E2E 跑完之后的产出物，直接影响排错效率。我们每个 CI 任务都会产出这几样东西：

• HTML 报告：按用例整理的执行结果，包含耗时和失败原因；
• 失败截图：自动附着在失败用例下方，能快速看到当时的页面状态；
• 失败视频：如果有需要，还能录下测试过程的完整视频；
• Trace 文件：记录每一步的 DOM 快照和网络请求链路。

这些产物在 CI 里默认以离线文件形式存在。我们写了脚本把它们上传到对象存储，然后在 PR 的评论里直接贴出下载链接，开发者点开就能看到 Trace 里的完整回放，不用去翻构建日志。这个改动把 E2E 失败的响应速度从“半天”压缩到“五分钟”，非常值得做。

6.4 通知分级和团队约定

如果 E2E 失败每次都把消息发到全员群，用不了两周大家就会麻木，变成“又红了，但应该不是我的问题”。这本质上是个信号噪音问题。我建议按影响范围分级通知：

• 冒烟集失败：立即在核心研发群报警，谁合入的代码谁负责到底；
• 全量集失败：只创建任务卡片，标注失败模块和失败用例，不往群里轰炸；
• 偶发重试后通过：不通知，但写入执行记录，防止被掩盖的问题长期存在。

另外还有几个和团队约定好的事情值得提前说清楚：测试账号由测试团队统一管理和登记，禁止私下占用；所有 E2E 用例在合入主干前必须在本机跑通一次，禁止带着“试试看”的心态提交脚本；每周清理一次过期数据，防止仓库数据膨胀拖慢用例。

6.5 给同样在搭 E2E 体系的人三点提醒

第一，E2E 不是万能药，它的定位是“核心链路的最后一道闸门”，不是全部质量保证。第二，E2E 的稳定性是一个从第一天就要开始维护的指标，不要等到用例多了才处理，偶发失败要当时就当回事。第三，团队建设比技术选型更重要，维护 E2E 的人要有明确归属，不能靠“谁有空谁改”，否则再好的框架也会慢慢贬值。

最后分享一个我至今受益的小技巧：给每个 E2E 用例在文件头写一行注释，说明“这条用例验证的是哪个用户可感知结果”。写不出来或者含糊不清的用例，直接删掉或重写。这个习惯帮我挡掉了至少一半没价值的 E2E 脚本，也让后来接手的新同事能快速理解整套测试体系的设计意图。