Screenshot to Code 新手教程

丢一张截图、Figma 稿或一段录屏，AI 把它变成干净可用的前端代码。本教程主线：在 Cursor CLI 里把它跑起来、用明白，再让「它出初版 + Cursor agent 接力」形成工作流。

Python 3.10+ 6 种技术栈 Gemini / GPT / Claude MIT GitHub 仓库

78.9k+

GitHub Stars（2026-09）

6 种

输出技术栈

4 家

模型提供商可接

MIT

开源协议

1这是什么

Screenshot to Code（作者 Abi Raja，2023-11 开源，MIT）把截图 / 设计稿 / 录屏交给多模态大模型，生成可直接运行的前端代码。

支持的输出技术栈一共六种：HTML + Tailwind、HTML + CSS、React + Tailwind、Vue + Tailwind、Bootstrap、Ionic + Tailwind。默认接入的代码生成模型有 Gemini 3 Flash Preview、Gemini 3.1 Pro Preview（README 原话：当前最好的两个）、GPT-5.5 与 GPT-5.4 Mini、Claude Opus 4.6 / 4.8；图像生成走 Replicate 的 z-image-turbo。它还能「看视频」：上传一段网页操作的录屏，直接还原成可交互原型。

形态先掰正：它不是 CLI 工具，是一个本地 Web 服务——FastAPI 后端 + React/Vite 前端，前端通过 WebSocket 连后端，生成过程流式实时预览。所以「在 Cursor CLI 中使用」不是敲一条转码命令，而是三条路：让 Cursor agent 把服务跑起来、让 agent 遵守项目纪律去改造它、以及把它的产物交给 agent 继续工程化。

它不做什么（反向界定）

没有官方命令行。终端里「用」它 = 起服务 + 浏览器操作；想纯命令行批量跑，得借 run_evals.py 这类自带脚本（第 9 节讲）。
不做像素级 100% 复刻。产出是质量很高的初版：布局、配色、字体、间距都对，但细节（精确的动效、响应式断点）仍要人工收尾。
不写业务逻辑。它只管「界面长得对」，不接数据库、不写路由和状态管理——那是 Cursor agent 的活。
不是免费的。烧的是你自己的 LLM API key，一轮生成是多轮 agent 循环，token 消耗远高于一次普通问答。
不需要它家账号。全本地运行，代码、截图、生成结果都不出你的机器（只有模型 API 调用走公网）。

2为什么需要

「把设计稿变成代码」你大概率试过下面三条路，每条都有熟悉的失败姿势。

常见做法	问题	失败现场
照截图手写 HTML/CSS	纯体力活，全靠肉眼比对	一张中等复杂度的落地页数小时起步；间距、字号、渐变色差一点就是「一眼假」
截图丢给通用聊天机器人	一次性输出，没有视觉反馈回路	文字描述永远有信息损耗；logo 被模型「重画」成抽象画；改一轮要重新贴一次图
直接让 Cursor 空手写	需求靠文字转述，模型脑中无图	你说「卡片圆角带阴影居中」，它脑中的图和设计稿差了三版迭代

Screenshot to Code 的核心洞察是把「一个 prompt 转一次」升级成带视觉反馈的 agent 流水线：

素材真实提取——用 Gemini 从你的截图里把 logo、主视觉图、图标原样抠出来复用，而不是让模型凭记忆重画。抠出来的素材按内容哈希命名（asset_<sha256前24位>.png），生成页面里用的就是像素级原图。
自渲染自检——装了 Playwright Chromium 后，agent 会把自己生成的页面渲染成截图再喂给自己检查，形成「写 → 看 → 修」闭环。这正是它比裸 prompt 强的根本原因。
流式 + 可迭代——生成过程逐块流到前端实时预览，跑完不满意可以直接对话改：「把导航栏改透明」「间距放大一档」。

3核心流程

三步：丢图 → 后端 agent 流式生成并自检 → 前端实时预览、迭代、导出。

1 上传截图 / 录屏→ 2 agent 流式生成 + 自检→ 3 预览迭代导出

整条链路里，后端是主角：它按你选的模型分发请求（llm.py），跑素材提取（asset_extraction.py），调 Replicate 补图抠背景，还会用无头 Chromium 把生成的页面渲染出来「自查」。前端只负责把流式结果拼起来实时预览，以及提供对话式改稿的入口（这个「改稿 agent」的引擎就在 backend/agent/ 里）。

4安装

三条路线按用途选：要改造项目走本地手动，只想用走 Docker，云端 agent 环境有官方一键脚本。

路线	前置	关键命令	适合谁
本地手动（推荐）	Python 3.10+ + Poetry、Node 20+ + pnpm	`poetry install` → `uvicorn` → `pnpm dev`	要开发、改造、加模型的人
Docker	Docker	`docker-compose up -d --build`	只想跑起来用，不碰代码
Cursor Cloud	无（依赖自动装）	`bash scripts/cursor-cloud-install.sh`	在 Cursor 云端环境跑 agent

最容易混的两件事：① key 配置有两条路——backend/.env 支持全部四种 key，而前端 Settings 对话框（齿轮图标）只认 OpenAI / Anthropic / Gemini，Replicate 只能写 .env；② Docker 是「用」不是「开发」——容器里改代码不会热更，想改项目必须走本地手动。

本地手动：后端

cd backend
echo "GEMINI_API_KEY=your-key" > .env
echo "OPENAI_API_KEY=sk-your-key" >> .env
echo "ANTHROPIC_API_KEY=your-key" >> .env
echo "REPLICATE_API_KEY=r8_your-key" >> .env

poetry install
# 装截图预览用的 Chromium（Linux 加 --with-deps 还要装系统库）
poetry run playwright install chromium
poetry env activate        # 打印出 source 命令，执行它激活虚拟环境
poetry run uvicorn main:app --reload --port 7001

.env 最少写一个能用的 key 就能跑（没有 key 生成会直接报 "No OpenAI, Anthropic, or Gemini API key"）。写完或改完 .env 要重启后端才生效。

本地手动：前端

cd frontend
pnpm install
pnpm dev
# 打开 http://localhost:5173

想换后端端口的话，改 frontend/.env.local 里的 VITE_WS_BACKEND_URL（默认 ws://127.0.0.1:7001）。

Docker 一把梭

echo "GEMINI_API_KEY=your-key" > .env
docker-compose up -d --build
# 起来后同样打开 http://localhost:5173

5环境自检

动手前 30 秒自检，能省掉 80% 的安装翻车。

python3 --version   # 需 3.10+（pyproject 钉 ^3.10，3.12 实测没问题）
poetry --version    # 没有：pip install --upgrade poetry
node --version      # 前端是 Vite，新版本 Node 即可
pnpm --version      # 没有：npm i -g pnpm 或 corepack enable
docker --version    # 只有走 Docker 路线才需要

API Key	必需？	解锁什么
`OPENAI_API_KEY`	三选一	GPT-5.5 / GPT-5.4 Mini 代码生成
`ANTHROPIC_API_KEY`	三选一	Claude Opus 4.6 / 4.8 代码生成
`GEMINI_API_KEY`	强烈推荐	Gemini 代码生成（当前最佳）；截图素材真实提取靠它；视频转代码模式必需
`REPLICATE_API_KEY`	强烈推荐	图像生成、图像编辑、背景去除（没有它 `edit_images` 和 `remove_backgrounds` 都不可用）

关键二选一：想顺手改这个项目（加模型、调 prompt）→ 本地手动，别犹豫；只想出几次代码 → Docker 也行，但改 key 之后要 docker-compose restart，改代码则必须回本地路线。key 拿得越全，每轮生成自动用上更强的模型组合。

6第一次实战：让 Cursor CLI 把它跑起来

screenshot-to-code 本身自带 AGENTS.md——项目为 AI agent 写好了协作纪律，Cursor CLI 天然兼容。所以第一次实战的正确姿势是：把整件事交给 Cursor agent 当施工队。

前提：Cursor CLI 已装好并登录（你日常用 Cursor 的那套入口就行），手里至少有一个 LLM API key。

第 1 步：把这段任务指令丢给 Cursor agent

# 在终端进入你放项目的目录，启动 Cursor CLI 后粘贴：
帮我跑通 github.com/abi/screenshot-to-code：
1. git clone https://github.com/abi/screenshot-to-code.git && cd screenshot-to-code
2. 在 backend/.env 写入我提供给你的 GEMINI_API_KEY（其他 key 我稍后给）
3. cd backend && poetry install && poetry run playwright install chromium
4. 后台启动后端：poetry run uvicorn main:app --reload --port 7001
5. cd frontend && pnpm install && pnpm dev（后台启动）
6. 确认 7001 / 5173 两个端口都在监听后告诉我
全程遵循项目 AGENTS.md 的约定。

agent 会自己处理依赖、报错重试和端口占用。它做的事等价于下面这份手动命令（第 4 节已给全，此处不复述）——但建议你扫一眼第 4 节，知道 agent 每一步在干什么，出问题时才接得住。

第 2 步：三件事验证跑通了

浏览器打开 http://localhost:5173——注意必须是 localhost，写成 127.0.0.1:5173 会拒绝连接（Vite 只绑 localhost，项目 AGENTS.md 里专门警告过这一条）。
点右下角齿轮开 Settings——看 Screenshot preview 是否显示 Available（Chromium 装成功就有；没装只是跳过自检工具，不报错，很容易被忽略）。
丢一张 UI 截图，选 HTML + Tailwind——应该看到代码逐块流式出现、右侧预览实时刷新。首图建议用你自己 App 的界面，素材提取的效果最有感知。

跑通标志：生成过程中浏览器 DevTools 的 Network 面板能看到一条到 ws://127.0.0.1:7001 的 WebSocket 长连接，生成完不中断。连不上时优先查后端 7001 是否活着、.env 的 key 是否生效（改过 .env 必须重启后端）。

7产物结构：生成的是什么

输出永远是「拿起来就能跑」的前端代码——HTML 类栈基本是单文件，React/Vue 栈是组件 + Tailwind class。

HTML + Tailwind / HTML + CSS / Bootstrap：一个自包含的 HTML 文件（Tailwind 栈走 CDN），浏览器双击即开，适合直接复制进任意项目。
React + Tailwind / Vue + Tailwind：组件化的 JSX/Vue 单文件组件，粘进你的工程补个 import 就能用。
Ionic + Tailwind：移动端组件风格，适合 Ionic 工程。

想二次开发或读源码，backend 的目录地图在这（都是一手仓库结构）：

路径	干什么
`backend/main.py`	FastAPI 入口：HTTP 路由 + WebSocket 通道
`backend/agent/`	内置对话编辑 agent（engine / runner / state / tools），「改稿」「再生成」靠它
`backend/asset_extraction.py`	从截图抠真实素材（logo / 主图 / 图标），按内容哈希存
`backend/preview_screenshot/`	agent 自渲染自检：无头 Chromium 截图生成结果再喂回模型
`backend/video/`	录屏转可交互原型
`backend/prompts/`	各模型的 system prompt，调教输出风格的入口
`backend/llm.py`	模型调用分发（OpenAI / Anthropic / Gemini）
`backend/run_evals.py`	headless 批量评估入口（第 9 节）

8怎么用：栈怎么选、会发生什么

同一个截图，六种栈怎么挑？按「代码最终去哪」倒推。

你的场景	选这个栈
快速 demo、静态落地页、给 Cursor agent 当参考稿	HTML + Tailwind
并进现有 React 工程	React + Tailwind
Vue 工程	Vue + Tailwind
不想要任何 CDN / 构建依赖的朴素页面	HTML + CSS
维护中的老项目就是 Bootstrap	Bootstrap
Ionic 移动端工程	Ionic + Tailwind

✅ 会发生：代码逐块流式输出；多变体并行生成（不同模型各出一版横向对比）；截图里的 logo 和图片被原样抠出来用；生成完可以对话式改稿（「把 hero 区背景改成深色渐变」）；录屏上传后还原成可交互原型。

❌ 不会发生：像素级 100% 一致（97 分和 100 分之间是你收尾的距离）；自动接入你的设计 token、路由、状态管理；替你写业务逻辑和接口对接。

9进阶：和 Cursor CLI 的组合工作流

单点工具的价值有限，真正的杠杆是分工：视觉还原交给它，工程整合交给 Cursor agent。

接力 prompt 模板

# 在你自己的工程里启动 Cursor CLI，把导出的代码放进项目后粘贴：
这是 screenshot-to-code 从设计稿生成的初版页面（src/views/landing-generated.tsx）。
帮我做工程整合：
1. 样式对齐现有 design tokens（颜色/圆角/字体全部换成我们的 CSS 变量）
2. 静态假数据换成 src/api/ 里的真实接口
3. 拆分出可复用组件，接入现有路由
4. 过一遍 eslint，别引入新警告

改造这个项目本身

想给它加模型、调 prompt？Cursor CLI 会自动读仓库根目录的 AGENTS.md，项目纪律是现成的：每次改后端代码必须跑 poetry run pytest 和 poetry run pyright（改动文件不允许新增警告），动前端跑 pnpm lint，两边都动了就都跑。直接把需求丢给 agent（比如「在模型列表里加一个新的 OpenAI 变量」），它会带着这套纪律干活。

没有界面的命令行批量跑

项目自带的评估脚本能当 headless 批量转码用：把截图放进 backend/evals_data/inputs，在 backend/run_evals.py 里设好 STACK 和 MODEL 变量，然后 OPENAI_API_KEY=sk-... python run_evals.py，输出落在 backend/evals_data/outputs。调试生成质量时再开 PROMPT_REPORTS_ENABLED=1 + LOGS_PATH，每次 LLM 请求的完整工具调用与产物会落到日志，在 /evals/prompt-reports 页面翻——比盯着界面猜可靠得多。

10不止于此：五个真实场景

名字叫 screenshot-to-code，但真正的高频用法往往不在名字里。

老页面复刻改版——把旧版页面截图转成新版代码基线，再让 Cursor agent 换色换字换布局，改版从「重写」变「修改」。
竞品界面打样——看到值得参考的界面，截图转代码看它的实现手法（尺寸、间距、响应式），只做参考不做抄用（版权边界见第 13 节）。
录屏 → 可交互原型——产品演示视频丢进去，得到能点的原型，需求评审不用再「你想象一下这里能点」。
Figma 交付加速——设计稿导出图直接转代码，前端从「切图」变「校对 + 整合」。
前端学习镜像——新手把喜欢的界面转成代码，对照读「这个视觉效果原来这么写」，比任何教程都具体。

11性能与成本

「哪个模型好」这个问题，项目给了可复现的答案机制，不用信玄学。

仓库自带评估体系（Evaluation.md）：一个 16 张截图的固定数据集，run_evals.py 对每种「模型 × prompt × 技术栈」组合批量生成，人工按 1–4 分在 /evals 页面打分，每组合跑三次取平均。你完全可以自己跑一遍，用自己常用的界面类型得出结论。

选择	建议
日常快速出稿	Gemini 3 Flash——快，质量在线，且素材提取和视频模式都靠 Gemini
质量优先定稿	Gemini 3.1 Pro（README 标注 best models 之一）或 Claude Opus 4.8
多 key 并存	App 自动按变体挑更强的模型组合，每轮可以横向对比多个模型输出
省钱姿势	探索阶段用 Flash / GPT-5.4 Mini，版式确定后用 Pro / Opus 收尾

成本提醒：一轮生成是「多轮 agent 循环 + 素材提取 + 可能的自渲染检查」，token 消耗远高于一次普通对话；Replicate 的图像生成按张另计。别拿最贵的模型反复试错——先用便宜的把版式磨好。

12FAQ / 踩坑

前四条都来自项目 AGENTS.md 的官方警告，属于「不踩不知道，一踩半小时」系列。

打开 127.0.0.1:5173 连接被拒绝？

用 http://localhost:5173。Vite dev server 只绑 localhost，127.0.0.1 会被拒绝——AGENTS.md 原话「the latter refuses the connection」。同理 WebSocket 默认地址是 ws://127.0.0.1:7001，改后端端口时要同步改 frontend/.env.local 的 VITE_WS_BACKEND_URL。

生成时报 "No OpenAI, Anthropic, or Gemini API key"？

两种情况：key 没写进 backend/.env（或写错了名字）；或者刚写完没重启后端——.env 改动必须重启 uvicorn 才生效。另外注意 REPLICATE_API_KEY 只认 .env，在前端 Settings 里配是没用的。

pnpm lint 报一堆 @typescript-eslint/no-explicit-any？

基线预存错误，不是你弄坏的。lint 以 --max-warnings 0 跑，仓库里 generateCode.ts 等文件本来就带着历史 any。AGENTS.md 的要求是「改动文件不允许新增警告」，存量别去动它。

Poetry 虚拟环境名字带 py3.12，文档不是说 3.10 吗？

pyproject 钉的是 ^3.10，3.12 满足条件所以 Poetry 建了 3.12 的环境，完全正常。AGENTS.md 里作者自己都写了「The Poetry virtualenv resolves to Python 3.12, not 3.10 — just use poetry run」。一律 cd backend && poetry run <命令>，别手动找 venv 路径。

pnpm install 警告 Ignored build scripts (esbuild, puppeteer)？

无害，直接用。AGENTS.md 确认 Vite 构建和测试不受影响，不需要去批准这些构建脚本。

Docker 模式改了代码没反应？

正常，容器里没有热更。Docker 路线定位是「跑起来用」；要开发必须走本地手动路线（poetry + pnpm dev），改完自动 reload。

Settings 里看不到 Screenshot preview？

Chromium 没装。执行 cd backend && poetry run playwright install chromium（Linux 要 --with-deps 补系统库），装完重启后端。注意缺失时 App 只是静默跳过自检工具、不报错——生成质量会默默打折，值得装。

生成很慢或者中途断流？

先查是不是模型商限流：QA.md 建议一次只跑一个场景、别并发叠加多变体（每轮多变体会同时压向模型提供商）。其次确认网络能直连各家 API。慢不一定是你环境的问题——3.1 Pro / Opus 这级模型本来就比 Flash 慢。

13合规与版权

工具是 MIT 的，但「生成的代码」和「上传的截图」各有各的边界。

工具本身：MIT，随便用随便改，商用无碍。
生成的代码：模型输出，布局与视觉风格本身通常不受版权保护；但拿去 1:1 复刻受保护的品牌界面仍有风险，商用前自己评估。
素材提取功能：它只是把你上传截图里的像素原样抠出来复用——抠自己团队的 logo、自己买版权的图没问题；别拿它抠竞品的 logo 和品牌素材商用，那一步的版权责任在你。
API key 成本归你：所有模型调用走你自己的 key，注意别把 .env 提交进 git（仓库 .gitignore 已处理，你自己新建的项目记得也带上）。

14参考链接

官方资源清单，教程内容均以 2026-09 抓取的仓库 main 分支为准。

GitHub 仓库：github.com/abi/screenshot-to-code
官方托管版（不想配 key 可先试）：screenshottocode.com
Agent 协作纪律：AGENTS.md
评估体系说明：Evaluation.md
依赖工具：Poetry · pnpm · Docker

仓库结构速览

screenshot-to-code/
├── AGENTS.md            # agent 协作纪律（Cursor CLI / Claude Code 都读它）
├── backend/             # FastAPI 后端
│   ├── main.py          # 入口：路由 + WebSocket
│   ├── agent/           # 对话编辑 agent 引擎
│   ├── asset_extraction.py
│   ├── preview_screenshot/
│   ├── video/
│   ├── prompts/         # 各模型 system prompt
│   └── run_evals.py     # headless 批量评估
├── frontend/            # React + Vite + pnpm
├── scripts/
│   └── cursor-cloud-install.sh   # Cursor Cloud 一键装
└── docker-compose.yml