Onlook 开源可视化编辑器完整指南：从看懂原理到跑通部署的新手快速上手方案-酒店常州论坛

Onlook 开源可视化编辑器完整指南：从看懂原理到跑通部署的新手快速上手方案

【免费下载链接】onlookThe Cursor for Designers • An Open-Source AI-First Design tool • Visually build, style, and edit your React App with AI项目地址: https://gitcode.com/GitHub_Trending/on/onlook

如果你想在浏览器里直接拖拽、改样式，同时自动产出能运行的 React 代码，Onlook 正是一个值得了解的开源项目。它把自己定位成"设计师的 Cursor"：一个以 AI 为核心的可视化编辑器，让你在 Next.js + TailwindCSS 项目里边看边改，页面与代码实时同步。本指南不堆术语，先用几分钟讲清它是怎么工作的，再带你从选部署方式、本地跑通，一路走到服务器部署和功能验收，每一步都给出可以直接照做的命令。

先别急着装：Onlook 到底适合谁

在动手之前，先花 30 秒判断它是不是你当前需要的工具，能少走很多弯路。

场景	是否推荐	原因
设计师想直接产出可运行的 React 页面	推荐	提供类 Figma 的可视化界面，改动即时反映到代码
前端团队想在现有 Next.js 项目上加速 UI 迭代	推荐	直接复用代码库，边预览边编辑
用 AI 聊天方式快速搭原型、落地页	推荐	支持文字或图片生成项目，并排队发送多条指令
项目不是 Next.js 或没用 TailwindCSS	谨慎	目前重点优化这两者，其他框架暂未支持
需要 99.9% 以上可用性的关键生产服务	谨慎	单机 / Docker Compose 方案偏简单，关键业务建议走云部署

简单说：个人尝鲜、小团队用、做原型都很合适；一旦面向大规模生产，就要提前规划高可用方案。

3 分钟看懂 Onlook 可视化编辑器的工作原理

很多人觉得"改个按钮文字就能同步到代码"很神奇，其实它的核心就是一条闭环：你在编辑器里改元素 → 先把改动应用到页面（DOM）→ 再把改动写回代码 → 页面重新渲染。这样你既看到即时效果，代码库也始终是真实、可维护的。

把视角拉远一点，整套系统分成三大块：

Web 客户端：你看到和操作的编辑器界面，里面同时维护一个"AST 索引"（把代码结构记下来）和一个 iFrame（用来预览运行中的页面）。
开发容器：真正跑你项目代码的沙箱环境，对外提供开发服务器，供 iFrame 加载。
数据库与外部服务：Supabase 负责登录、存储和项目数据，AI 能力则由多家大模型提供方支撑。

它的工作流程可以概括为：加载代码进容器 → 容器运行并服务页面 → 编辑器拿到预览链接放进 iFrame → 读取并索引代码 → 给代码"插桩"以记住每个元素对应代码里的哪一段 → 你编辑元素时，先改 iFrame 里的页面，再改回代码 → AI 聊天同样拥有读写代码的工具。官方也提到，这套架构理论上可以扩展到任何"声明式输出 DOM"的语言或框架（如 JSX / TSX / HTML），只是当前阶段优先把 Next.js 和 TailwindCSS 打磨好。

它背后用到的技术栈

理解技术栈有助于你判断依赖、排查问题：

层次	技术	作用（一句话）
前端	Next.js、TailwindCSS、tRPC	全栈应用、样式、前后端通信
数据库	Supabase、Drizzle	认证、存储、ORM
AI	AI SDK、OpenRouter、Morph / Relace	调用大模型、快速落地代码改动
沙箱与托管	CodeSandbox SDK、Freestyle	运行开发容器、对外托管预览
运行时	Bun、Docker	管理这个 Monorepo、跑容器

部署前怎么选：本地、Docker 还是单机服务器

Onlook 的自托管文档给了四条路线，本质差别在于"你想让多少人用、跑在哪里"。先选对路线，后面的命令才不会白敲。

路线	适合谁	特点
本地开发	想体验、想贡献代码的人	最快，直接在本机跑，边开发边改
单机（standalone）	5–50 人小中团队、想省心生产	一个自包含构建，不依赖容器，最简生产
Docker Compose	已在用 Docker、需要隔离的环境	容器化，适合开发与预发
云部署	大企业、要高可用与监控	多区域、合规、冗余，成本最高

建议：新手先从本地开发跑通，确认功能符合预期后，再根据团队规模决定上单机还是 Docker Compose。

最快上手：6 步在本地跑起 Onlook

下面这套步骤来自官方"本地开发"文档，目标是让编辑器在http://localhost:3000打开。

先确认环境已安装（缺一不可）：

Bun（这个仓库用的包管理器和运行时）
Docker（用于启动后端数据库等服务）
Node.js，版本至少v20.16.0，建议用最新版，注意避开v20.11.0

然后按顺序执行：

克隆仓库并进入目录，安装依赖：

git clone https://gitcode.com/GitHub_Trending/on/onlook cd onlook bun install

启动后端（它会拉起本地 Supabase，并打印出 anon key 和 service role key，先记下来）：
```
bun backend:start
```
准备好三类 API 密钥，之后填进环境变量：
- CodeSandbox 的 Token（用于跑开发容器）
- OpenRouter 的 API Key（用于 AI 聊天）
- Morph 或 Relace 的 Fast Apply Key，二选一（用于快速落地代码改动）
这些密钥都需前往对应平台后台创建，注意别把明文写进公开的地方。
运行交互式脚本，把上面这些密钥和环境变量一次性写好：
```
bun run setup:env
```
初始化数据库结构，再用测试数据填充（方便直接登录体验）：
```
bun db:push bun db:seed
```
启动开发服务器：
```
bun dev
```

打开浏览器访问http://localhost:3000，看到下面的编辑器界面，就说明本地环境跑通了。

团队长期使用：把 Onlook 部署到服务器

本地跑通后，如果要让同事也能用，就有两种常见生产方式，命令都很短。

Docker Compose 方式（适合容器化团队）

前置条件：机器满足 4 核以上 CPU、8GB 以上内存（建议 16GB）、50GB 以上磁盘，且装有 Docker 与 Docker Compose。

克隆并安装依赖：

git clone https://gitcode.com/GitHub_Trending/on/onlook cd onlook bun install

配置环境变量：bun run setup:env
启动后端服务：bun backend:start
初始化数据库：bun db:push
启动容器：
```
docker-compose up -d
```

根目录的 docker-compose.yml 只定义了一个web-client服务，它用根目录的 Dockerfile 构建、映射 3000 端口、设置"异常自动重启"，并采用 host 网络模式，以便容器能连到宿主机的 Supabase 服务。启动后用docker-compose ps查看状态，再访问http://你的服务器IP:3000即可。

提醒：这套 Compose 方案是"单容器、无负载均衡"的简单部署，适合 10 人以下团队、开发和预发环境；如果追求高可用，请看官方云部署文档。

单机 standalone 方式（最简单的生产）

如果你不想碰容器，可以在一台虚拟机上直接跑独立构建，步骤几乎一样，只是最后一步换成构建并启动 standalone 应用：

克隆并安装依赖，bun run setup:env配置环境变量
bun backend:start启动后端
bun db:push初始化数据库
构建独立生产构建：
```
bun run preview:standalone
```

它会产出一个自带依赖的独立 Node 服务加静态资源，直接对外提供服务即可。细节见单机部署文档。

部署成功了吗：先验证这 3 个功能

别只看到"页面打开了"就完事。建议按下面三点快速点一遍，确认核心能力都正常：

可视化改样式：选中任意文本或元素，用顶部工具栏调字体、字号、颜色、对齐，页面应即时变化。
页面与代码联动：在"Design"里选中一个元素，右侧 Code 面板应定位到它对应的代码行，说明"元素 ↔ 代码"的映射是通的。
AI 生成与编辑：在 Chat 里输入一段描述（或贴图），让 AI 生成或修改页面，检查生成结果是否符合预期，可再连发多条指令排队执行。

三点都能跑通，说明你部署的 Onlook 已经可以正式使用了。

常见卡点排查：Onlook 本地部署遇到问题先看这 4 处

现象	最可能的原因	处理建议
iFrame 里页面不显示、卡在确认页	CodeSandbox 预览需要手动确认	切到 Preview 模式点"Yes, proceed to preview"，再切回 Design
刷新后登录态丢失、频繁掉登录	Node 版本过低	升级到`v20.16.0`或更高，重装依赖并重启，必要时清理浏览器 Cookie
报"Column not found"	数据库结构与代码不同步	先跑`bun db:push`；仍不行再`bun db:reset`（会清空数据，慎用）
容器起不来 / 构建失败	端口占用或镜像缓存问题	释放或修改 3000 端口；执行`docker system prune`后重试

关于 CodeSandbox 预览：它第一次打开会弹出一个"是否继续打开 CodeSandbox 预览"的确认框，这是安全提示，点确认后画面才会正常加载进 iFrame。

进阶玩法与更多参考

跑通基础流程后，可以逐步解锁这些能力，让 Onlook 更像一套完整的工作流：

组件检测与复用：编辑器能识别你代码里的组件，配合 Branching（分支）功能，可以安全地尝试多套设计而不互相污染。
检查点与回滚：开发工具支持保存和恢复检查点，改崩了也能退回。
一键部署与自定义域名：生成的项目可秒级部署、生成可分享链接，甚至绑定自己的域名。
应用市场：可对接第三方应用扩展项目能力。

延伸阅读与源码位置（均为仓库内相对路径，方便深入）：

本地开发：docs/content/docs/developers/running-locally.mdx
自托管总览：docs/content/docs/self-hosting/index.mdx
架构说明：docs/content/docs/developers/architecture.mdx
故障排查：docs/content/docs/developers/troubleshooting.mdx
AI 能力源码：packages/ai/src/
可视化编辑解析逻辑：packages/parser/src/
前后端通信：packages/rpc/src/

Onlook 仍在快速迭代，建议定期拉取更新以获取新功能与修复。遇到仓库内的具体问题，可到官方文档的开发者板块和社区渠道求助，按上面这份"原理 → 方案 → 操作 → 校验"的路径走，你基本就能把这套可视化编辑工具从理解用到落地。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析