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你只需把仓库跑起来Onlook 就能让设计师和开发者在同一个 React 项目里做可视化编辑改动实时回写成代码。本文按环境准备 → 本地启动 → Docker 部署 → 生产配置的路径梳理 Onlook 自托管的完整流程和排障要点照着做即可落地。一、 适合谁用一句话你希望改页面不用来回切 IDE 和浏览器Onlook 就是为此而生的。设计师直接在画布上拖拽、改样式不用等开发排期。前端开发者可视化操作直接落到 React 源码省掉大量手动调样式的时间。小型团队自托管一份私有实例代码和数据留在自己手里。如果你日常要交付落地页、营销页、中小规模 Web 应用这套部署流程值得花一小时跑通。二、 动手前准备先确认机器上有这四项工具缺哪个补哪个工具用途版本要求Git拉取仓库任意近一年版本即可Docker Compose跑后端 Supabase 和容器化部署Docker Compose v2Node.js本地运行 Next.js 客户端v18官方文档推荐 v20.16.0Bun包管理器与 monorepo 脚本执行稳定版装完用下面三条命令自检输出无报错即可开干docker compose version node -v bun -v如果bun -v报 command not found先装 Bun 再继续后面所有脚本都依赖它。三、 看懂它怎么跑组件与数据流打开仓库你会发现 Onlook 分成三块Next.js 前端客户端、负责跑代码的后端服务、以及承担数据职责的 Supabase。核心工作方式是一条闭环你的项目代码被放进 Web 沙箱容器里运行容器内的页面通过 iFrame 加载出来供预览iFrame 里的每个 DOM 元素与源码中的代码位置建立映射你在画布上的每一次拖拽、改色都会顺着这条映射写回源码。各组件分工如下组件职责路径Web 客户端Next.js TailwindCSS 构建的编辑器 UI内嵌预览 iframeapps/web/client/后端服务启动沙箱容器、管理代码文件与预览apps/web/server/Supabase认证Auth、PostgreSQL 数据库、文件存储apps/backend/supabase/Docker Compose单容器编排构建、端口映射、自动重启docker-compose.yml记住这条容器运行 → iframe 预览 → DOM 映射 → 代码回写的链路后面排障时基本都能对上号。四、 本地跑起来从克隆到打开编辑器第一步克隆仓库并装依赖git clone https://gitcode.com/GitHub_Trending/on/onlook cd onlook bun install第二步复制环境变量模板。前端和后端各一份cp apps/web/client/.env.example apps/web/client/.env cp apps/backend/.env.example apps/backend/.env然后编辑这两个文件重点填两类值Supabase 的连接信息与密钥本地启动后端后anon key 和 service role key 会打印在终端里以及 AI 功能需要的模型 API 密钥。每个参数怎么取docs/content/docs/self-hosting/ 里逐条写了。第三步启动。两种姿势任选bun run dev # 或直接容器化启动 docker-compose up -d等日志出现就绪提示浏览器打开 http://localhost:3000 就能看到编辑器。新建项目后你会看到画布、图层、代码三栏并存点画布上的元素代码面板同步高亮到对应 JSX 行。五、 用 Docker 发布构建、启动与外网访问本地验证通过后发布到服务器走容器路线。Compose 里定义了一个web-client服务构建根目录的Dockerfile、映射3000:3000端口、network_mode: host便于访问宿主机上的 Supabase、restart: unless-stopped保证进程挂了能自动拉起。服务器上依次执行docker-compose build docker-compose up -d docker-compose psps输出里状态显示Up即构建启动成功。外网访问只需两步把访问地址写成http://服务器IP:3000再去云厂商安全组放行 3000 端口。构建失败时先docker compose logs web-client看报错再执行docker system prune清掉残留缓存重试这是最常见的两种情况。六、✅ 上线清单性能优化与安全加固生产环境别裸奔下面这份清单按先性能后安全的顺序过一遍类别动作落点性能为静态资源开启缓存策略减少重复请求apps/web/client/next.config.ts性能配置 CDN 加速把静态资源推给边缘节点apps/web/client/vercel.json性能调整数据库连接池大小匹配团队并发规模packages/db/drizzle.config.ts安全密钥类变量走加密管理不写死在代码和镜像里参见 docs/content/docs/enterprise.mdx安全收紧 CORS 白名单只放行自己域名的跨域请求apps/web/client/src/proxy.ts安全Nginx 反向代理 SSL 证书全站切 HTTPS自托管文档中有示例配置优先级排序的话HTTPS 和密钥管理是底线连接池和缓存按团队规模慢慢调。七、 验证与排障跑通三个核心功能 高频问题速查部署完先验功能按顺序跑这三项可视化编辑在画布上拖拽一个 div、改一段文字颜色确认代码面板同步变化样式面板的行为符合预期参考 assets/text-styling.png 对应的能力面。AI 生成代码向对话窗口发一句生成一个登录卡片观察 packages/ai/ 相关日志确认流式输出和代码落盘正常。项目导出导出项目文件检查产物结构是否完整、文件命名是否符合 packages/file-system/ 中的组织规范。功能跑不平时查这张高频问题速查表症状可能原因先查哪里服务启动失败依赖不完整或版本冲突apps/web/server/package.json 与终端报错数据库连不上Supabase 连接参数写错apps/backend/supabase/config.toml 及.env静态资源 404目录权限或文件缺失apps/web/client/public/ 下的文件是否齐全九成问题出在环境变量优先重查.env其次才是代码。八、 继续玩插件与模板扩展跑通主线之后两处扩展点值得了解插件开发编辑器的扩展接口定义在 packages/rpc/ 里想加自定义工具或面板从这里入手背景知识看 docs/content/docs/developers/。自定义模板在packages/templates/目录放置你的项目模板之后用新建项目功能即可一键选用团队里沉淀的组件库可以这样分发。这两块决定了 Onlook 是一个工具还是团队的基座值得留些时间试。九、 收尾资源索引与维护建议常用入口汇总收藏即可官方文档docs/content/docs/含自托管、开发者、排障全部分支API 参考packages/rpc/src/trpc/前后端 tRPC 接口都在这里贡献指南CONTRIBUTING.md提 PR 前必读项目说明README.md维护上的建议只有一条但很重要Onlook 迭代很快定期执行git pull跟进上游更新每次升级后重跑一遍第七节的三个功能验证确保新功能和安全补丁都真实生效。把上面九节按顺序走完你就有了一份随时可复用的 Onlook 部署手册——给团队做 onboarding 时直接递过去就行。【免费下载链接】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），仅供参考