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
Onlook 是一款开源的视觉优先代码编辑器，让你在 Next.js + TailwindCSS 项目里用 Figma 式界面直接拖拽、调样式，改动实时同步回代码，还能用 AI 对话生成页面。本文带你走完环境准备、最小化本地部署到 Docker 生产上线的完整流程。
🧩 技术栈速览
| 组件名 | 职责 | 对应路径 |
|---|---|---|
| Next.js + Tailwind | 前端框架与样式 | apps/web/client/ |
| tRPC | 服务端类型安全接口 | packages/rpc/ |
| Supabase | 认证、数据库、存储 | apps/backend/supabase/ |
| Drizzle | ORM 与迁移 | packages/db/ |
| AI SDK + OpenRouter | AI 对话与代码应用 | packages/ai/ |
| CodeSandbox | 开发沙箱容器 | packages/code-provider/ |
| Bun + Docker | 运行时、包管理与容器化 | docker-compose.yml |
📦 前置准备与依赖安装
按清单核对环境，缺失项先补齐：
- 操作系统：Linux / macOS / Windows（WSL2）
- Bun：包管理器兼运行时（推荐 1.3+）
- Node.js：v20.16.0+，避开 v20.11.0
- Git：版本管理
- Docker 20.10+ 与 Docker Compose 2.0+
- 硬件：4+ 核 CPU、8GB+ 内存（建议 16GB）、50GB+ 磁盘
环境就绪后，拉代码装依赖：
git clone https://gitcode.com/GitHub_Trending/on/onlook.git cd onlook bun install # 安装 monorepo 全部依赖🚀 最小化部署路径
三步跑通最小部署，先跑通再深入。
配置环境变量
bun run setup:env # 交互式写入 .env（Supabase/OpenRouter/CodeSandbox 密钥）密钥取自supabase start输出与 OpenRouter、CodeSandbox 控制台；手动填写见 appendix.mdx。
启动服务
bun backend:start # 启动本地 Supabase（DB/认证/存储） bun db:push # 推送数据库 schema bun db:seed # 写入测试用户与项目 bun dev # 启动开发服务器访问验证
curl http://localhost:3000 # 返回 HTML 即主应用就绪服务启动后浏览器打开 http://localhost:3000，Supabase 控制台在 http://localhost:54323。
🐳 容器化生产部署
docker-compose.yml 只编排一个web-client服务：生产级 Next.js 构建，映射3000:3000端口。这里用network_mode: host网络模式，因为容器要直连宿主机上的 Supabase（127.0.0.1:54321），host 模式省去端口转发；restart: unless-stopped保证崩溃后自动拉起。
docker compose build # 构建镜像 docker compose up -d # 后台启动 docker compose ps # 查看运行状态部署完成后访问http://服务器IP:3000验证生产实例。
⚙️ 生产调优三板斧
性能
- 开启 standalone 构建：next.config.ts 设
STANDALONE_BUILD（next.config.ts） - Nginx 反向代理加速缓存，重定向在 vercel.json
- 连接串集中在 drizzle.config.ts 的
SUPABASE_DATABASE_URL
安全
- 密钥只放
.env加密管理，模板见 appendix.mdx - 跨域拦截改 proxy.ts 边缘逻辑
- Nginx 挂 SSL 证书启用 HTTPS
可观测性
- 容器日志跟踪：
docker compose logs -f - 单机用 PM2 守护自动重启（single-machine.mdx）
- 健康检查由 compose 内置，异常看
docker compose ps
🔍 部署验证与排错指南
按序验证核心功能：
- 可视化编辑：拖拽元素调 Tailwind 样式，画布即时刷新
- AI 生成代码：聊天把描述转组件，确认改动落盘
- 项目导出：导出代码，结构符合 fs.ts 规范
- 认证登录：Supabase 邮箱登录/注册正常
- 沙箱预览：新建项目能在 iFrame 中实时运行
高频坑点按「现象 → 排查方向 → 关键文件」定位：
- 端口 3000 被占用 → 停占用服务或改端口 → docker-compose.yml
- 容器连不上 Supabase → 确认
backend:start已运行且 host 模式生效 → config.toml - 镜像构建失败 → 执行
docker system prune清缓存后重试 → Dockerfile
🔧 二次开发指引
扩展入口点到即止，教程展开见文档：
- AI 供应商扩展：在 providers.ts 按现有格式加 provider
- 沙箱提供方：code-provider/
- 插件与 RPC 接口：packages/rpc/src/trpc/
- 完整开发文档：docs/content/docs/developers/
📚 附录：关键路径索引
- 官方文档：docs/content/docs/
- 架构文档：architecture.mdx
- 本地运行：running-locally.mdx
- 故障排查：troubleshooting.mdx
- 自托管总览：index.mdx
- 贡献指南：CONTRIBUTING.md
- API 参考：packages/rpc/src/trpc/
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
