零到部署：Onlook可视化编辑器的全流程落地指南

Onlook作为开源的视觉优先代码编辑器，让设计师和开发者能够直接在React应用中进行可视化编辑并实时生成代码。本文将从环境准备到生产部署，完整呈现Onlook的本地化部署实践，帮助团队快速搭建可视化开发环境。

部署架构概览

Onlook采用前后端分离架构，核心由Web客户端、后端服务和数据库组成。其工作流程基于Web容器运行代码，通过iFrame预览并映射DOM元素到代码位置，实现可视化编辑与代码同步。

核心组件包括：

• 前端：Next.js + TailwindCSS，源码位于apps/web/client/
• 后端：Supabase提供认证、数据库和存储服务，配置文件见apps/backend/supabase/config.toml
• 容器化：通过docker-compose.yml实现服务编排

本地开发环境搭建

环境准备

确保系统已安装：

• Git
• Docker及Docker Compose
• Node.js (v18+)
• Bun包管理器

代码获取与依赖安装

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/on/onlook.git
cd onlook

# 安装依赖
bun install

配置环境变量

复制并修改环境变量模板：

# 前端环境变量
cp apps/web/client/.env.example apps/web/client/.env

# 后端环境变量
cp apps/backend/.env.example apps/backend/.env

编辑.env文件配置必要参数，包括Supabase连接信息和API密钥，详细参数说明见docs/content/docs/self-hosting/。

启动开发服务器

# 启动所有服务
bun run dev

# 或使用Docker Compose
docker-compose up -d

服务启动后访问http://localhost:3000即可打开Onlook编辑器界面，编辑区域与代码实时同步，效果如下：

Docker部署流程

容器化配置解析

项目根目录的docker-compose.yml定义了主要服务组件：

• web-client：前端应用容器，暴露3000端口
• 使用host网络模式确保容器间通信
• 自动重启策略保障服务稳定性

构建与启动容器

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看运行状态
docker-compose ps

成功部署后，可通过http://服务器IP:3000访问应用。系统会自动应用apps/web/client/next.config.ts中的配置，包括路由规则和构建优化。

生产环境配置

性能优化

1. 启用静态资源缓存：修改apps/web/client/next.config.ts配置缓存策略
2. 配置CDN加速：在apps/web/client/vercel.json中设置国内CDN地址
3. 优化数据库连接：调整packages/db/drizzle.config.ts中的连接池参数

安全加固

1. 设置环境变量：在生产环境中使用加密方式管理敏感信息，参考docs/content/docs/enterprise.mdx
2. 配置CORS策略：编辑apps/web/server/src/middleware.ts限制跨域请求
3. 启用HTTPS：通过反向代理（如Nginx）配置SSL证书，示例配置见docs/content/docs/self-hosting/

功能验证与故障排查

核心功能测试

部署完成后验证关键功能：

1. 可视化编辑：拖拽元素并确认assets/text-styling.png所示样式调整功能正常
2. AI生成代码：测试文本转组件功能，检查packages/ai/src/相关模块日志
3. 项目导出：验证代码导出功能，生成的文件应符合packages/file-system/src/fs.ts中的规范

常见问题解决

1. 服务启动失败：检查apps/web/server/package.json中的依赖是否完整
2. 数据库连接错误：确认apps/backend/supabase/config.toml中的连接参数正确
3. 静态资源加载异常：验证apps/web/client/public/目录权限及文件完整性

扩展与定制

插件开发

Onlook支持通过插件扩展功能，开发指南见docs/content/docs/developers/，核心插件接口定义在packages/rpc/src/index.ts。

自定义模板

创建项目模板并放置于packages/templates/目录，可通过编辑器的"新建项目"功能选择使用，模板配置规范参考packages/constants/src/templates.ts。

总结与资源

通过本文档，你已掌握Onlook从本地开发到生产部署的全流程。更多资源：

• 官方文档：docs/content/docs/
• API参考：packages/rpc/src/trpc/
• 社区支持：CONTRIBUTING.md

Onlook持续迭代中，建议定期通过git pull更新代码，并关注README.md中的更新日志，及时获取新功能和安全补丁。

部署过程中遇到问题可提交issue至项目仓库，或通过社区渠道寻求帮助。合理配置的Onlook环境将为团队带来高效的可视化开发体验，加速前端项目从设计到代码的转化流程。