onlook 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

onlook 是一个以视觉编辑为中心的开源代码编辑器，面向 Next.js 与 Tailwind CSS 项目提供浏览器内的页面编辑、实时预览、代码查看和人工智能（Artificial Intelligence，AI）交互能力。项目仓库使用 TypeScript 编写，许可证标注为 Apache-2.0，默认分支为 main。

根据提供的 GitHub 仓库元信息，项目有 26762 个 Star 和 2106 个 Fork。README 将它描述为“面向 AI 原生设计师的设计工具”，但仓库中的开源版本重点是 Next.js 加 Tailwind CSS 的视觉优先代码编辑器；README 同时说明，面向 AI 原生设计师的托管产品处于 early access 状态，二者不应混同。

“Craft websites, prototypes, and designs with AI in Next.js + TailwindCSS. Make edits directly in the browser DOM with a visual editor.”
来源：README

定位与目标用户

Onlook 的核心定位是把设计操作放在现有代码库之上，而不是把设计结果导出为与代码脱节的静态产物。使用者可以在浏览器中选择页面元素、查看视觉效果，并通过右键操作定位到代码中的对应位置。

项目当前的技术边界很明确：README 说明其可运行于 Next.js 加 Tailwind CSS 项目，并把非 Next.js 项目和非 Tailwind 项目列为尚未完成的高级项目支持。因而，选型时应先检查现有应用的框架和样式体系，而不是只依据“视觉编辑器”这一产品描述。

主要使用对象

• 使用 Next.js 与 Tailwind CSS 构建网站、原型或产品界面的前端团队。
• 需要在页面视觉调整与源代码修改之间快速切换的设计工程师。
• 希望从文本或图像描述创建 Next.js 应用，并继续在浏览器中调整页面的开发者。
• 需要通过分支、检查点和实时预览实验界面方案的个人开发者或小型团队。

核心功能

核心功能可以分为项目创建、视觉编辑、开发工具、部署和 AI 辅助几个层面。功能清单中的勾选状态来自 README；未勾选项目表示仓库资料明确标注为未完成，不应当当作已经可用的能力。

项目创建：从文本或模板进入编辑流程

README 将“创建 Next.js 应用”列为已完成能力，入口包括从文本或图像开始，以及使用预构建模板。其输出目标是一个可在 Onlook 中继续编辑的 Next.js 项目，而不是只生成一张设计图。

从工作机制看，创建动作需要与项目运行环境和编辑器工作区衔接。资料没有提供文本输入格式、图像提示词格式、模板列表、生成接口签名或所需模型配置，因此这些细节应以最新文档为准，不能根据功能名称推断具体参数。

视觉编辑：在浏览器 DOM 上修改页面

视觉编辑器（Visual Editor）直接面向浏览器文档对象模型（Document Object Model，DOM）中的元素。README 提到 Figma 风格界面、实时预览、品牌资产与设计令牌管理、页面创建与导航、图层浏览、项目图片管理，以及组件检测和使用。

触发方式是用户在编辑器中操作页面元素；对于代码定位，README 明确说明可以随时右键一个元素，打开该元素在代码中的确切位置。输入是当前项目中的页面与 DOM 元素，输出是视觉状态和对应代码位置；具体样式写回规则、冲突处理规则和组件识别算法，官方仓库资料未提供。

页面、图层、资产与组件

页面管理能力用于创建并导航到不同页面，图层浏览则提供页面结构的可视化检查路径。品牌资产、设计令牌和项目图片管理把视觉资源放在项目上下文中处理，但资料未说明资产存储格式、上传大小限制、令牌命名规则或持久化后端。

组件检测和使用已经列为已完成项目，README 还注明该能力此前位于 Onlook Desktop。拖放式组件面板则仍未完成，因此不能把当前组件能力理解为已经提供完整的拖放组件库。

AI 聊天与批量消息

AI 聊天可用于创建或编辑正在处理的项目，README 的使用说明把它描述为项目编辑入口。多个消息排队能力已经勾选，意味着用户可以提交多个待处理请求；但请求的队列顺序、失败重试、并发数、模型选择和响应持久化规则均未在资料中说明。

图像作为参考或项目资产、项目中设置和使用模型上下文协议（Model Context Protocol，MCP）、让 Onlook 自身作为工具调用来创建和迭代分支，均仍处于未完成状态。涉及这些功能的教程不应从当前仓库资料中自行补写。

分支、检查点与代码编辑

分支能力用于尝试不同设计方向，检查点能力用于保存和恢复项目状态，实时代码编辑器则让使用者在视觉界面和源代码之间切换。三者共同构成“实验—查看—恢复”的开发流程，但 README 没有给出分支命名、检查点存储位置、恢复粒度或冲突合并规则。

运行命令的能力通过命令行（Command-Line Interface，CLI）工具提供，另有应用市场连接能力。由于资料没有列出可执行命令白名单、权限模型和应用市场协议，生产环境启用前应先审阅实际文档和源码。

部署与分享

README 将“生成可分享链接”和“关联自定义域名”列为已完成部署能力。部署结果面向应用访问者，而不是只在编辑器内部预览；但托管服务的地域、配额、认证机制、网络模型、日志策略和服务等级协议（Service Level Agreement，SLA）未在资料中提供。

系统架构与关键模块

从仓库结构和构建文件可以确认，Onlook 是一个使用 Bun 工作区（workspace）的 monorepo（单仓库多包）项目，包含 packages/*、apps/*、tooling/*、apps/web/* 和 docs 工作区。资料没有提供完整目录树，因此以下模块关系只描述已被配置文件直接证明的部分。

工作区与应用入口

• apps/web：根脚本通过 @onlook/web 调用客户端构建、开发和启动命令。
• apps/web/client：Dockerfile 在此目录执行 build:standalone，并以 server.js 启动 Next.js 服务。
• apps/backend：根脚本提供后端启动和数据库重置入口。
• packages/db：根脚本提供数据库生成、推送、种子和迁移命令。
• packages/scripts：setup:env 脚本从该目录启动环境设置工具。
• docs：文档是一个 Next.js 应用，包含文档页面、搜索路由和内容源适配器。

客户端容器流程

Dockerfile 使用 oven/bun:1 作为构建基础镜像，把仓库内容复制到 /app，设置生产环境变量后执行 bun install --frozen-lockfile，再在 apps/web/client 中运行 bun run build:standalone。构建产物由 apps/web/client/server.js 启动。

容器声明暴露端口 3000，并通过访问 http://localhost:3000 的健康检查判断服务是否返回成功响应。Docker Compose 将宿主机的 3000 端口映射到容器端口，并为服务配置了 restart: unless-stopped。

文档应用模块

docs/README.md 明确说明文档应用使用 Next.js。lib/source.ts 提供内容源适配器接口，app/layout.config.tsx 保存共享布局选项，app/(home) 负责首页相关路由，app/docs 负责文档布局和页面，app/api/search/route.ts 是搜索路由。

这些路径反映的是文档工作区的已知结构，不等同于整个 monorepo 的完整源码结构。其他包的职责、数据库类型、后端框架和前后端通信协议，官方仓库资料未提供该信息，建议以最新 README 和开发者文档为准。

依赖与运行环境

根目录 package.json 将包管理器固定声明为 bun@1.3.1，项目类型为 ES Module（"type": "module"），并设置了私有 monorepo。构建文件同时表明容器构建基于 oven/bun:1，但该镜像标签的具体 Bun 小版本没有在资料中展开。

应用侧的 README 运行边界是 Next.js 加 Tailwind CSS 项目。根脚本涉及 Next.js 应用、数据库、后端和文档应用，但资料没有列出完整的运行时依赖版本、数据库种类、操作系统支持矩阵或最低硬件要求。

关键运行命令

• bun install --frozen-lockfile：按照锁文件安装依赖，来自 Dockerfile。
• bun --filter @onlook/web dev：启动 Web 开发命令，来自根目录 package.json。
• bun --filter @onlook/web build:client：构建客户端，封装在根目录 build 脚本中。
• bun --filter @onlook/web start:client：启动客户端，封装在根目录 start 脚本中。
• bun --filter @onlook/docs dev：启动文档开发服务。

快速开始

最快的本地验证路径是使用仓库提供的 Docker Compose 配置，因为该配置明确给出了构建步骤、服务端口、环境文件位置和启动方式。若要直接参与源码开发，则应使用 Bun 工作区命令，并先确认本地环境满足仓库文档要求。

方式一：使用 Docker Compose

以下命令来自 Dockerfile 和 docker-compose.yml，适合在本地或测试环境构建 Web 客户端。Compose 配置要求存在 apps/web/client/.env，其中具体变量未在提供资料中列出。

# 进入仓库根目录
bun install --frozen-lockfile

# 构建镜像
docker compose build

# 后台启动服务
docker compose up -d

安装步骤使用仓库指定的 Bun 包管理器和锁文件；镜像构建会再次执行依赖安装，这是 Dockerfile 的既定流程。服务启动后，访问 http://localhost:3000 可检查 Web 客户端是否响应，端口映射来自 Compose 配置。

# 查看服务日志，用于本地验证启动结果
docker compose logs -f

# 停止服务
docker compose down

Dockerfile 内置健康检查，会每 30 秒访问容器内的 http://localhost:3000，超时为 3 秒，启动宽限期为 5 秒，连续 3 次失败后标记异常。这些数值来自 Dockerfile；它们不是对生产可用性或服务等级的承诺。

方式二：直接启动 Web 开发服务

根目录脚本提供 Web 客户端开发入口，命令会通过 Bun 的过滤器定位 @onlook/web 工作区。开发服务器的实际访问端口没有在提供资料中声明，因此应以命令输出或最新文档为准。

# 安装锁定依赖
bun install --frozen-lockfile

# 启动 Web 客户端开发服务
bun --filter @onlook/web dev

如果目标是运行文档应用，可使用 bun --filter @onlook/docs dev。docs/README.md 还展示了在文档工作区中执行 bun run dev、pnpm dev 或 yarn dev 的方式，但根目录项目明确声明的包管理器是 Bun。

配置说明

配置项主要来自根目录 package.json、Dockerfile 和 Docker Compose 文件。下表只列出资料中真实出现的字段或环境变量；“未提供”表示仓库片段没有给出具体默认值，不代表运行时一定不需要该配置。

apps/web/client/.env 的字段名和默认值没有包含在所提供资料中。不要把 <你的-API-KEY> 一类占位符直接写入版本控制，也不要在没有官方配置说明的情况下猜测模型、数据库或第三方服务变量名。

进阶用法

进阶使用的重点是把视觉实验纳入已有开发流程，而不是只把 Onlook 当作独立的页面生成器。项目脚本已经提供代码检查、测试、类型检查、数据库操作、文档开发和 Docker 生命周期命令，可据此组织本地工作流。

质量检查与类型检查

# 运行所有工作区测试
bun --filter '*' test

# 运行所有工作区格式化任务
bun --filter '*' format

# 运行所有工作区代码检查
bun --filter '*' lint

# 对 Web 客户端工作区执行类型检查
bun --filter @onlook/web-client typecheck

这些命令直接来自根目录脚本。测试覆盖范围、代码检查规则、类型检查使用的 TypeScript 配置和失败阈值没有在资料中说明，执行结果应结合具体工作区输出判断。

后端与数据库工作流

# 启动后端
bun --filter @onlook/backend start

# 生成数据库相关内容
bun --filter @onlook/db db:gen

# 推送数据库结构
bun db:push

# 写入种子数据
bun db:seed

# 执行数据库迁移
bun db:migrate

根脚本还提供 bun db:reset，其实际实现会进入 apps/backend 并运行 reset。数据库类型、迁移工具、种子数据内容和数据删除范围均未在材料中说明，因此重置命令只能在明确隔离的开发或测试数据库中使用。

分支与检查点策略

README 已列出分支实验和检查点保存恢复能力。根据本文作者的经验判断，涉及视觉改版时，应把分支当作可回退的实验边界，把检查点当作较小粒度的恢复节点，并在合并前通过实时预览和代码审查核对实际差异。

上述工作方法是流程建议，不是仓库规定。分支是否映射到 Git 分支、检查点是否写入数据库、是否支持多人并行编辑，资料没有给出确切实现，不能据此承诺与 Git 工作流完全等价。

可观测性与运维

仓库明确提供的运行观测手段包括 Docker 健康检查、Compose 日志和服务生命周期命令。它们足以支持本地容器启动验证，但不构成完整的生产监控体系。

健康检查与日志

Dockerfile 使用 Bun 执行网络请求，访问本地 3000 端口并根据响应状态退出。检查周期为 30 秒，超时时间为 3 秒，启动宽限期为 5 秒，重试次数为 3 次；Compose 则通过 docker compose logs -f 提供前台日志跟踪。

资料没有提供指标名称、结构化日志格式、链路追踪、错误上报、告警规则、日志保留周期和备份策略。部署到生产环境时，应为这些空白项建立独立的运维方案，并以实际部署平台的安全要求为准。

容器生命周期

• docker compose build：重新构建 Web 客户端镜像。
• docker compose up -d：后台启动服务。
• docker compose down：停止并移除 Compose 服务。
• docker compose restart：根脚本中的重启逻辑是先执行停止，再执行带构建的启动。

根目录还提供 docker:logs、docker:restart 等脚本封装。容器使用 network_mode: host，并另外声明了名为 supabase_network_onlook-web 的外部网络配置；该网络的创建和成员服务信息不在资料中，因此部署前必须核对目标环境是否具备对应网络。

安全与合规边界

Onlook 涉及项目代码、页面资产、AI 聊天和命令行执行能力，安全重点是代码库、凭据、环境变量和用户内容的授权隔离。本文只讨论在拥有项目权限的本地或测试环境中使用，不提供针对未授权目标的访问、攻击、绕过检测或凭据窃取方法。

• 只导入由团队拥有或明确获准处理的 Next.js 与 Tailwind CSS 项目。
• 不要把 API 密钥、数据库凭据、生产环境变量或个人敏感数据提交到 Git 仓库。
• 执行 CLI 命令、数据库迁移和数据库重置前，应确认当前工作区和数据库属于隔离的开发或测试环境。
• 使用 AI 处理代码、设计资产或用户内容前，应确认组织内部的数据分类、供应商条款和跨境传输要求。
• 部署分享链接和自定义域名时，应明确访问控制、内容所有权和撤销机制；这些机制的具体实现未在资料中提供。

仓库资料没有给出身份认证、权限模型、密钥托管、数据加密、审计日志、数据留存、漏洞响应或合规认证信息。对于受监管数据、未成年人数据、支付数据或生产核心系统，应在隔离环境中完成安全评估后再决定是否采用。

许可证与商用条款

GitHub 仓库元信息和根目录 package.json 均将许可证标记为 Apache-2.0。Apache License 2.0 通常允许在满足许可证条件的前提下使用、修改、复制和分发软件，包括商业使用；分发修改版本时应遵守许可证中的版权声明、许可证文本、NOTICE 文件以及专利相关条款。

本次提供的资料没有包含 LICENSE 文件全文，也没有提供仓库当前 NOTICE 文件内容。因此，是否存在额外的第三方组件义务、特定版权声明或分发说明，必须以仓库中的 LICENSE、NOTICE 和依赖许可证清单为准。商业部署前应保留原始许可证和适用的版权声明，并对修改内容和第三方依赖进行记录。

局限性与已知限制

当前 README 已经把若干能力明确标记为未完成，技术选型的边界也写得比较清楚。下列限制是仓库资料直接说明的项目状态，不是对源码未提供部分的推测。

• 拖放式组件面板尚未完成。
• 团队协作中的评论功能尚未完成。
• 图像作为参考和项目资产的高级 AI 能力尚未完成。
• 项目中的 MCP 设置和使用尚未完成。
• 让 Onlook 自身作为工具调用进行分支创建和迭代尚未完成。
• 非 Next.js 项目支持尚未完成。
• 非 Tailwind 项目支持尚未完成。

此外，托管产品被 README 描述为 early access，仓库开源版本与托管产品的功能边界需要分别核对。官方资料没有给出并发上限、性能基准、数据规模、可用性承诺、模型清单或生产支持范围。

适合谁

以下判断以仓库已声明的框架、功能和运行方式为依据，适用性应通过小规模试用验证。满足多个条件的团队更容易直接利用其现有能力。

• 技术栈匹配：现有项目使用 Next.js 和 Tailwind CSS，并希望在不脱离代码库的情况下做页面调整。
• 工作流需要：设计师和前端开发者需要共享实时预览、DOM 元素和源代码位置，而不是分别维护设计稿与实现稿。
• 实验频率较高：项目经常需要尝试不同界面方案，并且需要分支和检查点帮助恢复实验状态。
• 部署目标清晰：团队能够自行处理环境变量、容器、域名、数据库和访问控制等工程问题。
• 可接受早期能力边界：团队不依赖尚未完成的评论、拖放组件面板、MCP 或非 Next.js 项目支持。

不适合谁

以下信号表明直接采用需要谨慎，或应先选择与现有技术栈和合规要求匹配的替代路径。这里的“不适合”指当前仓库资料不能证明能够满足要求，而不是对未来版本的评价。

• 框架不匹配：核心项目是非 Next.js，或样式体系不是 Tailwind CSS，且无法接受调整技术栈。
• 协作要求未覆盖：团队必须依赖评论、完整组件拖放面板或已经交付的多人协作流程。
• 合规要求严格：组织要求明确的审计日志、数据驻留、SLA、认证体系或供应商合规证明，而仓库资料没有提供这些信息。
• 运行环境受限：团队不能使用 Bun、Docker、Docker Compose，或无法为后端、数据库和环境文件提供隔离环境。
• 不接受 AI 早期能力：项目需要已明确的模型、MCP、图像参考和批量请求协议，而这些细节目前未在资料中完整提供。

README 明确提到的替代方向包括 Bolt.new、Lovable、V0、Replit Agent、Figma Make 和 Webflow。在场景 A，即需要直接编辑 Next.js 加 Tailwind CSS 代码并在浏览器中进行视觉调整时，可评估 Onlook；在场景 B，即需要非 Next.js 或非 Tailwind 项目支持、已完成的评论协作或明确托管服务条款时，应将 README 列出的替代方案纳入独立评估，而不能假设 Onlook 已覆盖这些需求。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分依赖安装、容器启动、环境文件和项目兼容性四类问题。下面的处理步骤只使用仓库资料中出现的命令和路径。

为什么容器启动后无法访问页面

先确认是否执行了 docker compose build 和 docker compose up -d，再使用 docker compose logs -f 查看构建后服务日志。Dockerfile 的服务端口为 3000，Compose 映射为 3000:3000，访问地址应为 http://localhost:3000。

如果容器反复重启，应检查 Dockerfile 中的健康检查结果和服务日志。健康检查只验证本地 HTTP 响应，不会替代应用自身的配置、数据库或外部服务诊断。

为什么环境变量缺失

Compose 为 web-client 服务加载 apps/web/client/.env。提供的资料没有列出该文件的具体字段，因此应从最新官方文档、现有本地配置模板或源码引用处核对变量名，不要凭名称猜测配置。

为什么项目无法导入

首先检查目标项目是否属于 Next.js 加 Tailwind CSS 范围。README 将非 Next.js 和非 Tailwind 项目支持标记为未完成，因此导入失败或编辑能力不完整时，应先确认技术栈，而不是直接修改 Onlook 的环境变量。

如何恢复或清理本地环境

根目录提供 bun clean 对应的 git clean -xdf node_modules，并提供工作区清理脚本。由于清理命令可能删除未跟踪内容，执行前应确认本地没有需要保留的文件；数据库重置命令则只能针对隔离数据库使用。

文档开发服务使用什么入口

根目录脚本提供 bun --filter @onlook/docs dev，docs/README.md 也列出 bun run dev、pnpm dev 和 yarn dev。文档应用的开发端口未在提供资料中明确，启动后应以终端输出为准。

项目地址与资源

以下链接仅列出仓库资料中出现的项目仓库、官网、文档和官方站点，适合继续核对安装、功能状态、开发指南和托管产品信息。

• Onlook GitHub 仓库
• Onlook 官网与托管应用
• Onlook 本地运行文档
• Onlook Early Access 等候名单
• Onlook Desktop 仓库
• Onlook Issues
• Onlook 官方招聘页面