企业官网建设流程全解析

• 后端
• 前端

Blitz 是一个构建在 Next.js 之上的全栈框架 monorepo，其贡献流程的核心在于一套覆盖「单元测试 + 跨浏览器端到端集成测试」的自动化体系。本文以仓库根目录的 CONTRIBUTING.md 为骨架，结合packages/、integration-tests/下的真实源码与配置，完整讲解从安装浏览器驱动、准备本地依赖，到执行pnpm test跑通全量测试的每一步，并深入剖析测试工具链在源码层面的工作原理，帮助你在提交 PR 之前高效、正确地验证自己的改动。

一、仓库形态速览：一个 Turbo + pnpm 的 monorepo

在动手跑测试之前，先认清仓库的组织方式。根目录的 package.json 声明了以下 workspace：

{ "name": "blitz-root", "version": "0.0.0", "private": true, "workspaces": ["apps/*", "packages/*", "integration-tests/*", "recipes/*"], "scripts": { "preinstall": "npx only-allow pnpm", "prepare": "husky install", "build": "turbo run build", "dev": "turbo run dev --filter='./packages/*'", "lint": "turbo run lint", "test": "turbo run test" }, "packageManager": "pnpm@8.6.6", "npmClient": "pnpm" }

关键信息如下：

• 包管理器强制为 pnpm：preinstall阶段通过only-allow pnpm拦截其他包管理器，因此安装依赖请统一使用pnpm install；packageManager字段锁定了pnpm@8.6.6。
• 任务编排走 Turbo：build、test、lint、dev均由 turbo.json 中的 pipeline 驱动，test任务声明了"dependsOn": ["^build"]，意味着运行测试前会自动先构建其上游依赖包。
• workspace 组成：pnpm-workspace.yaml 中列出apps/*、packages/*、integration-tests/*、recipes/*四个目录族。packages/下是核心源码包（blitz、blitz-auth、blitz-next、blitz-rpc、codemod、generator、config等），integration-tests/下则是按功能域拆分的端到端测试应用（auth、rpc、middleware、next-13-app-dir、trailing-slash 等）。

二、运行测试的前置条件：先装好浏览器驱动

CONTRIBUTING.md 明确指出：运行测试前，请确保为你的 Chrome 版本安装了chromedriver。集成测试需要真实浏览器驱动来驱动端到端场景，驱动版本与浏览器版本不匹配会导致测试无法启动或行为异常。

2.1 三种安装方式

文档提供了三种安装途径，可任选其一：

# macOS brew install --cask chromedriver # Windows（chocolatey） chocolatey install chromedriver

第三种是手动下载：从 chromedriver 的官方发布仓库下载与你已安装的 Chrome 版本匹配的驱动版本，并将二进制放入<next-repo>/node_modules/.bin。原文档中的<next-repo>是沿用了上游 Next.js 仓库的措辞，在 Blitz 仓库中对应的就是仓库根目录的node_modules/.bin（pnpm 安装后命令软链均集中在此），这样测试工具才能通过PATH找到驱动。

2.2 版本匹配原则：宁低勿高

文档特别强调了一条版本选择规则：

如果找不到与你 Chrome 版本完全一致的驱动版本，请下载略低于当前版本的那一档，而不要选择高于当前版本的驱动。

这是因为 chromedriver 对浏览器是向前兼容的——旧驱动可以驱动新版浏览器，而新驱动往往无法驱动旧版浏览器。这条规则是本地测试环境搭建中最容易踩坑的点，务必遵守。

2.3 驱动在测试工具链中的真实位置

Blitz 的集成测试工具直接依赖chromedriver包：integration-tests/utils/package.json 的 devDependencies 中锁定了"chromedriver": "100.0.0"，因此单纯pnpm install也会在依赖中携带一份驱动。

浏览器驱动由 integration-tests/utils/browsers/ 下的封装层消费：

• base.ts 定义了统一的BrowserInterface抽象（elementByCss、click、waitForElementByCss、eval、getValue等能力）。
• playwright.ts 是默认实现，基于playwright-chromium，默认以headless 模式启动 Chromium（const headless = !!process.env.HEADLESS || true），并支持BROWSER_NAME=safari/firefox切换 WebKit 与 Firefox。
• selenium.ts 是备选实现，支持 BrowserStack 云测（BROWSERSTACK环境变量）、本地 Selenium Server（默认localhost:4444/wd/hub）、HEADLESS（无头模式固定 1280x720 视口）以及CHROME_BIN（自定义 Chrome 可执行文件路径）等扩展点。

入口 next-webdriver.ts 则根据BROWSER_NAME（默认chrome）选择合适的浏览器，并在页面加载后等待 React 水合（hydration）完成，确保测试断言不会在首屏渲染未完成时误判。

2.4 关于 Rust / 原生包的说明

CONTRIBUTING.md 还提到：部分测试可能需要安装 Rust 工具链并构建原生包（yarn --cwd packages/next build-native）。需要说明的是，这段指引同样沿用了上游 Next.js 仓库的贡献文档措辞——当前 Blitz 仓库的packages/目录下并不存在packages/next（实际是blitz、blitz-auth、blitz-next、blitz-rpc、codemod、generator等纯 TypeScript/JavaScript 包），仓库也未内置 Rust 原生模块。因此对 Blitz 仓库而言，常规贡献场景无需安装 Rust；只有当你 fork 的版本引入了新的原生依赖时，才需要参考该段说明处理二进制构建。

三、运行全量测试：一条命令搞定

完成驱动安装和依赖安装后，在仓库根目录执行：

pnpm test

其背后执行的是根 package.json 中的turbo run test。根据 turbo.json 的 pipeline 定义：

{ "pipeline": { "build": {"dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"]}, "test": {"outputs": ["coverage/**"], "dependsOn": ["^build"]} } }

test任务会自动先执行其依赖包的build（即"先构建、再测试"），测试产物输出到coverage/**。由于各 workspace 的test脚本统一为vitest run（例如 packages/blitz/package.json 中的"test": "vitest run"），因此pnpm test会在所有 workspace 中批量执行 Vitest 测试。

如果你的改动只涉及某个包，可以缩小范围以节省时间：

# 只测试核心 CLI 包 pnpm --filter blitz test # 只测试某个集成测试应用 pnpm --filter test-auth test

单包测试的超时阈值可见 packages/blitz/vitest.config.ts：testTimeout: 5000 * 60 * 2（即 10 分钟），集成测试用例中普遍会显式传入与之一致或更长的超时参数（见下文）。

四、集成测试是如何跑起来的：源码级拆解

集成测试并不是简单地对某个函数做断言，而是真实启动 Blitz/Next.js 应用、用浏览器访问页面并校验行为。以 integration-tests/auth/test/index.test.ts 为例，其典型流程是：

1. 通过findPort()找一个空闲端口；
2. 用blitzBuild()/blitzStart()（生产模式）或blitzLaunchApp()（开发模式）启动被测应用；
3. 用webdriver(appPort, "/authenticated-page")拉起浏览器访问页面；
4. 断言页面元素、HTTP 响应头与 Cookie（如anti-csrf头、会话 CookiesPublicDataToken等）。

这些能力全部封装在 integration-tests/utils/next-test-utils.ts 中：

• runBlitzCommand：以node子进程方式执行blitz二进制（位于blitz包构建产物dist/index.cjs），并设置NODE_ENV=production与__NEXT_TEST_MODE=true；
• blitzLaunchApp：等价于blitz dev -p <port>，以 stdout 出现Ready标记作为启动成功信号；
• blitzBuild/blitzStart：分别对应blitz build与blitz start -p <port>；
• runDevSuite/runProdSuite：同一套用例在 dev 与 prod 两种模式下重复执行的标准套件封装。

被测应用通过blitzCLI 启动，其命令注册表在 packages/blitz/src/cli/index.ts：dev/build/start是核心命令（并支持d/b/s短别名），export、new、generate、codegen、db、console、routes等也在此注册。CLI 还会自动为build/start默认注入NODE_ENV=production，并监听SIGTERM/SIGINT以便在 Docker 等容器环境中优雅退出。这些细节决定了集成测试中"构建后进程不会悬挂"的可靠性。

以 auth 集成测试为例，测试声明式地组合了这些工具（见 integration-tests/auth/test/index.test.ts 开头部分）：

import {describe, it, expect, beforeAll, afterAll} from "vitest" import waitPort from "wait-port" import {killApp, findPort, runBlitzCommand, blitzLaunchApp, blitzBuild, blitzStart} from "../../utils/next-test-utils" import webdriver from "../../utils/next-webdriver"

而 integration-tests/auth/package.json 中的test脚本即vitest run，测试前还可通过blitz prisma migrate deploy（prisma:start）准备数据库迁移。

五、常见问题与排查

1. pnpm test报找不到浏览器：绝大多数情况是 chromedriver 缺失或版本不匹配。先执行chromedriver --version核对版本，再对照 2.2 节的"宁低勿高"原则重新安装，并把二进制放进仓库根目录的node_modules/.bin。
2. 包管理器被拦截：仓库强制 pnpm（only-allow pnpm）。请勿使用npm install或yarn，统一pnpm install。
3. 测试跑得很慢 / 超时：集成测试涉及真实启动服务与浏览器，单用例超时常为5000 * 60 * 2毫秒（10 分钟），属正常设计。排查时可先缩小范围，仅运行pnpm --filter <package> test，或对单个用例临时缩短超时以快速定位。
4. 只想验证一个功能域：进入对应integration-tests/<domain>目录，先执行pnpm run prisma:start（如需要数据库迁移），再pnpm test。
5. 修改了 CLI 或核心包源码后测试不生效：turbo 的testpipeline 依赖^build，请先确保pnpm build成功；或使用pnpm dev（对应turbo run dev --filter='./packages/*'）进行增量构建。

六、提交前的最后一步

在本地完整跑通pnpm test后，建议：

• 运行pnpm lint（turbo 聚合各包的 ESLint 检查）与pnpm format（Prettier 统一格式）；
• 仔细阅读 Blitzjs.com 上的完整贡献指南（CONTRIBUTING.md 首行指向的官方文档），确认 PR 规范、变更日志与发布流程；
• 提交前留意 husky 预提交钩子（根 package.json 的prepare: husky install），它会自动执行 lint-staged 相关检查。

总结一下：跑通 Blitz 仓库测试的三步是——按版本匹配规则装好 chromedriver →pnpm install安装依赖 → 根目录执行pnpm test。理解 next-test-utils.ts 与 browsers/ 的分层设计后，你还能根据自己的场景定制集成测试的启动方式，让贡献过程更加从容。

• 后端
• 前端