screenshot-to-code：把截图/设计稿直接转成可用代码的开源 AI 工具｜部署与使用全指南
适用读者：想把一张网页截图、Figma 设计稿或一段录屏"喂"给 AI 后直接拿到前端代码的开发者、独立建站者、UI 还原工程师。本文所有命令、端口、环境变量均来自官方 README，可直接照做；不写 star 数，版本类信息以官方仓库最新说明为准。
一、项目简介
screenshot-to-code 是 abi 开源的一个本地 Web 应用，作用是把截图、模型稿（mockup）、Figma 设计稿，甚至一段网站操作录屏，转换成干净、可运行的前端代码。它的定位不是"生成一整个后台系统"，而是把视觉稿还原成静态/半静态前端页面——HTML、Tailwind、React、Vue、Bootstrap 这类栈。
项目本体是一个前后端分离的应用：前端是 React + Vite，后端是 FastAPI（Python），通过大模型 API 完成"看图 → 写代码"的过程。官方同时提供一个托管版 https://screenshottocode.com ，不想配环境的可以先去那里点一点；自托管的价值在于 Key 自己管、代码自己留、可以改源码接内部模型。
核心信息一览表
| 项目 | 内容 |
|---|---|
| 仓库 | https://github.com/abi/screenshot-to-code |
| 官方托管版 | https://screenshottocode.com |
| 技术栈 | 前端 React/Vite，后端 FastAPI（Python） |
| 前端默认端口 | 5173（pnpm dev） |
| 后端默认端口 | 7001（uvicorn main:app --reload --port 7001） |
| 包管理 | 后端 Poetry，前端 pnpm |
| 可选运行方式 | 本地源码运行 / Docker Compose |
| 必配依赖 | 至少一个大模型 Key（OpenAI / Anthropic / Gemini 三选一） |
适用场景
- 拿到一张设计稿截图，想快速还原成可在浏览器打开的 HTML/Tailwind 页面；
- 想把某个网页的视觉效果"抄"成前端原型做学习参考；
- 需要把 Figma 稿或录屏转成可迭代的前端代码骨架；
- 自托管一套"截图转代码"工具，避免把设计稿上传到第三方 SaaS；
- 设计/前端协作时，设计师出图、AI 出第一版代码，工程师在上面接着改。
能力边界（务必先读）
- 它生成的是前端页面代码，不是完整全栈应用；后端逻辑、数据库、鉴权不会自动写出来；
- 不保证像素级 1:1 还原，官方 README 明确建议搭配 Gemini（负责提取截图里真实 logo/图片素材）与 Replicate（负责图片生成、抠图、图片编辑）才能拿到最好效果；
- 开源版需要你自己准备模型 API Key 并承担调用费用；
- 对录屏模式（video mode），官方 README 标注需要
GEMINI_API_KEY。
二、功能特性
- 多栈输出：官方 README 列出的支持栈包括 HTML + Tailwind、HTML + CSS、React + Tailwind、Vue + Tailwind、Bootstrap、Ionic + Tailwind；
- 多模型可切换：默认支持 Gemini 3 Flash Preview、Gemini 3.1 Pro Preview、GPT-5.5、GPT-5.4 Mini、Claude Opus 4.6 / 4.8 等代码生成变体；并通过 Replicate 调用 z-image-turbo 做图片生成。配得 Key 越全，一次生成里能自动组合的模型越强；只配一个 Key 就只用那一家；
- 素材复用：配了
GEMINI_API_KEY后，可以从截图里直接提取真实 logo / 图片素材，而不是让模型凭空画；这也是官方 README 把 Gemini 标为"强烈推荐"的主要原因； - 图片后处理：配了
REPLICATE_API_KEY后，开放edit_images（图片编辑）与remove_backgrounds（抠背景）两个工具；没配这两个工具在设置面板里就是灰的； - 截图自校验（Screenshot preview）：后端装好 Chromium
后，agent
可以把自己生成的页面在无头浏览器里跑一遍、自己截图检查哪里不对；缺
Chromium 时自动跳过该工具，设置面板会标明是否可用；Linux 下要
poetry run playwright install --with-deps chromium才会把系统库一起装好（需要 sudo/apt）； - 录屏转原型：支持把一段网站操作录屏转成可交互原型；该模式依赖
GEMINI_API_KEY； - 设置面板：前端加载后点齿轮图标，可以在 UI 里直接填
OpenAI / Anthropic / Gemini Key（Replicate 仍必须写在
backend/.env），不用每次改文件重启； - 代理友好：OpenAI 直连不通时，在
backend/.env或设置面板设OPENAI_BASE_URL走代理，URL 必须带/v1； - 前后端分离：前端 Vite 5173、后端 FastAPI
7001，前端通过
VITE_HTTP_BACKEND_URL/VITE_WS_BACKEND_URL连后端，方便把后端单独部署到服务器上跑，本地只起前端。
三、官方界面预览
下面这组图来自官方 README 的 Examples 章节，左为原始 NYTimes 网页截图，右为 screenshot-to-code 生成的复刻页面。
四、官方链接汇总
| 资源 | 地址 |
|---|---|
| GitHub 仓库 | https://github.com/abi/screenshot-to-code |
| 官方托管版（免部署试用） | https://screenshottocode.com |
| OpenAI Key 申请 | https://platform.openai.com/api-keys |
| Gemini Key 申请 | https://aistudio.google.com/ |
| Anthropic Key 申请 | https://console.anthropic.com/ |
| Replicate Key 申请 | https://replicate.com/ |
| 故障排查官方文档 | https://github.com/abi/screenshot-to-code/blob/main/Troubleshooting.md |
五、前置要求
按官方 README，本地源码运行前需要准备：
| 项 | 要求 |
|---|---|
| Python | 后端用 Poetry 管理；官方 README 建议先
pip install --upgrade poetry |
| Node 包管理器 | 前端用 pnpm（官方 README 直接给的是
pnpm install / pnpm dev） |
| 模型 Key | 至少一个：OPENAI_API_KEY /
ANTHROPIC_API_KEY /
GEMINI_API_KEY；强烈推荐再加
REPLICATE_API_KEY |
| 浏览器（可选） | Playwright + Chromium，用于"截图自校验"；Docker 镜像内已自动装好 |
| Docker 路线 | 需要本机装有 Docker 与 docker-compose |
官方 README 提到：如果想用 Ollama 跑开源模型也可以，但官方明确标注"不推荐，效果较差"，做法见 issue #354 下的一条评论，本文不展开。
先想清楚走哪条路：只是想体验一下，直接打开 https://screenshottocode.com 官方托管版最快；要长期用、Key 自己管、或者要接内部代理，再按下面本地或 Docker 路线部署。本地源码路线改代码方便，但要同时管 Python（Poetry）与 Node（pnpm）两套依赖；Docker 路线一键起，但改代码不会热更新，不适合二次开发。
六、安装部署
方式 A：本地源码运行（推荐折腾党）
- 克隆仓库并进入后端目录：
git clone https://github.com/abi/screenshot-to-code.git
cd screenshot-to-code/backend- 在
backend/.env里写入模型 Key（官方原文照抄）：
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 下用下面这条同时装好系统依赖（需要 sudo/apt）：
# poetry run playwright install --with-deps chromium
poetry run playwright install chromium
poetry env activate
# 按提示执行打印出来的那条激活命令，例如：
# source /path/to/venv/bin/activate
poetry run uvicorn main:app --reload --port 7001- 另开一个终端，启动前端：
cd screenshot-to-code/frontend
pnpm install
pnpm dev- 浏览器打开 http://localhost:5173 即可使用。
方式 B：Docker Compose（最省事）
在仓库根目录执行：
echo "OPENAI_API_KEY=sk-your-key" > .env
docker-compose up -d --build启动完成后访问 http://localhost:5173 。官方 README
同时提醒：这种方式下改代码不会自动重新构建，不适合二次开发；.env
里至少要写一个模型 Key，后端才能正常起来。
七、配置项说明
| 配置项 | 位置 | 说明 |
|---|---|---|
OPENAI_API_KEY |
backend/.env 或前端设置面板 |
启用 GPT 系列代码生成（GPT-5.5、GPT-5.4 Mini） |
ANTHROPIC_API_KEY |
backend/.env 或前端设置面板 |
启用 Claude 系列（Opus 4.6 / 4.8 等） |
GEMINI_API_KEY |
backend/.env 或前端设置面板 |
启用 Gemini 代码生成；负责从截图提取真实素材；录屏模式必需 |
REPLICATE_API_KEY |
仅 backend/.env（设置面板不可填） |
启用图片编辑、抠图、Replicate 图片生成；缺它则
edit_images / remove_backgrounds 不可用 |
OPENAI_BASE_URL |
backend/.env 或设置面板 |
配 OpenAI 代理；URL 路径里必须带 v1，例如
https://xxx.xxxxx.xxx/v1 |
VITE_HTTP_BACKEND_URL |
frontend/.env.local |
前端连接的后端 HTTP 地址，例如
http://124.10.20.1:7001 |
VITE_WS_BACKEND_URL |
frontend/.env.local |
前端连接的后端 WebSocket 地址；改后端端口时必须同步改这里 |
三个代码生成 Key（OpenAI / Anthropic / Gemini）是三选一关系；配得越全，前端在一次生成里能组合的模型越强。
八、使用流程
- 启动后端（7001）与前端（5173）；
- 浏览器打开 http://localhost:5173 ；
- 首次进入点右上角齿轮图标，在设置面板里填好已有的模型 Key（Replicate
除外，它必须写在
backend/.env，改完要重启后端）； - 在主界面上传一张截图 / 设计稿，或粘贴一段录屏；
- 选择目标栈（HTML+Tailwind、React+Tailwind、Vue+Tailwind、Bootstrap、Ionic+Tailwind 等）与模型；
- 点击生成，等待后端调用模型返回代码；如果装了 Chromium，agent 会自己在无头浏览器里预览一遍再交回结果；
- 在预览区查看生成结果，可继续用自然语言让模型改局部，例如"把导航栏改成毛玻璃""卡片圆角加大"；
- 满意后把生成的代码拷走，落到自己的项目里；需要图片素材时，Gemini 会从原截图里抽出来一并给你。
九、常用运维 / 更新命令
# 拉取最新代码
git pull
# 后端依赖更新
cd backend && poetry install
# 前端依赖更新
cd frontend && pnpm install
# Docker 路线重新构建
docker-compose up -d --build
# 后端改代码后自动热重载（已在 --reload 模式下）
# 前端 pnpm dev 也是热更新，无需手动重启十、常见故障排查
| 现象 | 原因 / 处理 |
|---|---|
| 后端启动报错 | 官方 README 指向 issue #3 的一条评论给出通用修法；仍不行就开 issue |
| 不知道去哪拿 OpenAI Key | 看官方 Troubleshooting.md（见链接汇总） |
| 国内直连 OpenAI 报错 | 在 backend/.env 或设置面板设
OPENAI_BASE_URL，URL 必须含 /v1 |
| 前端连不上后端 | 检查 frontend/.env.local 里的
VITE_HTTP_BACKEND_URL 与 VITE_WS_BACKEND_URL
是否指向真实后端地址与端口 |
| 后端启动报 UTF-8 错误 | Windows 下用 Notepad++ 打开 .env，把编码切成 UTF-8
再保存 |
| 设置面板里"截图自校验"不可用 | 没装 Chromium；执行
poetry run playwright install chromium（Linux 加
--with-deps） |
| 端口被占用 | 后端把 --port 7001 改成别的端口，同时同步改
frontend/.env.local；前端 Vite 默认 5173，被占用时按 Vite
提示换端口 |
edit_images / remove_backgrounds
不可用 |
没配 REPLICATE_API_KEY；该 Key 只能写在
backend/.env |
| 录屏模式没反应 | 没配 GEMINI_API_KEY，录屏模式依赖 Gemini |
| Docker 路线起不来 | 先在仓库根目录写好 .env（至少一个模型 Key），再
docker-compose up -d --build；改 .env 后要重新
up |
| 生成的页面样式对不上 | 截图越清晰、设计越规整效果越好；复杂字体/动效/第三方组件建议生成后手动改；Replicate 与 Gemini 配全效果明显更好 |
| 想把后端放到服务器、本地只跑前端 | 在服务器上跑后端，本地 frontend/.env.local 里把
VITE_HTTP_BACKEND_URL 与 VITE_WS_BACKEND_URL
指过去即可，注意 WebSocket 端口要放行 |
十一、风险与责任使用声明
- 本文所有命令、端口（5173 / 7001）、环境变量名、模型名均来自官方 README 与官方 Troubleshooting 文档，不构成任何第三方担保；版本类信息以官方仓库最新说明为准；
- 调用 OpenAI / Anthropic / Gemini / Replicate 的 API
会产生真实账单，请自行在各平台控制台设置额度告警；Key
写在
backend/.env里，不要把这个文件提交到公开仓库； - AI 生成的前端代码可能包含不安全写法（内联事件、未转义 HTML、外链第三方脚本等），上线前必须自行审计；
- 本项目生成的是视觉还原代码，不得用于未经授权复刻受版权保护的网站、品牌 UI 或商业产品界面；仅可用于学习、自有项目或已获授权的设计稿还原；
- 开源版按其仓库许可证发布；官方托管版 screenshottocode.com 是独立商业产品，与自托管版不是一回事，两者的模型配额、隐私政策、计费方式都各自独立。