stitch-mcp serve 实战指南：本地Vite开发服务器热重载预览全部AI设计页面

stitch-mcp 是一个把 Google Stitch 平台上 AI 生成的 UI 设计带入本地开发流程的 CLI 工具。这篇文章聚焦它的 serve 命令：一条命令即可在本地启动 Vite 开发服务器，将项目里的全部 AI 设计页面挂载为可热重载的网页路由，配合资源代理与磁盘缓存，让你在浏览器中直接预览、走查每一屏设计。

serve 命令是什么？

在 Stitch 平台上，AI 生成的设计以 HTML/CSS 的形式存在于云端，直接走查很麻烦：要么逐屏复制导出，要么反复切换网页。serve 命令解决的正是这个问题——它一次性拉取项目中所有屏幕的 HTML 代码，挂载到一个本地 Vite 开发服务器上，并自动生成一个索引页，每个屏幕都能通过独立 URL 访问。

整个流程只需三步：完成一次初始化 → 运行 serve → 在浏览器中浏览设计。

环境准备：三步完成 stitch-mcp 初始化

serve 依赖有效的 Stitch 认证。如果还没配置过，先运行一次引导向导：

npx @_davideast/stitch-mcp init

向导会依次处理 MCP 客户端选择、认证方式（API Key 或 OAuth）、gcloud 安装、项目选择和 MCP 配置生成，详见 docs/setup.md。两种方式任选其一：

• API Key（推荐）：最简单，只需设置 STITCH_API_KEY 环境变量，无需 gcloud 和令牌刷新
• OAuth：由向导自动完成 gcloud 安装、登录与 Stitch API 启用

初始化完成后，可以用体检命令确认配置健康：

npx @_davideast/stitch-mcp doctor

一键启动本地开发服务器

拿到项目 ID（数字字符串，可在 Stitch 网页地址栏或 view --projects 中找到）后，一条命令即可启动：

npx @_davideast/stitch-mcp serve -p <project-id>

运行后，终端会进入一个交互式界面：顶部显示服务器地址与状态，下方按字母序列出项目内全部屏幕及其路由路径，实现见 src/commands/serve/ServeView.tsx。

按键	操作
↑ / ↓ 或 j / k	在屏幕列表中上下移动
Enter	在浏览器中打开当前选中页面（选中 Index 时打开索引页）
q	退出并关闭服务器

打开索引页后，每个屏幕位于 /screens/{screenId} 路径下，点击标题即可逐屏走查设计。

Vite 开发服务器的 4 个核心能力

serve 底层由 StitchViteServer 封装了一个真实 Vite 开发服务器，而不是简单的静态文件托管，这也是它能"热重载"的原因：

1. 热重载预览

所有屏幕 HTML 通过 virtualContent 插件 以虚拟路由形式挂载，并自动注入 Vite 客户端。当屏幕内容发生变化时，服务器通过 WebSocket 向浏览器推送 full-reload 信号，页面自动刷新，无需手动 F5。

2. 资源代理与 CSS 改写

AI 设计中引用的字体、图片往往来自外部 CDN，直接加载可能遇到跨域或 404 问题。服务器内置了资源代理端点 /_stitch/asset?url=<encoded-url>，所有外部资源都会改由本地服务器代为抓取；CSS 中的 url() 引用也会被自动改写为代理地址，确保字体与图片正确渲染。代理只放行白名单域名（如 Google Fonts、Tailwind CDN 等）且强制 HTTPS，实现见 AssetGateway。

3. 磁盘缓存加速

所有抓取到的资源会缓存在项目目录下的 .stitch-mcp/cache/ 中，二次启动和页面刷新时直接读本地文件，预览速度明显更快。

4. 自动索引页

服务器启动完成后，根路径 / 会自动生成一个深色主题的索引页：显示项目标题，并按字母序列出全部屏幕链接，方便快速导航。

serve 常用参数速查

参数	说明
-p, --project <id>	项目 ID（必填）
-l, --list-screens	以 JSON 列出全部屏幕及其服务器路径，适合脚本集成
--json	非交互模式启动服务器，就绪后输出 JSON 地址，服务器持续运行直到手动终止

交互式模式适合人工预览，--json 模式则适合 CI 或自动化场景，完整参数说明见 docs/command-reference.md。

与 screens / view / site 命令配合走查

serve 不是孤立存在的，搭配其他命令可以覆盖"预览 → 检查 → 建站"的完整链路：

• screens -p <id>：不离开终端即可浏览屏幕缩略图与元数据，按 v 可在浏览器中预览
• view --project <id> --screen <id>：以树状浏览器检查屏幕数据，--serve 参数可通过本地服务器直接提供该屏幕
• site -p <id>：满意后，把屏幕映射为路由，一键生成可部署的 Astro 站点

命令组合逻辑与本文同属 src/commands/serve/ 目录体系，各命令的 Handler 与参数定义（spec）成对出现，便于阅读源码。

常见问题排查

现象	处理方法
提示 SCREENS_FETCH_FAILED	项目 ID 有误或认证失效，先运行 doctor --verbose 查看具体错误
提示"No screens with HTML code found"	该项目下尚无带 HTML 代码的屏幕
Permission Denied	确认 Google Cloud 项目已启用计费、已启用 Stitch API，且账号具备 Owner/Editor 角色
OAuth 令牌过期	建议改用 API Key 认证，或重启代理让令牌自动刷新

更完整的诊断清单见 docs/troubleshooting.md。

写在最后

stitch-mcp 的 serve 命令把"云端 AI 设计"变成了"本地开发资产"：一条命令启动 Vite 开发服务器，热重载、资源代理、磁盘缓存全部开箱即用。对于经常需要评审 Stitch 生成设计的同学来说，它是从 AI 画布走向本地开发工作流最短的一公里。如果预览满意，不妨接着用 site 命令把设计变成真正的网站。