GitHub 7.3万 Star！截图直接变代码，这个 AI 项目把原型稿搬进终端编码流程

产品同学扔过来一张截图，说“按这个做一版”。终端里的 AI 编码代理当然能写前端，但麻烦总卡在第一步：你得先把布局规则、颜色值、字号层次、交互状态一点一点用文字描述清楚。话说少了，它容易自由发挥；说多了，你自己都快变成人肉标注工具。

小G最近仔细看了一个老牌开源项目，叫 screenshot-to-code。

Image

它要解决的正是这个环节：把截图、设计稿导出的图像、网页录屏，先转化成一份能直接运行的前端代码。然后你再把这份代码交给 Codex、Claude Code 这类终端 AI 编码代理，去拆组件、接接口、补状态管理，整个过程会比面对一个空白文件高效许多，来回沟通的成本明显下降。

先说清楚，它本身并不是终端 CLI 代理。

它是一个 Web 应用，前端用 React/Vite，后端用 FastAPI。在本地跑起来后，你在页面上传截图或视频，系统通过模型生成代码，并在浏览器里直接预览效果。小G更愿意把它当成“终端编码代理前面的 UI 草稿机”。

Image

它到底能生成什么

这个项目当前支持的前端技术栈有 6 种：

  • HTML + Tailwind
  • HTML + CSS
  • React + Tailwind
  • Vue + Tailwind
  • Bootstrap
  • Ionic + Tailwind

Image

输入也不限于单一图片。一次最多可以上传 5 张截图，或者 1 个视频；支持的格式包括 PNG、JPG、MP4、MOV、WebM；单个文件上限 20MB，视频提示最长 30 秒。另外也支持通过 URL 截图，但需要配置 ScreenshotOne API Key。

这里有一个容易产生误解的地方。README 里提到了 Figma designs，但当前前端代码中，直接粘贴 Figma 链接会提示不支持。正确的用法是把 Figma 画板截图，或者导出成图片，再通过 Upload 入口上传。这不是大问题，但别把它当成可以“直接接入 Figma 文件”来使用。

值得留意的设计思路

很多截图转代码工具，早期本质上就是把图片直接塞给模型，然后等待它返回一段 HTML。而 screenshot-to-code 现在的代码已经朝 Agent 工作流程迈进了一步。后端里，每个候选方案都会调用 Agent(...).run(model, prompt_messages)，生成过程可以走工具调用。当前可用的工具包括 create_file、edit_file、generate_images、remove_background、edit_image、extract_assets、screenshot_preview、retrieve_option 等。

这直接影响到后续的返工量。比如，截图中包含 logo、商品图、头像等元素时，项目会让模型优先调用 extract_assets 从输入图里提取可复用的素材；对于缺失或无法提取的图片，再按照配置回退到图片生成流程。而生成出的页面，不是只靠人眼检查，screenshot_preview 会使用 Playwright 在本地 Chromium 中渲染当前 HTML，同时抓取桌面端和移动端两张截图，继续交给模型判断和优化。源码里这两个视口的尺寸也写死了：desktop 是 1280×832，mobile 是 342×684。

前端返工常常卡在间距、换行、移动端挤压、颜色偏差等细微问题上。让模型自己看一遍渲染结果，至少能把一部分肉眼返工提前拦住。当然，也别把它定位成专业级的设计走查工具。它生成的是单文件前端原型，系统提示里也明确要求主文件使用 index.html。即使你选择 React + Tailwind，它也是通过浏览器可直接运行的脚本和样式来拼出一版页面。拿到结果后，真要进生产项目，还是需要交给终端编码代理继续拆文件、接入数据、替换成项目内的组件写法。

多候选比单次生成更实用

在当前的 config.py 里，创建新页面时默认跑 4 个 variant；更新已有结果时跑 2 个；视频模式同样跑 2 个。这种多候选设计，对截图转代码的场景非常实用。UI 还原没有唯一答案，面对同一张图，Claude 可能在排版上更擅长，Gemini 可能对视觉元素理解更好，OpenAI 的某个模型或许补充交互细节更到位。项目会根据你配置了哪些 Key 来选择模型组合，多个候选通过 WebSocket 并行生成，前端再让你快速切换比较。

小G这里不泛泛地说“生成质量更高”，因为这需要具体的 benchmark 验证。但按照当前源码能够确认的是，这套机制减少了把宝全押在单一模型上的风险。这比对着唯一一版结果反复说“再像一点”要来得合理。先把最接近截图的那一版挑出来，后面只做局部修改，反馈也会更加聚焦。

本地怎么跑

只是想简单试用，可以直接访问官方托管站：https://screenshottocode.com/。

本地部署主要适合两类人：一类是想深入修改源码，另一类是不想把自己的模型 Key 放到托管站里。README 当前推荐前后端分开启动。后端先配 Key，再安装依赖和 Chromium：

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
poetry run playwright install chromium
poetry env activate
poetry run uvicorn main:app --reload --port 7001

前端单独启动：

cd frontend
yarn
yarn dev

最后打开本地页面：

http://localhost:5173

不想分两个窗口依次启动，也可以走 Docker：

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

这些 Key 不必全部填满。项目要求 OpenAI、Anthropic、Gemini 至少提供一个；README 当前更推荐使用 Gemini 和 Replicate。Gemini 负责截图理解、素材提取和视频模式，Replicate 负责图片生成、去背景和图片编辑。如果没有 Replicate，edit_image 和 remove_background 会不可用，图片生成能力会在配置了 OpenAI 时回退到 OpenAI。

如何与终端编码代理配合

小G会把它放在流程的最前面：先丢截图或录屏，选定输出技术栈，让它生成 2 到 4 个候选版本；从中挑一版最接近的，在页面里做一两轮局部微调，比如“按钮再小一点”“移动端菜单按录屏里的方式展开”。

到这里基本就该停手了。后面更适合交给终端里的 AI 编码代理去完成。让代理把这件单文件代码塞进真实项目中，拆组件、接路由、连接口，替换成项目已有的 UI 库，再补充 loading 态和错误态。

如果你期待它从一张图直接产出能够合入生产仓库的高质量前端代码，那预期确实偏高了。截图里看不到的数据结构、接口状态、权限逻辑、响应式细节，它都只能靠猜测来完成。

还有隐私问题。本地部署并不等于完全离线运行，截图、提示词和生成过程依然会传递给你所配置的模型供应商处理。README 提到可以使用 Ollama 运行开源模型，但项目方的口径是不推荐，原因是输出质量较差。因此，涉及内部后台、客户数据或未发布产品稿时，不要随手丢到托管站，至少先确认素材是否能外发。

写在最后

screenshot-to-code 适合解决一个很窄但频率很高的问题：你手上已经有视觉参考，却不想从零开始用文字逐点描述 UI。

它产出的东西更像一份可编辑的样稿。真实项目里的接口状态、组件规范、异常处理、权限逻辑，它看不到，也无法自动对齐你仓库里的架构。所以小G建议把它停留在起稿这一步：前端 demo、落地页、后台页面复刻，或者把产品截图先变成一份能交给 Agent 继续加工的代码。

另外，仓库目前没有 release/tag，Key 调用也会产生费用，截图内容还会进入你配置的模型供应商。试用阶段没有问题，但要进入正式工作流之前，这些因素需要提前想清楚。

项目地址：https://github.com/abi/screenshot-to-code