Onlook：在真实 React 代码上直接可视化编辑的开源 AI 前端编辑器｜部署与使用全指南

适用读者：设计师 / 前端工程师，想在自己的 Next.js + Tailwind 项目上像 Figma 那样拖拽改元素、同时让 AI 直接动代码；想自托管一个 Bolt.new / Lovable / V0 开源替代的人。本文所有命令、端口、环境变量均来自 onlook-dev/onlook 仓库根 Dockerfile、docker-compose.yml 与 apps/web/client/.env.example，可放心照做。注意：本仓库是早期浏览器版 Onlook；官方新桌面版（Mac app）源码尚未开源，本文只覆盖仓库内可自部署的 Web 版。

一、Onlook 是什么

Onlook 是一个开源、可视化优先的代码编辑器：你在浏览器里打开自己的 Next.js + TailwindCSS 项目，Onlook 把页面渲染到一个 iframe 里，让你像 Figma 一样直接点选、拖拽、改样式；所有改动会反向写回真实的 JSX/TSX 源码，而不是生成一份脱离代码的设计稿。它对标 Bolt.new、Lovable、V0、Replit Agent、Figma Make、Webflow 一类工具，但代码是你自己仓库里的。

适用场景：你已经有一个 Next.js + Tailwind 项目，想让设计师 / 非工程同学在不碰源码的前提下改文案、调样式、挪布局；或者你想自托管一个 AI 建站工具，而不是把代码交给 SaaS。

能力边界（README 勾选清单原文）：

• 已支持：几秒起一个 Next.js 应用（文本或图片起步、模板起步）、Figma 风格 UI、实时预览、品牌资产与 token 管理、页面与图层管理、图片管理、组件检测（组件检测此前在独立的 Onlook Desktop 仓库做过）、分支实验、实时代码编辑器、检查点保存与恢复、CLI 跑命令、应用市场、分享链接、自定义域名、多人实时编辑、多消息排队；
• 未支持：拖拽组件面板、评论、图片作参考/资产、MCP 配置、让 Onlook 把自己当工具调、非 Next.js 项目、非 Tailwind 项目。

关于新桌面版：docs.onlook.com/developers/running-locally 页面明确写"我们正在准备把新的 Onlook 桌面 app 开源，未来几周内发布"，并强调"当前 Onlook app 没有从源码构建的步骤，不要把旧 Onlook 项目的构建步骤套到它身上"。也就是说，本文档覆盖的 onlook-dev/onlook 仓库是早期浏览器版，与新 Mac 桌面 app 是两套不同代码；桌面版目前只能去 https://onlook.com/install 下载 Mac Apple Silicon 安装包并排 waitlist。

二、功能特性

• 可视化编辑真实 DOM：在 iframe 里画新 div、在父容器内拖拽排序；
• 右键定位源码：任意元素右键即可跳到它在代码里的精确位置；
• 工具栏直接调 Tailwind：选中元素后在工具栏改 Tailwind 样式、对象属性、布局（Flex、间距 8/18/24、字号 Medium、行高 100% 等都在工具栏里点）；
• Design / Code / Preview 三栏：设计稿、源码、预览并排；
• AI 聊天改代码：用自然语言让 AI 新建或改项目，AI 走 OpenRouter；search-replace 改不动时退到 Morph / Relace 的 fast apply；可以一次排队多条消息；
• 分支与检查点：实验性改动走分支，随时保存 / 恢复检查点；
• 分享与发布：生成可分享链接，或绑自己的域名；
• 技术栈（来自 README "Our Tech Stack" 原文）：前端 Next.js（全栈）+ TailwindCSS + tRPC；数据库 Supabase（鉴权 / DB / 存储）+ Drizzle ORM；AI 走 Vercel AI SDK + OpenRouter + Morph Fast Apply + Relace；沙箱与托管用 CodeSandbox SDK + Freestyle；运行时 Bun（monorepo / runtime / bundler）+ Docker。

三、官方界面预览

除开头两张外，官方 README 还给出了一张架构图，说明它怎么把"画布上的操作"映射回代码。其工作原理（README "How it works" 原文七步）：

1. 你创建应用时，Onlook 把代码加载进一个 Web 容器；
2. 容器跑起来并对外提供服务；
3. 编辑器拿到预览链接，用 iframe 显示；
4. 编辑器从容器读取并索引代码；
5. 编辑器对代码做插桩（instrument），把 DOM 元素映射回源码位置；
6. 你在 iframe 里改元素，先改 iframe 里的 DOM，再同步改回源码；
7. AI 聊天同样有代码访问权和工具，可以理解代码并改代码。

官方明确说：这套架构理论上能扩展到任何"用声明式方式渲染 DOM"的语言或框架（jsx / tsx / html），但目前只认真打磨 Next.js + TailwindCSS。

四、官方链接汇总

五、前置要求

• Docker 与 Docker Compose：官方根目录提供 Dockerfile 与 docker-compose.yml，推荐容器化跑；
• Bun 1.3.1：如果你想裸跑而不是走 Docker，需要本机装 Bun（packageManager: bun@1.3.1）；
• 本地 Supabase：.env.example 默认指向 http://127.0.0.1:54321（Supabase API）与 postgresql://postgres:postgres@127.0.0.1:54322/postgres（Postgres 直连）；docker-compose 里声明了一个外部网络 supabase_network_onlook-web，意味着你需要先在同一台机器上把 Supabase 起来；
• API Key：
  • OPENROUTER_API_KEY（必填，AI 聊天走这里）；
  • CSB_API_KEY（必填，CodeSandbox SDK 用来沙箱跑用户应用）；
  • MORPH_API_KEY 或 RELACE_API_KEY（fast apply，二选一可选）；
• 操作系统：Linux / macOS 均可；不支持 Windows 原生路径（容器化跑可绕开）。

六、安装部署

方式 A：Docker Compose（官方推荐路径）

git clone https://github.com/onlook-dev/onlook.git
cd onlook

# 1. 准备环境变量
cp apps/web/client/.env.example apps/web/client/.env
# 然后编辑 apps/web/client/.env，填入你自己的 OpenRouter / CodeSandbox 等 Key

# 2. 构建并启动
bun run docker:build     # = docker compose build
bun run docker:up        # = docker compose up -d

等价的裸 docker 命令：

docker compose build
docker compose up -d

启动后访问 http://localhost:3000。

根 docker-compose.yml 关键内容（照抄）：

services:
  web-client:
    build:
      context: .
      dockerfile: Dockerfile
    env_file:
      - apps/web/client/.env
    ports:
      - "3000:3000"
    restart: unless-stopped
    network_mode: host

根 Dockerfile 关键内容：基础镜像 oven/bun:1，NODE_ENV=production、NEXT_TELEMETRY_DISABLED=1、STANDALONE_BUILD=true、HOSTNAME=0.0.0.0、PORT=3000；执行 bun install --frozen-lockfile 与 cd apps/web/client && bun run build:standalone；启动命令 bun apps/web/client/server.js。Dockerfile 还带一个 HEALTHCHECK，每 30 秒 bun -e "fetch('http://localhost:3000')..." 探活，启动宽限期 5 秒、3 次重试。

关于 network_mode: host 与外部网络：compose 里写了 network_mode: host，意味着容器直接共享宿主机网络栈，这样容器里访问 127.0.0.1:54321 就是宿主机上的 Supabase；同时又声明了一个外部网络 supabase_network_onlook-web（external: true），这是为了让 Onlook 容器能和 Supabase CLI 起的本地栈在同一个 Docker 网络里互通。如果你不用 Supabase CLI 而是自己起的 Postgres，请按你自己的网络命名改这一段，或者直接去掉这行 networks 配置。

方式 B：裸 Bun 跑

git clone https://github.com/onlook-dev/onlook.git
cd onlook
bun install
cd apps/web/client
bun run build:standalone
bun server.js

前提仍是本地 Supabase 已起、.env 已填。

七、配置项说明（apps/web/client/.env）

来自 .env.example 原文，逐项说明：

必填：

可选：

端口固定 3000，由 Dockerfile ENV PORT=3000 与 compose 3000:3000 共同写死；要换端口需同时改这两处。

八、使用流程

1. 起本地 Supabase，确保 54321 / 54322 可访问，并在 apps/web/client/.env 里填好 anon key 与 service role key；
2. 按上一节 docker compose up -d 启动 Web 客户端；
3. 浏览器开 http://localhost:3000；
4. 要么从文本 / 图片 / 模板新建一个 Next.js 应用，要么把你已有的 Next.js + Tailwind 项目导入 Onlook；
5. 在画布上点选元素、拖拽、改 Tailwind 样式；右键任意元素跳到源码对应位置；
6. 用 AI 聊天下指令（"把 hero 区改成深色"、"加一个 pricing 表"），OpenRouter 出代码、Morph/Relace 负责把补丁可靠落到文件；
7. 实验性改动走分支，满意后再合回主线；需要分享时生成链接或绑自定义域名；
8. 团队协作场景下，Onlook 目前已支持实时编辑，但评论功能尚未上线（README 勾选清单里 Leave comments 是未勾选状态）。

九、常用运维 / 更新命令

根 package.json 提供的脚本（均为 bun workspace 过滤器，workspaces 声明了 packages/*、apps/*、tooling/*、apps/web/*、docs）：

更新到最新：git pull origin main && bun run docker:restart。第一次 git pull 后建议先 bun install 刷新 lockfile，再 docker compose build --no-cache，避免容器里用旧依赖起新代码。

十、常见故障排查

十一、风险与责任使用声明

1. 本文命令、端口（3000）、Supabase 默认端口（54321 / 54322）、环境变量均来自 onlook-dev/onlook 仓库根 Dockerfile、docker-compose.yml 与 apps/web/client/.env.example；新版桌面 Mac app 的构建流程官方文档明确写"coming soon"，本文不混用。
2. Onlook 会在沙箱里跑你（或 AI）生成的代码；CSB_API_KEY 对应的 CodeSandbox 额度按你自己账号计费，请设好预算告警。
3. SUPABASE_SERVICE_ROLE_KEY 是绕过 RLS 的高权限 Key，.env 文件不要提交到公开仓库；docker-compose 默认 network_mode: host，生产暴露前请自行加反代与鉴权。
4. AI 生成的代码会直接写进你导入的 Next.js 仓库；建议先在分支上玩，重要改动走 PR review。
5. 许可证 Apache-2.0，可自由自用与二次开发；你接入的 OpenRouter / CodeSandbox / Morph / Relace / PostHog 等第三方服务各自有服务条款，请同时遵守。

关于"能不能用 Onlook 直接做生产站点"：README 明确说当前只打磨 Next.js + TailwindCSS，非 Next.js 或非 Tailwind 项目不支持；多人协作的评论功能还没上线；MCP 配置、图片作资产、让 Onlook 自我迭代这些高级能力也都在未勾选清单里。把它当一个"设计师在真实代码上拖拉拽"的内部工具用是合适的，直接拿它对外交付商业站点前请自己评估成熟度。