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认证、存储、ORMAIAI SDK、OpenRouter、Morph / Relace调用大模型、快速落地代码改动沙箱与托管CodeSandbox SDK、Freestyle运行开发容器、对外托管预览运行时Bun、Docker管理这个 Monorepo、跑容器部署前怎么选本地、Docker 还是单机服务器Onlook 的自托管文档给了四条路线本质差别在于你想让多少人用、跑在哪里。先选对路线后面的命令才不会白敲。路线适合谁特点本地开发想体验、想贡献代码的人最快直接在本机跑边开发边改单机standalone5–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.mdxAI 能力源码packages/ai/src/可视化编辑解析逻辑packages/parser/src/前后端通信packages/rpc/src/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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认证、存储、ORMAIAI SDK、OpenRouter、Morph / Relace调用大模型、快速落地代码改动沙箱与托管CodeSandbox SDK、Freestyle运行开发容器、对外托管预览运行时Bun、Docker管理这个 Monorepo、跑容器部署前怎么选本地、Docker 还是单机服务器Onlook 的自托管文档给了四条路线本质差别在于你想让多少人用、跑在哪里。先选对路线后面的命令才不会白敲。路线适合谁特点本地开发想体验、想贡献代码的人最快直接在本机跑边开发边改单机standalone5–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.mdxAI 能力源码packages/ai/src/可视化编辑解析逻辑packages/parser/src/前后端通信packages/rpc/src/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
