screenshot-to-code：AI 驱动的"截图转代码"系统本地部署与架构实践指南

本文基于 screenshot-to-code 仓库的官方 README，完整覆盖从 API Key 配置、后端/前端本地启动到 Docker 一键部署的全部实操步骤，并结合仓库源码验证了多模型提供商路由、截图预览（screenshot preview）工具等关键机制的实现。读完后你将能够独立搭建该开源项目，理解其"截图/录屏 → 多模型并行生成 → 工具调用自我校验"的技术链路，并知道各项配置参数在源码中的真实作用位置。

项目定位与支持的输出栈

screenshot-to-code 的核心能力是：丢入一张截图、mockup、Figma 设计稿，甚至一段网站屏幕录制，由 AI 生成干净、可用的前端代码。README 声明的默认 AI 模型组合包括 Gemini 3 Flash Preview / Gemini 3.1 Pro Preview、GPT-5.5 / GPT-5.4 Mini、Claude Opus 4.6 / 4.8，以及用于图像生成的 z-image-turbo（走 Replicate）。

官方声明支持的输出栈如下：

输出栈	组件	状态
html_css	HTML + CSS	正式
html_tailwind	HTML + Tailwind	正式
react_tailwind	React + Tailwind	正式
bootstrap	Bootstrap	正式
vue_tailwind	Vue + Tailwind	Beta
ionic_tailwind	Ionic + Tailwind	Beta

从源码看，前端栈定义 中的 Stack 枚举与后端的 prompts/types.py 保持同步（文件注释明确要求 "Keep in sync with backend (prompts/types.py)"），Vue 与 Ionic 两个栈被标记为 inBeta: true，枚举顺序同时决定了 UI 下拉框中的展示顺序。

除了静态截图，项目还支持将网站操作的屏幕录制转成可交互原型——README 指出视频模式依赖 Gemini（Gemini Key 是 video mode 的必需项）。

API Key 配置：四把钥匙各自解锁什么

README 给出的 API Key 要求是：至少需要一个模型提供商 Key（OpenAI、Anthropic、Gemini 三选一），Gemini 与 Replicate 被强烈推荐。官方推荐的 Key 配置方式与解锁能力如下：

Key	是否必需	解锁能力
OPENAI_API_KEY	三选一	GPT 系列代码生成模型（GPT-5.5、GPT-5.4 Mini 等）
ANTHROPIC_API_KEY	三选一	Claude 系列代码生成模型（Opus 5、Opus 4.8、Fable 5、Sonnet 4.6 等）
GEMINI_API_KEY	三选一，强烈推荐	Gemini 代码生成模型（3 Flash、3.1 Pro）；负责从截图中提取真实素材（asset extraction）；视频模式必需
REPLICATE_API_KEY	强烈推荐	图像编辑、背景移除、Replicate 驱动的图像生成；缺失时 edit_image 与 remove_background 工具不可用，图像生成会回退到 OpenAI（若已配置）

配置更多 Key 时，应用会为每个生成变体自动组合更强的模型；只配置单一 Key 时则只用该提供商的模型。关于模型与提供商的映射，后端模型定义文件 中有一个权威的 Llm 枚举与 MODEL_PROVIDER 字典，显式把每个模型（含不同思考档位，如 gpt-5.5 (high thinking)、claude-opus-5 (max effort)、gemini-3.1-pro-preview (medium thinking)）绑定到 openai / anthropic / gemini 三个提供商之一，注释明确说明这样做的目的是"不依赖命名约定来判断模型归属"。

这些环境变量在后端入口 backend/config.py 中被集中读取：

# LLM-related
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", None)
ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY", None)
GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY", None)
OPENAI_BASE_URL = os.environ.get("OPENAI_BASE_URL", None)

# Image generation (optional)
REPLICATE_API_KEY = os.environ.get("REPLICATE_API_KEY", None)

值得注意的还有两个与 README 功能对应的配置项：config.py 中的 GENERATION_MAX_COST_USD = 3.0 是每轮生成的硬性花费上限（按变体/评测运行计），以及 NUM_VARIANTS = 4（视频模式为 2），解释了"多模型并行生成多个变体"的实现来源。

Key 的录入有两种途径：写入 backend/.env（Replicate Key 必须走这条途径），或通过前端的设置对话框（应用加载后点击齿轮图标）配置 OpenAI、Anthropic、Gemini——设置对话框还会显示当前后端是否具备 screenshot preview 能力。

本地部署：后端

README 推荐的包管理工具是 Poetry（无 Poetry 先 pip install --upgrade poetry）。完整启动流程：

cd backend
echo "OPENAI_API_KEY=sk-your-key" > .env
echo "ANTHROPIC_API_KEY=your-key" >> .env
echo "GEMINI_API_KEY=your-key" >> .env
echo "REPLICATE_API_KEY=r8_your-key" >> .env
poetry install
# 安装截图预览工具所用的 Chromium 浏览器。
# Linux 下用 `poetry run playwright install --with-deps chromium`
# 一并安装系统依赖库（需要 sudo/apt）。
poetry run playwright install chromium
poetry env activate
# 运行打印出的命令，例如 source /path/to/venv/bin/activate
poetry run uvicorn main:app --reload --port 7001

几点说明：

• 端口：后端默认监听 7001，前端 Vite 开发服务器默认 5173。
• Playwright 步骤并非可选：它是 screenshot preview 工具的运行时依赖（后文详述），但装不上也不会让后端崩溃——Chromium 缺失时应用只是跳过该工具。
• 后端入口：backend/main.py 首先 load_dotenv() 加载 .env，创建 FastAPI 实例（关闭了 OpenAPI docs 路由），并在两个 startup 事件中完成初始化——其中之一就是 probe_screenshot_preview()，用于探测并预热无头 Chromium，"只有真正能运行时才把 screenshot_preview 工具提供给 Agent"。

源码印证：模型路由与工具按 Key 动态启用

provider 工厂 展示了"Key 决定工具可用性"这一 README 承诺的底层实现：

canonical_tools = canonical_tool_definitions(
    image_generation_enabled=should_generate_images,
    # edit_image 工具调用 Replicate，没有 Key 就不提供
    image_editing_enabled=bool(replicate_api_key or REPLICATE_API_KEY),
    # extract_assets 工具调用 Gemini，没有 Key 就不提供
    asset_extraction_enabled=should_extract_assets and bool(gemini_api_key),
    # screenshot_preview 需要无头 Chromium，启动不了就跳过
    screenshot_enabled=is_screenshot_preview_available(),
)

也就是说：extract_assets（复用截图中真实 logo/图片的资产提取）被绑定到 Gemini Key，edit_image 被绑定到 Replicate Key，screenshot_preview 被绑定到 Chromium 是否可用。之后再按所选模型分发到 OpenAIProviderSession / AnthropicProviderSession / GeminiProviderSession，缺失对应 Key 时直接抛出 Exception("... API key is missing.")。

核心机制：Screenshot Preview（截图预览自检）

README 将 Screenshot preview 描述为可选能力：装好 Chromium 后自动启用，让 Agent 在浏览器里渲染自己刚生成的页面并"肉眼检查"成果。其实现链路可以完整追溯到源码：

1. 启动探测：backend/main.py 的 probe_screenshot_preview_on_startup 在 FastAPI 启动时探测 Chromium 并记录结果。
2. 渲染与截图：screenshot 预览工具 的 run_screenshot_preview 会对当前文件内容分别在 desktop 和 mobile 两个视口做 full_page=True 的整页截图；若文件还不存在会返回错误提示"先调用 create_file"。
3. 多模态回传：截图像素通过 ToolMultimodalPart 作为附件字节直接回传给模型，让多模态模型"看到"自己生成的页面来验证布局；工具注释特别说明这些预览图"只用于看、不用于留"——不会被持久化为资产，内联进 summary 的 data URL 仅供 UI 展示缩略图。
4. 前端可见性：设置对话框中显示的"screenshot preview 是否可用"即来自上述探测结果。

这套机制的价值在于形成闭环：模型不只是"写完代码就结束"，而是能像人一样预览渲染结果、发现溢出/错位并继续迭代修改。

本地部署：前端

cd frontend
pnpm install
pnpm dev

启动后访问 http://localhost:5173 即可使用。若后端跑在非默认端口，需在 frontend/.env.local 中更新 VITE_WS_BACKEND_URL。

从 前端配置 可以补充一个 README 未展开的细节：当未显式设置 VITE_WS_BACKEND_URL / VITE_HTTP_BACKEND_URL 时，默认回退到当前页面同源地址（window.location.origin），并配合 Vite dev-server 代理工作。这一设计的注释写明目的是让应用在隧道/预览 URL 环境下也能正常工作——此时 localhost 指向的可能是查看者自己的机器而非沙箱内的后端。

Docker 一键部署

安装了 Docker 后，在仓库根目录执行：

echo "OPENAI_API_KEY=sk-your-key" > .env
docker-compose up -d --build

应用同样跑在 http://localhost:5173。README 提醒：这套方式不能用于开发，因为文件改动不会触发重新构建。

对照 docker-compose.yml 可以看到两个服务的具体编排：

• backend：以 ./backend/Dockerfile 构建，env_file: .env 注入密钥，端口映射 ${BACKEND_PORT:-7001}:${BACKEND_PORT:-7001}，启动命令为 poetry run uvicorn main:app --host 0.0.0.0 --port ${BACKEND_PORT:-7001}。文件内注释提示：若修改 BACKEND_PORT，记得同步修改 frontend/.env.local 中的 VITE_WS_BACKEND_URL。
• frontend：以 ./frontend/Dockerfile 构建，固定映射 5173:5173。

常见问题（FAQ）与排查

README 的 FAQ 覆盖了最常见的部署问题，这里完整继承并结合源码路径给出定位：

1. 后端启动报 OpenAI 相关错误 / 无法直连 OpenAI API？

可以配置 OpenAI 代理（proxy）：在 backend/.env 中设置 OPENAI_BASE_URL，或在 UI 设置对话框中直接修改。关键要求是 URL 路径中必须包含 v1，例如 https://xxx.xxxxx.xxx/v1。从源码看，该值经 config.py 读取后，直接作为 AsyncOpenAI(api_key=..., base_url=openai_base_url) 的 base_url 参数传入 OpenAI 客户端（见 factory.py）。若仍无法解决，可查看仓库自带的 Troubleshooting.md，其中也说明如何获取 OpenAI API Key。

2. 如何更新前端连接的后端主机？

在 frontend/.env.local 中同时配置 VITE_HTTP_BACKEND_URL 和 VITE_WS_BACKEND_URL（一个走 HTTP、一个走 WebSocket），例如 VITE_HTTP_BACKEND_URL=http://124.10.20.1:7001。这两个变量在 frontend/src/config.ts 中分别导出为 HTTP_BACKEND_URL 与 WS_BACKEND_URL。

3. Windows 下运行后端出现 UTF-8 编码错误？

用 Notepad++ 打开 .env，在 Encoding 菜单中选择 UTF-8 保存即可。

4. 想用 Ollama 开源模型跑？

README 明确标注"不推荐，因为生成质量较差"，并指向项目 issue #354 下的社区评论方案。

5. 其他排查入口：仓库还附带了 QA.md（质量清单）、TESTING.md（测试说明）、Evaluation.md（评测体系）等文档，backend 目录下有大量针对 provider 配置、资产提取、模型选择、截图预览等模块的 pytest 测试（如 test_screenshot.py 同级的 tests 目录）。后端开发时可在 backend 目录运行 poetry run pyright 做类型检查、poetry run pytest 跑测试，并用 backend/utils.py 的 print_prompt_summary 快速可视化某次请求发给 LLM 的完整 prompt。

生成效果与多模型对比机制

README 的 Examples 部分展示了纽约时报页面、Instagram、Hacker News 的"原截图 → 生成复刻"对比与录屏演示（以远程媒体形式嵌入 README，可查阅 README.md 原文查看动图）。

其背后的批量生成机制在源码中同样有据可查：backend/config.py 定义了 NUM_VARIANTS = 4（图像模式）与 NUM_VARIANTS_VIDEO = 2（视频模式），配合 README 中"配置多个 Key 时自动挑选更强的模型组合"的说法，可以推断每次生成会并行调用多个模型提供商的多个思考档位变体，供用户在界面上挑选最满意的产出。前端的 variants 组件 与 设计文档 进一步描述了这一变体系统的运作方式。

延伸阅读

围绕 README 的主线，仓库中还有几份与部署、架构直接相关的材料值得继续深入：

• design-docs/agent-tool-calling-flow.md：Agent 工具调用流程，理解 extract_assets、screenshot_preview 等工具如何编排；
• design-docs/agentic-runner-refactor.md 与 backend/agent/：Agent 运行器的重构设计与实现，含 provider 会话层（providers/factory.py）与工具运行时（tools/runtime.py）；
• Evaluation.md 与 backend/evals/：截图转代码质量的评测体系；
• backend/README.md：后端的类型检查、测试与 prompt 可视化快捷操作。

至此，从 README 出发、经源码印证，screenshot-to-code 的本地部署路径已完全闭环：配置 Key（backend/.env 或设置对话框）→ poetry install + Chromium → uvicorn main:app --port 7001 → pnpm dev → http://localhost:5173。理解"Key 与工具的绑定关系"和"截图预览自检闭环"这两个点，是掌握该项目技术内核的关键。