Next.js 页面构建器，基于 GrapesJS

GrapesJS 提供视觉编辑引擎。Next.js 提供围绕其的应用架构。以下是重复阅读的同一份列表：编辑器的组成部分，以及在你采用 GrapesJS 后，谁负责构建每个部分。

• 拖放 — GrapesJS 核心
• 画布 — GrapesJS 核心
• 组件树 — GrapesJS 核心
• 选择与悬停 — GrapesJS 核心
• 区块 — GrapesJS 核心
• 样式 — GrapesJS 核心
• 响应式编辑 — GrapesJS 核心
• 撤销/重做 — GrapesJS 核心
• 资源管理 — GrapesJS 核心
• 序列化 — GrapesJS 核心
• 命令 — GrapesJS 核心
• 插件系统 — GrapesJS 核心
• 存储 — GrapesJS 核心
• 多页项目 — 插件或扩展
• 模板库 — 插件或扩展
• 用户与权限 — 你的Next.js应用
• 发布 — 你的Next.js应用

十七张中有两张是你的。其余的要么随编辑器附带，要么作为插件安装。

React 入门集成：GrapesJS 从一个 React 组件挂载，配有标准的块、图层和样式面板。

GrapesJS 需要一个浏览器。 它测量元素，附加监听器，并在 DOM 初始化时进行变异，所以编辑器属于 Client Component，其设置属于效果。这就是全部约束——其他都是普通的 React。

'use client';

import { useEffect, useRef } from 'react';
import grapesjs, { type Editor } from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

export default function GrapesEditor() {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<Editor | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    // Runs only in the browser: effects never execute during SSR.
    const editor = grapesjs.init({
      container: containerRef.current,
      height: '100vh',
      storageManager: false,
      blockManager: {
        blocks: [
          {
            id: 'section',
            label: 'Section',
            content: '<section class="py-16"><h2>Headline</h2></section>',
          },
          { id: 'text', label: 'Text', content: '<p>Edit me</p>' },
        ],
      },
    });

    editorRef.current = editor;

    // Strict Mode mounts twice in development; without this you get two editors.
    return () => {
      editor.destroy();
      editorRef.current = null;
    };
  }, []);

  return <div ref={containerRef} />;
}

import GrapesEditor from '@/components/GrapesEditor';

// A Server Component. It renders the Client Component; it never touches
// the editor instance, and no 'use client' is needed here.
export default function EditorPage() {
  return <GrapesEditor />;
}

为什么这个例子会这样

那是一个可用的编辑器。本页剩余部分讲述了接下来添加的四个内容：项目存储在哪里，用户可以拖拽什么，发布时会发生什么，以及哪些内容你不必自己编写。

// components/GrapesEditor.tsx
'use client';
// …useRef + useEffect + grapesjs.init()

// app/editor/page.tsx — stays a Server Component
import GrapesEditor from '@/components/GrapesEditor';
export default function Page() {
  return <GrapesEditor />;
}

import dynamic from 'next/dynamic';

// In the Pages Router every page is a client entry point, so ssr: false
// is allowed here — and skips the prerender pass entirely.
const GrapesEditor = dynamic(() => import('@/components/GrapesEditor'), {
  ssr: false,
  loading: () => <p>Loading editor…</p>,
});

export default function EditorPage() {
  return <GrapesEditor />;
}

如果你在迁移，不要携带动态（）包装器。在App Router中，它要么直接在Server Component内部失败，要么重复了'use client'已经完成的工作。

Server Components 才是编辑器周边工作的最佳位置。 它们获取数据，运行服务器端逻辑，并提供应用壳。Client Component 初始化 GrapesJS，拥有其生命周期并处理所有浏览器交互。prop 跨越边界;编辑器实例则从不跨越。

import GrapesEditor from '@/components/GrapesEditor';

export default async function EditorPage({
  params,
}: {
  params: Promise<{ projectId: string }>;
}) {
  const { projectId } = await params;

  // Server side: auth, permissions and data fetching stay here.
  const res = await fetch(`${process.env.API_URL}/projects/${projectId}`, {
    cache: 'no-store',
  });
  const initialProject = await res.json();

  // The Client Component receives plain, serialisable props.
  return <GrapesEditor projectId={projectId} initialProject={initialProject} />;
}

编辑器保留客户端，同时使用 Server Components 来管理周边应用。

是的，但编辑器本身应该在客户端上初始化，因为它依赖浏览器的APIs和DOM。

这个答案的有用版本更具体，因为这两部分的失败方式不同。

这是最需要早期做好、最容易出错的部分。编辑器是一个创作环境。发布页面可以使用你自己的 Next.js 渲染架构——静态生成、流式传输、重新验证、边缘缓存，所有这些。

// The public route. GrapesJS is not imported here, so the editor
// bundle never reaches a visitor.
export const revalidate = 3600;

export default async function PublishedPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const res = await fetch(`${process.env.API_URL}/published/${slug}`, {
    next: { revalidate: 3600 },
  });

  // Already sanitised on the way in — see the publish route below.
  const { html, css } = await res.json();

  return (
    <>
      <style dangerouslySetInnerHTML={{ __html: css }} />
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </>
  );
}

GrapesJS 提供本地和远程存储适配器，并允许你注册自己的适配器。定制适配器通常是正确的选择，因为它会把所有读写都放在你控制且可认证的路由后面。

const editor = grapesjs.init({
  container: containerRef.current,
  storageManager: {
    type: 'nextjs-api',
    autosave: true,
    stepsBeforeSave: 5,
  },
  plugins: [
    // Registered as a plugin so the adapter exists before the first load.
    (editor) => {
      editor.Storage.add('nextjs-api', {
        async load() {
          const res = await fetch(`/api/projects/${projectId}`);
          return res.ok ? res.json() : {};
        },
        async store(project) {
          await fetch(`/api/projects/${projectId}`, {
            method: 'PUT',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(project),
          });
        },
      });
    },
  ],
});

import { NextResponse } from 'next/server';

// Your own persistence layer — Postgres, MySQL, Mongo, S3, a headless CMS.
// GrapesJS never talks to it; it only ever talks to this route.
import { loadProject, saveProject } from '@/lib/projects';
import { requireProjectAccess } from '@/lib/auth';

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ projectId: string }> },
) {
  const { projectId } = await params;
  await requireProjectAccess(projectId);

  return NextResponse.json(await loadProject(projectId));
}

export async function PUT(
  request: Request,
  { params }: { params: Promise<{ projectId: string }> },
) {
  const { projectId } = await params;
  await requireProjectAccess(projectId);

  const project = await request.json();
  if (typeof project !== 'object' || project === null) {
    return NextResponse.json({ error: 'Invalid project' }, { status: 400 });
  }

  await saveProject(projectId, project);
  return NextResponse.json({ ok: true });
}

• 加载：适配器的load()在初始状态下运行，恢复用户最后处理的项目。
• 保存：store() 以 JSON 的身份接收整个项目。返回被拒绝的承诺，以在编辑器中发现失败。
• 自动保存：用stepsBeforeSave自动保存批量修改，这样你就不会每次按键都写入。
• 草稿：将草稿项目和发布的成果分列，避免编辑改变访客看到的内容。
• 版本管理：项目数据是 JSON 文档——仅附录版本表只需一次插入，并购买回滚费用。
• 发布：一个独立的端点，有自己的权限检查，而不是在保存路径上设置标志。

示例：使用 Supabase 存储项目

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!, // server only — never NEXT_PUBLIC_
);

export async function loadProject(projectId: string) {
  const { data } = await supabase
    .from('projects')
    .select('project')
    .eq('id', projectId)
    .single();

  return data?.project ?? {};
}

export async function saveProject(projectId: string, project: unknown) {
  await supabase
    .from('projects')
    .upsert({ id: projectId, project, updated_at: new Date().toISOString() });
}

这实现了 loadProject 和 saveProject 边界，路径上方导入。将主体替换为 Prisma、Drizzle、Mongo、DynamoDB 或对现有后端的 REST 调用，页面上的其他内容不变。

示例：将项目存储连接到 Vercel/Next.js 部署

发布写入HTML，CSS则读取你的公用路由。重新验证、缓存和渲染策略仍是Next.js的常规关注点——编辑器不在请求路径中。

你可以把GrapesJS连接到任何后端或数据库。编辑器里根本不知道你选了哪个。

开箱即用，画布为用户提供了通用的HTML。自定义组件类型是编辑器开始生成产品标记的方式——也就是你Next.js应用已经渲染的部分，只包含你决定暴露的属性。

// Your design system, expressed as something users can drop in,
// edit and style — but not break.
editor.Components.addType('pricing-table', {
  isComponent: (el) =>
    el.tagName === 'SECTION' && el.classList.contains('pricing'),

  model: {
    defaults: {
      tagName: 'section',
      classes: ['pricing'],
      // Structure the user cannot accidentally dismantle.
      droppable: false,
      // Fields exposed in the Settings panel.
      traits: [
        { name: 'plan', label: 'Plan name', type: 'text' },
        { name: 'price', label: 'Price', type: 'text' },
        { name: 'billing', label: 'Billing period', type: 'select',
          options: [
            { id: 'month', label: 'Monthly' },
            { id: 'year', label: 'Yearly' },
          ] },
      ],
      components: [
        { type: 'text', tagName: 'h3', content: 'Starter' },
        { type: 'text', tagName: 'p', content: '$19 / month' },
        { type: 'link', content: 'Choose plan', attributes: { href: '#' } },
      ],
    },
  },
});

构建一个模块库

块是用户拖拽时出现在面板上的。一旦组件类型存在，注册块只需几行。

// A block is what the user drags. A component is what it becomes.
editor.Blocks.add('pricing-table', {
  label: 'Pricing table',
  category: 'Marketing',
  media: '<svg viewBox="0 0 24 24" width="24" height="24">' +
    '<rect x="3" y="4" width="18" height="16" rx="2" fill="currentColor"/></svg>',
  content: { type: 'pricing-table' },
});

• 可复用区块 —— Hero、功能区、客户评价、页脚
• 营销块——定价表、标志墙、行动号召
• 布局块——列、间隔、容器
• 表格——联系、注册、多步骤
• 电商区块——产品网格、购物车摘要、结账提示
• 应用块——无论你的产品做什么，页面应该能显示出来

管理图片和资源

Asset Manager负责选择和插入。文件存放在哪里、谁可以上传以及允许通过什么，都是你合同上的规定。

assetManager: {
  // The library the user already has, loaded from your backend.
  assets: initialAssets,

  uploadFile: async (event) => {
    const files = event.dataTransfer
      ? event.dataTransfer.files
      : (event.target as HTMLInputElement).files;
    if (!files) return;

    const body = new FormData();
    Array.from(files).forEach((file) => body.append('files', file));

    // Your route authenticates the user and validates type and size
    // before anything is written to storage.
    const res = await fetch('/api/assets', { method: 'POST', body });
    const { urls } = await res.json();

    editor.AssetManager.add(urls);
  },
},

• 通过你自己的路由处理程序上传，这样会话 cookie、速率限制和审计日志都能生效。
• 允许已经托管图片的团队使用外部网址。
• 预加载用户现有库，这样拣选器会在他们的资产上打开，而不是在空面板上。
• 验证服务器上的MIME类型和大小。编辑器的文件输入是建议，不是控制。
• 从CDN服务器提供，并将CDN URL存储在项目中，这样发布的页面就不会到达你的媒体来源。
• 分页大库——资产面板会很乐意渲染一万个缩略图。

编辑器生成两种不同的内容，且它们不能互换。存储错误的代码是将“编辑您的页面”变成“重新开始”的错误。

// Project data — the editable source. This is what you store.
const project = editor.getProjectData();

// HTML and CSS — the rendered output. Generate this when you publish.
const html = editor.getHtml();
const css = editor.getCss();

// Reopening an editing session needs the project data, not the HTML:
editor.loadProjectData(project);

存储项目数据以便编辑。需要发布或渲染内容时生成HTML/CSS。

GrapesJS 提供编辑器引擎。插件增加了特定产品所需的专用功能——而页面构建器在第一周后仍然缺乏的大部分功能已经存在。

• 区块现成的拖拽面板部分和布局原件。
• 模板完整的起始预设——一个能在某个平台上打开的编辑器，而不是空白画布。
• 存储持久化适配器、自动保存和崩溃恢复。
• 资源上传小工具、媒体库和CDN集成。
• 页面多页项目、页面树和内部链接。
• 导出ZIP 导出、HTML/CSS 转换器和部署钩子。
• 电子邮件MJML 和新闻通讯预设，用于同一画布上的邮件输出。
• 表单表单组件、输入和第三方嵌入。
• 人工智能文稿生成、图片生成和辅助编辑。
• UI样式管理器扩展、尺、调色板和编辑器 Chrome。

GJS.Market目录中的实时列表，按Next.js团队在编辑器安装后提出的问题分组。

React 与 Next.js 集成

为从React组件安装GrapesJS的队伍提供起始和UI层。

浏览类别

GrapesJS React Demo — Starter Integration for React Developers

一个可以正常工作的React集成，写自己的之前可以先读一读。

免费景观

GrapesJS Shadcn

完整的编辑器外壳重新设计为现代React设计系统。

¥7,199.93景观

存储与恢复

从“用户编辑了某件事”到“明天它还在”之间的各种情况。

浏览类别

Autosave & Restore — Crash Recovery for GrapesJS

关闭标签页或失去连接后恢复会话。

¥86.40景观

IndexedDB Storage

支持离线的本地持久化，作为API前方的草图层非常有用。

免费景观

区块、页面与模板

用户拖拽了哪些页面，页面在哪里，编辑器打开了什么。

浏览类别

Pages Manager

多页项目，编辑器中带有页面树。

¥180.00景观

Templates Manager

用户可以从模板库开始，你可以进行策划。

¥280.80景观

Plugin Blocky for Tailwind CSS

Tailwind原生模块，适合已经在用Tailwind造型的团队。

¥424.80景观

资源、导出与邮件

媒体处理以及页面构建器发展的输出格式。

浏览类别

Grapesjs Cloudinary

Cloudinary 作为资产后端，包含了变换。

免费景观

Grapesjs Uppy

一个生产级上传小部件，通过线连接到Asset Manager。

免费景观

Export Zip

下载项目为即部署的 HTML 和 CSS 捆绑包。

免费景观

MJML Preset

把同一个画布变成响应式邮件输出。

免费景观

编辑器用GrapesJS核心，只添加产品真正需要的功能。

根据能力逐一说明你要写的内容。“可扩展”意味着库提供接口和默认值，并期望你指向自己的后端。

已在2026-09-02上与已发布的GrapesJS API进行验证。

这两份清单值得在第一个真正用户打开编辑器之前阅读，而不是之后。

几乎所有报告的该栈集成失败都属于以下七种。

• ✕错误

  在Server Component内部初始化GrapesJS

  Server Components 没有钩子、没有效果，也没有 DOM。导入可能会解决，但编辑器没有地方可以挂载。

  ✓修复

  用Client Component——把'use client'放在拥有编辑器的模块顶部。

• ✕错误

  在DOM存在之前初始化

  在渲染时调用init()，或者对仍为空的引用调用失败，因为容器元素尚未被创建。

  ✓修复

  安装后初始化，在useEffect内部，并在ref出现时进行守卫。

• ✕错误

  在SSR期间运行GrapesJS

  任何访问 init() 的调用都会抛出 ReferenceError： 文档未定义。仅导入本身无害。

  ✓修复

  编辑器初始化保持在客户端。一个效果就足够了;动态导入是优化，不是修复。

• ✕错误

  将编辑器实例置于React状态

  编辑器是一个大且可变的对象，不断变化。将其存储在状态中，调度会重新渲染，但这些都没有任何效果。

  ✓修复

  使用参考文献。保留UI实际渲染的内容状态，比如保存指示器。

• ✕错误

  不必要的重新渲染编辑器

  如果是父重渲染，重建道具或重新安装容器，则会拆除并重建整个画布。

  ✓修复

  保持GrapesJS生命周期与正常的React渲染分开——先挂载一次，然后通过自己的API驱动。

• ✕错误

  仅存储HTML

  HTML 是输出，不是源。从 HTML 重新打开项目会丢失组件类型、traits 和编辑器状态，所以下一次编辑从扁平化的页面开始。

  ✓修复

  如果用户需要继续编辑，请持久化项目数据。发布时生成 HTML。

• ✕错误

  在每个公共页面上运行GrapesJS

  将编辑器运行时发给无法编辑内容的访客，需要支付捆绑包尺寸、内存和Core Web Vitals费用，且无回报。

  ✓修复

  将编辑器运行时间与已发布内容分离——将已发布页面渲染为纯 HTML 和 CSS。

三个示波器，每个相辅相成。大多数队伍在第一个导向镜上会超标，第三个则会被惊讶。

1. 1第一周

   MVP

   在围绕它做任何东西之前，先证明编辑体验是正确的。

   • GrapesJS 安装在客户端组件中
   • 几个基础方块
   • 本地或单项目存储
   • 简单发布到一条路由
   从这里开始
2. 2首批真正用户

   生产环境

   所有让演示变成客户可以依赖的东西的一切。

   • 每个编辑器路由的认证
   • 后端存储放在你自己的API后面
   • 资源上传与媒体库
   • 与你的设计系统匹配的定制组件
   • 服务器端强制执行的权限
   • 版本管理与发布工作流程
   详见存储部分
3. 3商业

   SaaS

   就是围绕编辑器的产品层，这才是你实际收费的部分。

   • 组织与团队
   • 计费和套餐限额
   • 白标编辑器 UI
   • 为用户精心策划的插件集
   • 模板库
   • 已发布页面的分析
   SaaS 页面构建器

从原型到商业产品的路径是通过你的应用程序，而不是编辑器。