Front-End-Checklist v2 生产发布就绪指南：全链路质量门禁、Vercel 部署配置修复与可复现验证路径

2026-09-03 19:48:39作者：秋泉律Samson

docs/production-launch-readiness.md 是 Front-End-Checklist 仓库 v2 前端上线前的就绪性审查记录：v2 应用本身（生产构建、单测、类型检查、Lint、规则质量门禁、来源校验、MCP 审计、Playwright 冒烟套件）在本地全部通过，唯一的发布阻塞点是 Vercel 项目配置——项目被配成了仓库根目录 + Other 框架预设，导致打包阶段报 No Output Directory named "public" found。读完本文，你将掌握这套 monorepo 的完整就绪验证命令集、每个门禁背后的脚本实现细节，以及修复 Vercel 配置后如何复跑预发演练。

核心结论：阻塞点在部署配置，不在应用编译

就绪审查（本地 readiness sweep，记录于 2026-05-29）对 2026-05-29 的 Vercel 预发演练做了归因：david-dias-digital/frontendchecklist.io 项目当时配置的 Root Directory 为 .、Framework Preset 为 Other。Vercel 成功运行了 monorepo 的 Next.js 构建，但在打包阶段失败，因为它按静态站点约定去寻找根目录下的 public 输出目录，而真正的 Next.js 应用位于 apps/web。

上线前需要将 Vercel 项目设置更新为：

配置项	目标值
Root Directory	`apps/web`
Framework Preset	`Next.js`
Build Command	自动检测，或 `pnpm --filter web build`
Install Command	自动检测的 `pnpm install`
Output Directory	自动检测

更新后的复验步骤是依次执行：

vercel pull --yes --environment preview --scope david-dias-digital
vercel build --yes
# 然后复跑预览环境的冒烟测试

仓库中 apps/web/vercel.json 也佐证了该应用并非静态托管形态：它声明了 git.deploymentEnabled: false（禁用 Git 直推部署）、每天 06:00 的 Supabase keepalive cron 任务，以及针对 mcp.frontendchecklist.io 域名的 rewrite（全部路径转发到 /api/mcp）与 CORS 响应头——这些路由行为都依赖 Next.js 运行时，进一步说明必须用 Next.js 框架预设而不是 Other。

就绪门禁全集：命令与结果

审查记录列出了 14 项本地验证门禁，以下按类别完整列出其命令与结果：

规则内容质量门禁

命令	结果	说明
`pnpm score:rules`	385/385 规则通过，平均分 95%	对 `packages/content/rules` 下全部 385 条规则做结构化评分
`pnpm validate:rule-structure`	385 条规则，0 错误	校验规则文档的结构规范
`pnpm validate:evidence`	385 条规则，0 问题	校验规则的 evidence（证据/代码示例）合规性
`pnpm validate:sources`	385 条规则，0 个失效 URL	实时探测每条规则 frontmatter 中的 sources/resources 链接
`pnpm validate:packages`	通过	校验 npmPackages 元数据（当前语料中尚不存在该类元数据）
`pnpm generate:skills`	生成 385 个 skills	由规则语料生成 `skills/` 目录下的技能文件

工程构建与测试门禁

命令	结果	说明
`pnpm lint`	通过	Biome Lint
`pnpm typecheck`	21/21 任务通过	Turbo 驱动的逐包类型检查
`pnpm test:ci`	16/16 任务通过	Turbo 驱动的逐包单元测试
`pnpm exec turbo build --force`	通过	强制全量生产构建
`pnpm test:e2e:ci`	9/9 冒烟测试通过	Playwright，覆盖 Chromium、Firefox、WebKit
`pnpm mcp:audit`	通过，无 critical 发现	MCP 服务单测 + 安全扫描

其中 vercel build --yes 是唯一失败项，但失败原因是上述项目设置问题，而非应用编译问题。

这些命令在根 package.json 中均有对应脚本定义，例如 score:rules、validate:sources、mcp:audit、test:e2e:ci。仓库还提供了两条组合入口，可以直接复现大部分 CI 行为：

ci:check：串联 lint → typecheck → validate:rule-structure → validate:guide-structure → validate:guides → validate:evidence → test:ci；
ci:e2e：先 build 再 test:e2e:ci。

Turbo 任务图定义在 turbo.json：build 任务声明了 dependsOn: ["^build"]（先构建被依赖的 workspace 包）以及 outputs: [".next/**", "dist/**", "build/**"]，并显式列出了构建所需的约 30 个环境变量（数据库、Better Auth、Sentry、OpenPanel、Resend、Upstash KV/Redis 等），这与下文"生产环境变量体检"的剩余风险直接对应。

门禁实现细节：从源码看三个关键脚本

validate:sources——带降级与重试的 URL 存活校验

pnpm validate:sources 的实现是 scripts/validate/validate-sources.ts。它遍历 packages/content/rules/en 下所有分类目录中的规则 .mdx 文件，用 gray-matter 解析 frontmatter，收集 sources 与 resources 字段中的全部 URL 做真实探测。就绪审查中"降低并发、延长超时、HEAD 转 GET 降级、瞬时故障重试"的加固，在源码里可以一一对应：

并发与超时参数：CONCURRENCY = 5、TIMEOUT_MS = 15000、TRANSIENT_RETRIES = 1；
HEAD→GET 降级与重试循环：先以 HEAD 请求探测，HEAD 不可用或失败时回退 GET，每一层都允许一次瞬时重试；请求携带 User-Agent: frontendchecklist-validator/1.0 并跟随重定向；
分类逻辑抽离到 scripts/validate/source-validation-policy.ts，配合 scripts/validate/source-validation-policy.json 策略文件，支持 --allow-bot-blocked-domain / --allow-bot-blocked-url 等命令行白名单参数；
报告维度包括：缺失来源的规则数、失效 URL 数、被目标站点拦截 bot 但 URL 本身有效的数量、重定向 URL 数量。

mcp:audit——单测加安全扫描两段式

pnpm mcp:audit 对应 scripts/audit/mcp-audit.ts，流程分两段：

通过 turbo test --filter=@repo/mcp 运行 MCP 包单测（脚本第 42-50 行）；
再执行 pnpm dlx mcp-security-auditor@latest scan packages/mcp/src --fail-on critical 做静态安全扫描（脚本第 57-69 行），支持 --skip-security 跳过。

就绪审查中"修复 MCP audit 路径解析、并把安全扫描调用切换为 pnpm dlx"正是针对这段实现的调整——pnpm dlx 避免了对本地安装版本的依赖，保证扫描工具版本始终可复现。完整工具清单与手动验证步骤另见 docs/mcp-quality.md。

规则加载的 ESM/Turbopack 兼容修复

"Fixed During Sweep" 中第一条提到为 @frontendchecklist/rules 恢复了生产构建兼容性：保留 ESM 源码导入，同时补充运行时 JS shim 供 Turbopack 解析。对应证据在 packages/rules 包中：包内同时存在 load-rules.ts（TypeScript ESM 源码）与 load-rules.js（一行式运行时 shim，export { loadRules } from './load-rules.ts'），types.js 与 types.ts 成对出现，就是这个兼容策略的落地形态。load-rules.ts 本身同时支持包内 rules/en 目录与 monorepo 的 packages/content/rules/en 语料目录两个来源，并用轻量正则提取 frontmatter 单行/多行字段，避免引入完整 YAML 解析器。

本次 Sweep 中完成的其他修复

就绪记录（docs/production-launch-readiness.md 的 "Fixed During Sweep" 小节）还列出了以下修复，均可在仓库中找到落点：

将请求级账户鉴权检查包进 Suspense，解决 /profile 页面在 Next.js Cache Components 下的预渲染阻塞；
将 breadcrumb、geo meta、meta refresh、Open Graph、RFC URL 语法等 SEO 规则中脆弱的引用替换为更具体、更稳定的权威来源（服务于 validate:sources 零失效 URL 的结果）;
调高 MCP 性能预算以匹配当前语料规模（385 条规则），同时保留延迟检查；
修正 PR workflow 中 e2e 产物/路径过滤，使其匹配当前 apps/web/e2e 目录布局；
移除了不必要的 header hydration 抑制与页脚装饰性 blob。

浏览器冒烟验证：3 条用例 x 3 个浏览器 = 9/9

pnpm test:e2e:ci 的 9/9 结果构成可以从 Playwright 配置解释：apps/web/playwright.config.ts 定义了三个浏览器工程（Chromium、Firefox、WebKit），CI 模式下每条用例失败重试 2 次、输出 github + html 双报告；未设置 BASE_URL 时由 webServer 配置自动拉起 pnpm exec next start --port 3080 的生产服务再开测。

冒烟用例在 apps/web/e2e/smoke.spec.ts：首页 Hero 标题可见性、/rules 规则列表渲染、/mcp 页面标题渲染共 3 条，在 3 个浏览器工程上执行即 9 次运行，与审查记录一致。

除自动化冒烟外，人工本地生产冒烟还覆盖了：桌面端首页/规则详情/checklist 详情/MCP 页面、移动端首页与移动端菜单、未登录访问 /profile 时回跳到公开首页，以及本地 /api/mcp metadata 端点返回 200 且包含 11 个工具、prompts、resource templates 与安全响应头。

剩余风险与上线后 backlog

审查记录明确区分了"阻塞项"与"遗留风险"，后者不阻塞发布但需在后续跟踪：

SSRF 疑似发现需人工分诊：mcp-security-auditor 对 MCP 请求适配器中 new Request(request.url, ...) 报出两条高危 SSRF 疑似项。由于该处并不发起出站请求，从实现看属于静态分析误报，但在将安全报告标记为"干净"之前仍需完成分诊记录。
MCP 启发式覆盖率 128/135 条规则（94.8%）：缺口属于发布后的质量 backlog，不是当前失败门禁。
React Doctor 仅剩 warning 级清理项：Tailwind size-* 简写、使用 <img> 的 mention 嵌入、多组件 mention 嵌入文件；修复 header 错误后评分为 99/100。
Vercel 预发验证：在 Root Directory 改为 apps/web 并使用 Next.js 框架预设之前无法完成，即本文开头的核心阻塞项。
仅生产环境才生效的检查：Sentry/OpenPanel 环境变量体检、mcp.frontendchecklist.io 线上行为、远程迁移就绪性评审，需要在部署后验证。

复现完整验证路径

把上述门禁串起来，一次完整的本地发布就绪验证可以是：

pnpm install
pnpm ci:check        # lint + typecheck + 规则/指南/证据校验 + test:ci
pnpm score:rules
pnpm validate:sources
pnpm generate:skills
pnpm mcp:audit
pnpm ci:e2e          # turbo build --force 后的三浏览器 Playwright 冒烟

注意适用前提：根 package.json 约束 packageManager: pnpm@10.33.0 且 Node 版本为 >=24.15.0 <25；ci:e2e 依赖先完成生产构建；validate:sources 需要网络访问（含对规则来源站点的真实 HTTP 探测）；mcp:audit 的安全扫描通过 pnpm dlx 拉取工具，需要网络且可被 --skip-security 跳过。完成本地全绿后，再按第一节的 Vercel 配置修复与 vercel pull / vercel build 复验顺序完成预发演练，即与审查记录的结论闭环。