网页部署验证 — Trove 组合包

场景

「部署成功」与「网页真实可访问」是两件事。部署脚本说成功，但页面白屏、路由 404、样式没加载——之前只能靠人打开浏览器看。你想要的是：构建完，自动用真实浏览器打开页面断言关键元素与路由，白屏当场被抓。

本组合包把「构建 → 验证」串成确定性链路：Vite 负责构建（内容哈希资源）、playwright-mcp 给 Agent 浏览器控制面（打开页面断言关键元素与路由）。两个工具各管一段，不重复；完整链路已实测 PASS。

组合成员（2）

vite-deploy（前端构建）

下载：npm 包 `vite`（条目名 vite-deploy，官方；国内 npmmirror 前缀）
版本要求：5.0~5.4（2026-08-29 收录实测 5.4.21）

npm install --save-dev vite --registry=https://registry.npmmirror.com
npx vite build

工具手册 →

playwright-mcp（浏览器验证）

下载：npm 包 `@playwright/mcp`；免安装 `npx -y @playwright/mcp@latest`
版本要求：>= 0.0.79（2026-08-29 实测；Node >= 18）

npm_config_registry=https://registry.npmmirror.com npm install -g @playwright/mcp
npx --no-install playwright install chromium

工具手册 →

方案总览

工具	管什么	为什么是它
vite-deploy（Vite）	前端构建（输出侧）	构建产出 dist/，内容哈希资源；npm 生态
playwright-mcp	浏览器验证（验证侧）	真实浏览器断言页面元素/路由；MCP 形态可被 Agent 调用

备选方案：只要「构建」→ 项目已有 Vite 即可；只要「浏览器验证」→ 只装 playwright-mcp。顺序逻辑：先构建（vite build）→ 再验证（playwright 打开页面断言）。

快速开始

一键脚本由本文档自动生成（渲染后位于 pages/combos/combo-web-deploy-verify.sh），逐条执行：

bash pages/combos/combo-web-deploy-verify.sh

装完你会得到：vite build 构建 + playwright-mcp 浏览器验证链路（构建完自动打开页面断言）。
预计耗时：5-10 分钟。最大卡点 = chromium 引擎下载（约 114MiB，实测走 playwright CDN 可下）。
前置条件：Node >= 18；磁盘预留 ~114MiB（浏览器引擎）；无 GUI 环境用 --headless。

想弄明白每一步在干什么、装错了怎么恢复 → 看「逐步教学」。一键脚本出问题 → 按逐步教学手动执行定位。

逐步教学

第 1 步：装 vite（前端构建）

Vite 构建产出 dist/（内容哈希资源）。项目根目录装为 devDependency（npmmirror 前缀），vite build 一条命令出产物。

npm install --save-dev vite --registry=https://registry.npmmirror.com
npx vite build

预期输出: vite build 完成，dist/ 目录出现（实测 5.4.21 构建成功）

装好确认：

npx vite --version 输出版本号（5.x）；
npx vite build 产出 dist/。

卡住怎么办：

npm 慢 → 命令已带 npmmirror registry。
构建报错（依赖缺失）→ 先 npm install 装项目依赖再 build。

第 2 步：装 playwright-mcp（浏览器验证）

playwright-mcp 给 Agent 浏览器控制面：打开页面、断言元素、检查路由。全局安装（npmmirror 实测 3 秒），首次运行需下载浏览器引擎（chromium 约 114MiB，实测 playwright CDN 可下）。无 GUI 环境用 --headless。

npm_config_registry=https://registry.npmmirror.com npm install -g @playwright/mcp
npx --no-install playwright install chromium

预期输出: @playwright/mcp 版本号 + chromium 下载完成

装好确认：

npx --no-install @playwright/mcp --version 输出版本号（0.0.79+）；
起 server 监听 8931（实测）；headless 打开页面冒烟 title=ok（实测）。

卡住怎么办：

npm 慢 → 命令已带 npmmirror。
chromium 下载失败 → 换网络窗口重试；或配 playwright 镜像环境变量。
无 GUI → 运行参数加 --headless。
端口 8931 被占 → --port 换端口。

装完验收（一步到位）

作用：装完跑下面一条命令块，全绿 = 本组合包就绪；某条失败 → 回「逐步教学」对应步骤定位。

npx vite --version
npx --no-install @playwright/mcp --version
npx vite build

预期输出: 5.x；@playwright/mcp 0.0.79+；vite build 完成、dist/ 目录出现（2026-08-29 实测 5.4.21 构建成功）。浏览器断言链路 = 起服务 + playwright-mcp 打开页面断言（chromium 已下载）

注：成员级已实测；无 GUI 环境用 --headless。

日常使用

启动与入口

vite：npx vite build（构建）；npx vite preview（本地预览）。
playwright-mcp：npx --no-install @playwright/mcp（MCP 服务，默认 8931；Agent 通过 MCP 调用）。

常用操作

部署验证链路：vite build → 起静态服务 → playwright 打开页面断言关键元素/路由。
白屏抓取：断言 <title> + 关键元素（如 #hero）存在；缺失即失败（实测链路）。
无头模式：CI 里用 --headless 跑断言。

数据与目录

vite：dist/（构建产物）。
playwright：浏览器引擎 ~/.cache/ms-playwright/（可删，重新 install 即恢复）。

卸载与清理

按安装相反顺序卸载：

# 1. playwright-mcp（npm 全局）+ 浏览器引擎缓存
npm uninstall -g @playwright/mcp
rm -rf ~/.cache/ms-playwright
# 2. vite（项目 devDependency）
npm uninstall --save-dev vite
# 3. 清理构建产物
rm -rf dist

提示：浏览器引擎缓存约 114MiB，卸载时一并清掉。

安装顺序

vite-deploy（构建）→ 2. playwright-mcp（验证）；全装完跑通才算组合就绪。playwright-mcp 首次运行需下载浏览器引擎（~114MiB）。

依赖警告

版本：Node >= 18（两工具 npm 形态）；vite 5.0~5.4（收录实测 5.4.21）；playwright-mcp >= 0.0.79。
环境：磁盘预留 ~114MiB（浏览器引擎）；playwright-mcp 默认监听 8931 端口（--port 可改）；无 GUI 环境用 --headless。
权限边界：playwright-mcp 默认文件访问限 workspace roots；敏感开关需显式开启。
冲突：两工具写面互不重叠（dist/ 构建产物 / 浏览器临时 profile）→ compatible（组合包实测态：2026-08-29 浏览器冒烟通过）。

FAQ

「部署成功」为什么还要验证？ → 部署脚本成功 ≠ 页面可访问（白屏/404/样式丢失都测不出来）。playwright 用真实浏览器断言，白屏当场被抓。
chromium 下载不下来？ → 换网络窗口重试 npx --no-install playwright install chromium，或配 playwright 镜像环境变量。
无图形界面能跑吗？ → 能，--headless 无头模式（完整链路实测就是 headless）。
playwright-mcp 的权限边界？ → 默认文件访问限 workspace roots，敏感开关需显式开启（安全默认）。

验证证据

每份组合包在隔离环境实测（冒烟 + 写面检查），未实测项在文中如实标注；实测日期见下方验证证据。

验证于 2026-08-29 · TTL 到期 2027-02-25（180 天）

2026-08-29：playwright-mcp 0.0.79 实测（npmmirror 3 秒安装；server 启动监听 8931；chromium headless 下载 113.9MiB + 页面冒烟 title=ok）；组合包链路实测见下条。
2026-08-29：vite-deploy 条目收录实测（npmmirror 7s 装 12 包，vite 5.4.21 构建产出 dist/）。
2026-08-29 完整链路实测 PASS：vite 8.2.2 构建 dist/ → python3 http.server 8977 起静态服务 → playwright headless 打开 http://127.0.0.1:8977/ 断言 title=ComboLinkOK + #hero=deployed-ok（证据：实测复现日志（2026-08-29））。

关联问题

← 全部组合包｜工具货架｜遇到问题？去问题空间提交求助卡

场景

组合成员 （2）