Onlook 可视化编辑器部署实战：本地 5 分钟跑通，生产三步上线

Onlook 可视化编辑器部署实战：本地 5 分钟跑通，生产三步上线

【免费下载链接】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 想解决的就是这种来回折腾：它是一个开源的可视化编辑器，你在浏览器里拖元素、调样式，React 代码自动同步生成。这篇文章带你把 Onlook 部署起来——先在本地跑通，再放到服务器上给团队用，最后顺手做点生产加固。

🔧 场景一：本地 5 分钟跑通 Onlook

动手前先用一句话了解它的结构：前端、后端、数据库三块各管各的。前端是 Next.js + TailwindCSS，代码在 apps/web/client/；后端由 Supabase 承担认证、数据库和存储，配置见 apps/backend/supabase/config.toml。

1. 装好前置工具

四样东西装齐就能开工：Git、Docker（含 Docker Compose）、Node.js v18+、Bun 包管理器。

2. 克隆仓库，安装依赖

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

第一条把代码拉下来，第二条进目录，最后用 Bun 一次装齐所有工作区的依赖，不用逐个包手动装。

3. 准备环境变量

cp apps/web/client/.env.example apps/web/client/.env cp apps/backend/.env.example apps/backend/.env

模板里已经列好要填的项，重点是 Supabase 的连接信息和 API Key，逐项抄进新生成的 .env 即可。

4. 启动开发服务器

bun run dev

打开 http://localhost:3000 就能看到编辑器：点一下画布上的元素，对应代码位置立刻高亮；改完代码，预览实时刷新，不用手动刷新页面。

🚀 场景二：用 Docker Compose 把 Onlook 放到服务器

自己玩没问题，给别人用建议容器化。根目录的 docker-compose.yml 只定义了一个 web-client 服务，几个关键设置：对外监听 3000 端口、host 网络模式让容器间通信更简单、unless-stopped 策略保证容器挂了自动拉起。

按顺序敲这三条：

docker compose build # 构建镜像 docker compose up -d # 后台启动 docker compose ps # 确认容器在运行

构建可能要几分钟，等ps里状态变绿再访问 http://服务器IP:3000。上线后顺手验证三件事，确认没装错：

• 在画布上拖一拖元素、改改文字样式，预览应即时生效；
• 让 AI 按一句描述生成组件，AI 相关逻辑都在 packages/ai/，出问题往这个方向查；
• 导出一次项目代码，产出走的是 packages/file-system/ 里的文件规范。

🛡️ 场景三：生产环境三步加固

正式给团队用之前，花十分钟把这三件事做了：

1. 管好密钥：Supabase 的 URL、各类 API Key 只写在服务器上的 .env 里，别提交进仓库；企业级配置建议参考 enterprise.mdx。
2. 上 HTTPS：前面挂一层 Nginx 反代终结 SSL，3000 端口交给代理，不要直接暴露公网；具体步骤见 自托管文档。
3. 核对数据库连接：连接串由 SUPABASE_DATABASE_URL 决定（默认逻辑在 packages/db/drizzle.config.ts），把它指向你自己的 Supabase 或 PostgreSQL 实例。

🩺 出问题怎么办：Onlook 部署常见故障排查

部署卡住别慌，绝大多数是这三类，按顺序排查就行：

• 容器起不来、端口打不开：先docker compose logs -f看实时日志，十有八九是 .env 里 Supabase 相关项没填全。
• 连不上数据库：核对 apps/backend/supabase/config.toml 与 .env 里的连接参数；本地开发时数据库默认在 127.0.0.1:54322。
• 依赖或构建异常：本地环境重新bun install一次；Docker 场景直接bun run docker:restart，它会重建镜像并重启。

📚 想继续深入：二次开发与常用资源

跑起来只是开始。想读懂架构或参与开发，开发者文档 里有完整资料，前后端通信的接口层在 packages/rpc/。平时用git pull更新代码，顺手看看 README.md 的更新说明就能跟上新功能和安全补丁；遇到疑难杂症可以提交 issue，也欢迎按社区流程贡献代码。

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