Onlook 部署完整指南：30 分钟把可视化编辑器跑上服务器-迪斯科星球

Onlook 部署完整指南：30 分钟把可视化编辑器跑上服务器

【免费下载链接】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

设计稿还原成前端代码要对齐半天，设计师想改一个像素又得排队提需求。Onlook 解决的就是这个痛点：它是一个开源的可视化编辑器，让你在 Next.js + TailwindCSS 项目里直接拖拽、改样式，编辑实时生成代码。你只需 30 分钟就能完成一次完整的 Onlook 部署，从本地跑通到上线服务器，跟着走就行。

先看清 Onlook 的三层分工

一句话定位：Onlook 是一个面向设计师的 AI 优先开源编辑器，视觉改动与代码双向同步。

前端：Next.js + TailwindCSS 的编辑器应用，源码在 apps/web/client/
沙箱：项目代码跑在 Web 容器里，编辑器通过 iFrame 加载预览，并把 DOM 元素映射回代码位置
数据层：Supabase 提供认证、数据库和存储，配置在 apps/backend/supabase/config.toml

编辑一个元素时，编辑器先改 iFrame 里的页面，再同步改写容器中的代码，AI 对话也共享同一份代码上下文。

30 分钟跑通本地环境

先看环境要求，缺什么装什么：

工具	版本要求	用途
Bun	1.3+	monorepo 管理与脚本运行
Node.js	v20.16.0+（避开 v20.11.0）	本地运行
Docker + Compose	20.10+ / 2.0+	跑 Supabase 后端
Git	任意新版	拉取代码

服务器配置建议 4 核、8GB 内存（16GB 更稳）、50GB 磁盘。

第 1 步，拉代码并装依赖：

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

装完会看到根目录出现node_modules，说明 monorepo 依赖就绪。

第 2 步，启动 Supabase 后端：

bun backend:start

命令输出里会打印anon key和service role key，先复制下来，下一步要用。

第 3 步，交互式配置环境变量（填入 Supabase 密钥、CodeSandbox 令牌、OpenRouter 的 AI 模型密钥）：

bun run setup:env

跑完后 apps/web/client/.env 会自动生成，后面 Docker 部署也复用它。

第 4 步，初始化并填充测试数据：

bun db:push bun db:seed

db:push同步表结构，db:seed写入测试用户和项目。

第 5 步，启动开发服务器：

bun dev

浏览器打开 http://localhost:3000，能看到登录页和项目列表，本地就跑通了。

用 Docker 把它送上服务器

生产部署走单容器方案，编排定义在 docker-compose.yml：web-client服务暴露 3000 端口，host网络模式，失败自动重启。

确认服务器上已有第 3 步生成的apps/web/client/.env，这是容器的全部配置来源
构建并启动：

docker compose build docker compose up -d docker compose ps

ps里容器状态为Up (healthy)即构建内置健康检查已通过。

浏览器访问http://服务器IP:3000验证页面正常
上 HTTPS：在前面挂一层 Nginx 反向代理并配置证书，把 443 转发到 3000，细节可参考 docs/content/docs/self-hosting/
敏感信息只放在.env里，不要写进镜像；密钥定期轮换

跑通后先验这 3 件事

AI 生成页面：新建项目，用文字描述一个落地页，看代码是否实时出现、预览是否同步渲染
可视化改样式：点击任意文本，用工具栏改颜色、字号、布局，改完刷新页面确认代码里真的变了，效果如下：

元素与代码联动：右键页面上任一元素，右侧代码面板会跳到对应 JSX 位置，确认 DOM 到代码的映射正常：

三项都通过，说明沙箱、预览和代码索引链路全部打通。✅

高频坑一次排完

现象	原因	解法
预览卡在加载，不出页面	CodeSandbox 容器在等确认	切到 Preview 模式，点 "Yes, proceed to preview"，再切回来
启动报`Column not found`	数据库与 schema 不同步	先跑`bun db:push`；仍不行再`bun db:reset`（会清空数据）
刷新后频繁掉登录	Node 版本过旧（尤其 v20.11.0）	升到 v20.16.0+，重装依赖并重启，必要时清浏览器 cookies
端口 3000 被占用	其他服务占了端口	停掉占用方，或改 docker-compose.yml 里的端口映射
`docker compose build`失败	磁盘不足或镜像缓存损坏	`docker system prune`后重新构建

预览卡加载时的确认界面长这样：

更多细节见 docs/content/docs/developers/troubleshooting.mdx。

进阶定制：只给你指个入口

换 AI 模型提供商：在 packages/ai/src/chat/providers.ts 按已有格式加 provider，再把对应密钥写进.env
改沙箱注入脚本：预加载脚本源码在 apps/web/preload/script/，改完同步到项目的 public 目录即可生效
扩展接口层：tRPC 路由定义在 packages/rpc/src/trpc/，新增能力从这里入手

收尾：资源与下一步

官方文档：docs/content/docs/，部署细节在 self-hosting 目录
开发指南与架构说明：docs/content/docs/developers/
参与社区：CONTRIBUTING.md，遇到问题可以提 issue 或提交 PR

建议现在就执行第一步：先在本机把bun dev跑起来验证 3 项核心功能，再原样复制到服务器上做一次docker compose up -d，你就有了一个团队共用的可视化开发环境。

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

企业官网建设流程全解析