Puck：把 React 组件变成可拖拽页面的开源可视化编辑器

Puck 是一个模块化、MIT 协议开源的 React.js 可视化编辑器框架。它不是一个开箱即用的 CMS 产品，而是一个嵌进你自己 React 应用里的”编辑内核”：开发者预定义可拖拽的组件与表单字段，编辑者在页面上拖拽、填表单来组装内容，最终产物是一份存在你自己数据库里的 JSON，再由 Puck 的 Render 组件原样渲染。本文基于 Puck 官网文档、GitHub 仓库与 2026 年 7 月 28 日发布的 Puck AI 0.8 说明，对其技术机制、商业化分层与边界做一次客观梳理。

一、背景：为什么需要一个”嵌进自己应用”的编辑器

传统建站工具（Webflow、各类 AI site builder）交付的是”锁在厂商平台里的成品站”，代码与数据都归平台所有；而 Coding Agent（如各类 CLI 编程代理）直接产出原始代码，面向的是开发者，非技术用户无法使用，产出物落在代码仓库里，也不运行在你的应用内部。Puck 官网在对比表中把自己定位在两者之间：让非技术用户也能操作，输出的却是 JSON 而非代码，数据留在你自己的数据库，编辑器直接运行在你的应用之内。

对一个已经用 React（含 Next.js）构建产品的团队来说，典型痛点是：市场或运营想改一个 Landing Page 的文案、换一个区块顺序，都要走开发排期。Puck 的思路是把这套”可编辑能力”作为 SDK 集成进去，而不是把内容搬到另一个平台。

二、是什么：一个 React 组件，两段渲染路径

Puck 的核心包是 @puckeditor/core，对外暴露两个主要组件：

• <Puck>：编辑器 UI。读取开发者提供的 Config，让用户拖拽、配置，交互过程产出一份数据负载（data payload），通过 onPublish 回调交给你的后端保存；
• <Render>：渲染端。接收同一份 Config 和数据负载，把 JSON 还原成真实页面。

这正是 Puck “你拥有数据、无厂商锁定”主张的技术落点：编辑器与渲染器分离，存储格式是普通 JSON，后端由你自己实现。

三、技术机制：Config 与 JSON 数据模型

Puck 的核心行为由一个 Config 对象驱动，它声明三件事：有哪些可用组件、每个组件怎么 render、选中组件时展示哪些配置字段（fields）。一个最小配置形如：

const config = {
  components: {
    HeadingBlock: {
      fields: { title: { type: "text" } },
      defaultProps: { title: "Hello, world" },
      render: ({ title }) => <h1>{title}</h1>,
    },
  },
};

用户把组件拖进预览区并发布后，产出的数据负载结构如下（官方文档原文）：

{
  "content": [
    { "type": "HeadingBlock", "props": { "id": "HeadingBlock-1234", "title": "Hello, world" } }
  ],
  "root": {}
}

content 是组件实例的有序数组，root 承载包裹所有组件的根组件属性。<Render> 拿着这份 JSON 和 Config 就能渲染出页面——渲染路径上没有任何私有运行时依赖。

官方文档列出的核心能力包括：组件配置（render 函数 + 字段映射到 props）、根组件配置、多列嵌套布局（已支持高级 CSS 布局）、侧边栏组件分类、动态 props、动态字段、对接第三方 CMS 的外部数据源、可选的 React Server Components 支持、跨破坏性版本的数据迁移工具、同源 iframe 视口预览，以及通过 Permissions API 开关复制/删除等操作。扩展层还提供自定义字段、字段变换、Plugin API、UI 覆写与主题化。

四、Puck AI 0.8：Assembly 与 Design 双模式

2026 年 7 月 28 日，作者 Fede Bonel Tozzi 发布 Puck AI 0.8，新增”下一代 agent”、Design mode、BYOK 与新定价。AI 层运行在编辑器之上，支持两种生成模式：

• Assembly mode（装配模式）：只能从你 Config 里已注册的组件中挑选、拼装成页；
• Design mode（设计模式）：agent 可临时生成新的组件类型，并在能用已注册组件时优先复用。生成的组件存进页面数据，像普通组件一样拥有可修改字段、支持多列布局，并出现在 Blocks 面板中。

官方称下一代 agent 可分多步完成复杂任务、能”视觉检查自己生成的页面”、理解组件用法，并能访问外部网站收集信息。机制上需要注意几个官方明确写出的约束：

1. Design mode 默认关闭，需在服务端 handler 设置 ai.designMode.allowed = true，并用 withDynamicConfig 包裹 Config；
2. 生成组件存放在数据根节点的 _dynamicConfig 下，官方明确要求”逐字保存返回数据，丢掉 _dynamicConfig 会把设计出的组件从页面剥离”；
3. 客户端脚本默认禁用（scripts: true 才允许），Design 产物默认是静态展示组件；
4. 云端 AI 目前只支持 OpenAI 模型的一个子集，Assembly 与 Design 可分别配模型（文档示例中 Design 默认 openai/gpt-5.6-luna，可换成 openai/gpt-5.6-sol 并调 reasoningEffort）；
5. Headless 场景通过 @puckeditor/cloud-client 的 generate({ prompt, config, mode, pageData }) 程序化生成，官方只说明”执行时间随提示词复杂度变化”，未公布任何时延或成功率数字。

五、关键数据与定价

官网首页公开的规模数字（访问当日口径）：GitHub 13k+ stars、月下载量 2,127,848、MIT 协议。GitHub 仓库页面显示 13.5k stars、约 1.0k forks、87 位贡献者、45 个 release，最新版 v0.23.0，代码以 TypeScript 为主（约 66.8%），当前开放 Issue 174 个、PR 23 个。

Puck Cloud 的四档定价（官方定价页）：

需要注意：开源核心编辑器本身免费 MIT，AI 能力是 Cloud 商业化层；官方博客同时说明，已订阅旧计划的用户可继续用旧 agent，但要获得 0.8 新 agent 等新 AI 功能必须升级到新定价方案。

六、评测口径批判

Puck 官网与发布说明没有提供任何独立基准：没有生成成功率、页面还原度、时延分布，也没有与 Builder.io、Craft.js、GrapesJS 等同类开源编辑器的横向对比数据。首页对比表（Puck vs Coding Agents vs AI Site Builders）是官方自评，维度（使用者、输出物、数据归属、是否运行在应用内）属于产品定位描述，不含量化成绩。AI 生成质量目前只能通过官方在线 Demo 主观体验。此外月下载量为 npm 包口径，不等于生产环境采用数，也无法区分核心编辑器与 AI 插件的下载。

七、优势与局限

优势：

1. 数据主权彻底：产物是普通 JSON，存自己的库，渲染不依赖私有服务，MIT 协议允许商用与二次开发；
2. 与现有 React 技术栈同构：组件就是你已写的 React 组件，字段就是 props，不引入另一套模板语言；
3. 分层清晰：免费开源内核 + 可选 AI Cloud，团队可以先只接编辑器，AI 按需再加；
4. 工程化考虑较全：动态 props/字段、外部数据源、RSC、数据迁移、权限开关、插件与 UI 覆写，覆盖了企业集成常见需求。

局限：

1. 仍是 v0.x（最新 v0.23.0），官方专门提供”跨破坏性版本迁移”工具，侧面说明 API 会有 breaking change，长期升级成本要预留；
2. AI 模型覆盖面窄：Cloud 只支持 OpenAI 模型子集，BYOK 也要付费档才有，暂不支持 Anthropic、Gemini 或自托管模型；
3. Design mode 的治理负担：动态生成组件散落在每页数据的 _dynamicConfig 里，缺少全局组件库沉淀，规模化后样式一致性需要额外约束（官方提供 instructions 注入设计规则，但非强制 schema）；
4. 它是框架不是成品：鉴权、持久化、协作、发布流都要团队自己搭，想要”注册即用的后台”会失望；
5. 无公开量化评测，生成效果与成本需要自行 PoC 验证。

八、适合谁关注

• 已有 React/Next.js 产品、需要让市场或运营自助改页面，又不想迁出代码栈的团队；
• 做白标 SaaS，需要给每个客户一套可编辑界面的产品方；
• 希望用”受约束的组件装配”而非”自由生成代码”来控制 AI 输出的团队。

反之，如果需要成熟的开箱 CMS、可视化建站成品，或要求 AI 支持多模型/自托管，Puck 当前版本都不是最省心的选择。

参考来源

• Puck 官网
• Puck 官方文档 Introduction
• Puck AI 0.8: Next-gen agent, design mode & BYOK（发布博客）
• Puck AI Headless Generation 文档
• Puck Pricing 定价页
• GitHub: puckeditor/puck
• Koala 项目库条目 1413