07 CI(一):从 lint 到 Playwright 的质量门
一句话结论:CI 的价值不是把本地命令抄一遍,而是把「我会记得检查」变成每次提交都自动检查;步骤顺序应该按失败成本排,能在几秒内失败的事情,不要留到浏览器里。
它解决什么问题
这个仓库只有我一个人写。没有代码评审,也没有测试同学,唯一的防线是提交前那点自觉。问题在于,自觉很不稳定:改一篇文章的 frontmatter、调一个 SCSS 变量、换一个图标,看起来都不像会出事,实际上分别可能让内容校验失败、样式检查报错、主题按钮的可访问名称失配。
本地也有 Git hooks:pre-commit 跑 lint-staged,commit-msg 跑 commitlint。但 hooks 只检查暂存的文件,而且可以被 --no-verify 跳过;它适合挡明显的问题,不适合当完整的质量门。真正的质量门放在 GitHub Actions:每次 push 到 main、每次 PR,都从干净环境安装依赖、构建、跑浏览器测试。
我要它回答的不是「代码能不能跑」,而是几个更具体的问题:
- 内容 frontmatter 是否仍然符合 schema,slug 有没有重复;
- TypeScript 和 Vue 模板是否仍然能通过类型检查;
- 样式是否还在 tokens 和 Stylelint 的约束内;
- 生产构建是否能生成,页面在真实浏览器里是否还能用;
- 亮暗主题下有没有严重的 axe 违规。
我怎么试的
1. 触发条件和 job 拓扑
工作流只做两件事:先检查,再验证镜像能构建。
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
push 和 pull_request 都会触发,workflow_dispatch 留一个手动入口。permissions: contents: read 是最小权限:CI 只需要读代码,不需要写 issue、PR 或 release。concurrency 让同一分支的新提交取消上一次还在跑的任务,避免连续推送时排队等待旧结果。
push / PR
└─ check(15 分钟超时)
├─ checkout
├─ setup-node 24 + npm cache
├─ npm ci
├─ lint / stylelint / format / typecheck
├─ vitest
├─ nuxt build
├─ playwright install chromium
├─ e2e
└─ a11y
└─ image(needs: check)
└─ docker build(只验证,不推送)
check 和 image 两个 job 各自设了 15 分钟超时。超时不是为了卡正常构建,而是防止某个步骤卡死时一直占着 runner。CI 里还设了 HUSKY: 0,避免 npm ci 在无交互环境里尝试安装 Git hooks。
还有一个不太显眼的收益:CI 从干净环境开始,没有本机的全局依赖、旧缓存或未提交文件。它不能证明代码在所有机器上都一样,但至少能排除「我本地刚好能跑」这一类问题。
2. 检查顺序:先便宜,后昂贵
| 顺序 | 命令 | 抓什么 | 为什么放这里 |
|---|---|---|---|
| 1 | npm run lint |
ESLint:Vue/TS 语法、未使用变量、导入顺序 | 几秒级,先挡低级错误 |
| 2 | npm run lint:styles |
Stylelint:SCSS、Vue 样式、未知属性 | 和 lint 同量级,单独报错更清楚 |
| 3 | npm run format:check |
Prettier:格式是否一致 | 不跑自动修复,只检查 |
| 4 | npm run typecheck |
vue-tsc:模板和类型 |
比 lint 慢,但比构建快 |
| 5 | npm run test |
Vitest:内容管线、tokens、组件 | 单元级,失败定位明确 |
| 6 | npm run build |
Nuxt 生产构建 + 内容校验 | 第一次真正生成产物 |
| 7 | npx playwright install --with-deps chromium |
浏览器依赖 | 只在需要跑浏览器时安装 |
| 8 | npm run test:e2e |
生产构建上的端到端 | 最慢,放在最后 |
| 9 | npm run test:a11y |
axe 扫描 5 页 × 2 主题 | 同样慢,和 e2e 分开报错 |
这个顺序不是随便排的。lint、样式、格式、类型都能在几十秒内给出结果;单元测试通常在一分钟内;构建和浏览器测试则可能要几分钟。如果格式错误留到最后才报,等于让一个空格浪费一整轮 CI。
3. 内容校验放在 build 里
前端没有单独的「内容检查」步骤,而是让 npm run build 自动触发 prebuild:
{
"scripts": {
"prebuild": "node scripts/validate-content.mjs",
"build": "nuxt build"
}
}
这是 npm 的生命周期约定:执行 npm run build 前会先执行 prebuild。脚本会加载 content/notes 和 content/articles,校验 frontmatter、日期、slug、URL 和标签。只要有一篇写错,构建直接失败,后面所有步骤都不会执行。
把校验放在构建前,而不是放在独立的 CI 步骤里,有一个实际好处:本地执行 npm run build 时也会先校验。CI 和本地走的是同一条路径,不会出现「本地能构建、CI 多一步检查却失败」的差异。
4. 浏览器测试测的是生产构建
Playwright 没有连开发服务器:
export default defineConfig({
use: {
baseURL: 'http://127.0.0.1:3200',
trace: 'on-first-retry',
},
webServer: {
command: 'node .output/server/index.mjs',
url: 'http://127.0.0.1:3200',
env: {
PORT: '3200',
HOST: '127.0.0.1',
NUXT_PUBLIC_SITE_URL: 'http://127.0.0.1:3200',
},
timeout: 120_000,
},
})
开发服务器会做热更新、按需编译,和生产产物不是一回事。测试直接启动 .output/server/index.mjs,端口 3200,和线上一样走 Nitro 的 SSR 与静态资源。只有这样才能测到构建后的 CSS Modules 类名、内容资源路由和 404 行为。
端到端覆盖首页、主题切换、目录筛选、系列总览、详情、空标签和 404;axe 则扫首页、目录、两篇详情、系列总览、关于页和聊天页,亮暗两套主题各一遍,另有一条单独检查助手浮窗的用例,端到端与可访问性合计 37 个测试。测试失败时,Playwright 会保留 trace,CI 的 github reporter 会把失败步骤直接标在日志里。
5. image job 只验证 Dockerfile
CI 只能证明列出来的检查项通过了。它不知道文案是否准确、交互是否合理、页面是否符合预期;个人项目没有代码评审,反而更需要保留发布前的手动验收。把 CI 当成底线,而不是唯一的质量来源。
image job 在 check 通过后运行:
- name: Build image
run: docker build --build-arg NODE_IMAGE=node:24-alpine -t ednotes:${{ github.sha }} .
它只验证 Dockerfile 能构建,不登录 ACR,也不推送镜像。正式发布由本地 scripts/publish-image.sh 完成(发布脚本只在私有仓库)。这是有意的边界:CI 负责「代码和镜像定义没有坏」,发布负责「把某个版本送到服务器」。两件事的权限、网络路径和失败处理都不一样,混在一起会让 CI 承担它不该承担的凭证。
坑和限制
1. 一次 CI 实际构建了三次。 check 里有一次 npm run build,test:e2e 和 test:a11y 的脚本又各自 npm run build 一次。总耗时里有相当一部分是重复构建。更合理的做法是先构建一次、让两个 Playwright 项目复用同一个 .output,但这需要调整脚本和缓存策略,当前版本先接受这个成本。
2. Playwright 浏览器安装很慢。 npx playwright install --with-deps chromium 要下载浏览器和系统依赖,在 CI 里可能比测试本身还久。只装 Chromium 是有意的取舍:这个站没有复杂的跨浏览器布局,先用一个浏览器守住核心行为。
3. 没有 Nuxt 构建缓存。 每次 CI 都从 npm ci 开始,.nuxt 和 .output 不复用。好处是干净,坏处是慢。个人项目可以接受;如果以后构建时间成为瓶颈,再考虑缓存 .nuxt 和 npm 缓存。
4. HUSKY=0 只在 CI 设置。 本地提交仍然走 hooks;CI 里不需要也不应该安装 hooks。这个变量只影响当前 job,不会改变仓库配置。
5. 只跑 Chromium 不等于跨浏览器兼容。 如果需要验证 Safari 或 Firefox,得增加 Playwright 项目,测试时间也会相应增加。当前阶段先把可访问性和核心交互固定下来。
6. action 版本要跟着维护。 actions/checkout、actions/setup-node 都有主版本更新。固定大版本能减少意外,但也需要定期看弃用提示,避免某天 runner 升级后工作流突然失败。
适合谁
这篇适合还没给前端项目配过完整 CI 的人,尤其是个人项目:你知道应该跑 lint 和测试,但不确定顺序、超时、权限和浏览器测试该怎么放。它不涉及多环境部署、矩阵构建或自托管 runner;目标是把一条能稳定复现的质量门搭起来,并且知道它的成本在哪里。