如何将GrapesJS集成到Ruby on Rails应用中（完整指南2026）

为什么GrapesJS适合Rails

GrapesJS 是一个仅支持浏览器、MIT授权的编辑器，因此Rails负责编辑器页面 并负责加载/存储端点，而 GrapesJS 负责界面。本指南构建 一个工作设置：一个承载编辑器的ERB视图，一个持续存在的控制器 内容包含CSRF保护，以及HTML/CSS导出。

1. 在视图中渲染编辑器

你的轨道布局已经包含 csrf_meta_tags了。创作 app/views/editor/show.html.erb：

<div id="gjs"><h1>Edit me in GrapesJS</h1></div>
<link href="https://unpkg.com/grapesjs/dist/css/grapes.min.css" rel="stylesheet">
<script src="https://unpkg.com/grapesjs"></script>
<%= javascript_include_tag "editor" %>

2. 带远程存储初始化 GrapesJS

// app/javascript/editor.js
const csrf = document
  .querySelector('meta[name="csrf-token"]')
  .getAttribute('content');

const editor = grapesjs.init({
  container: '#gjs',
  height: '100vh',
  fromElement: true,
  storageManager: {
    type: 'remote',
    stepsBeforeSave: 3,
    options: {
      remote: {
        urlStore: '/editor/save',
        urlLoad: '/editor/load',
        headers: { 'X-CSRF-Token': csrf },
      },
    },
  },
});

3. 路由与控制器

# config/routes.rb
get  "editor",      to: "editor#show"
get  "editor/load", to: "editor#load"
post "editor/save", to: "editor#save"

# app/controllers/editor_controller.rb
class EditorController < ApplicationController
  def show; end

  def load
    page = Page.find_or_create_by(key: "home")
    render json: (page.project || {})
  end

  def save
    page = Page.find_or_create_by(key: "home")
    page.update!(
      project: params.permit!.to_h,
      html: params["gjs-html"],
      css: params["gjs-css"]
    )
    render json: { status: "ok" }
  end
end

X-CSRF-Token该头符合 Rails 默认伪造条件 保护，所以你要保持CSRF的状态。作为project jsonb柱子。

4. 渲染导出的页面

<style><%= raw @page.css %></style>
<%= raw @page.html %>

只用于 raw 可信赖的编辑;否则进行净化。

制作技巧

为了稳定的 Rails 配置，把 GrapesJS 项目存成列 jsonb ，这样查询和部分更新就省钱，渲染后的 html/css 也保持独立列，方便快速送达。如果你通过importmap-rails加载GrapesJS，而不是CDN，用它钉顶 bin/importmap pin grapesjs 并确认它在生产环境中能解析，因为资源主机不同。保持Rails X-CSRF-Token 的伪造保护——封头 csrf_meta_tags 能满足它。并且缓存已发布页面（片段缓存或CDN），保存时失效，这样编辑器的渲染成本就不会传达到终端用户手中。

前提条件

你需要Ruby 3.x和Rails 7应用程序。GrapesJS 可以从 CDN 加载 在ERB视图或用importmap-rails钉顶——不需要Rails专属的宝石。 编辑器在浏览器中运行并发布到手柄，所以你对 视图、路线、控制器以及Rails的伪造保护就足够了。

向编辑器添加自定义方块

在以下 grapesjs.init情况下，用块管理器注册可拖拽的块：

editor.BlockManager.add('hero', {
  label: 'Hero section',
  category: 'Sections',
  content: '<section class="hero"><h1>Headline</h1><p>Copy</p></section>',
});

从GJS拉取现成的块库和预设。市场要买更丰富的套装。

存储深度潜入：定制适配器

自定义存储适配器会读取 meta 标签中的 CSRF 令牌，并发布到你的路由：

const csrf = document.querySelector('meta[name="csrf-token"]').content;
editor.Storage.add('rails-store', {
  async load() {
    const res = await fetch('/editor/load');
    return res.ok ? res.json() : {};
  },
  async store(data) {
    await fetch('/editor/save', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrf },
      body: JSON.stringify(data),
    });
  },
});
// then: storageManager: { type: 'rails-store' }

把项目存成一 jsonb 列，这样它就能准确地重新加载到编辑器里。

表演技巧

只在编辑器界面加载 GrapesJS，然后推迟脚本。缓存已发布的 带有 Rails 片段缓存或 CDN 的页面，并在保存时失效。如果你加载 GrapesJS 通过 importmap-rails 确认 pin 在生产中解析，且 资产主机不同。

安全考量

保持伪造保护开启——标题来自 X-CSRF-Token csrf_meta_tags 满足了它。加一个 before_action 那个 在保存前授权当前用户。只用 raw/html_safe 在编辑者被信任时对存储的标记进行分析;否则，输出时要消毒。验证 有效载荷的大小。

排查常见问题

422 不可处理实体 通常意味着 CSRF 令牌缺失 或者说陈旧。 未样式的画布 意味着样式表没有加载。 空白编辑器 意味着容器选择器没有匹配。 413 意味着项目载荷超过了人体限制。

什么时候使用 GrapesJS 搭配 Rails

当你的 Rails 应用需要内置可视化编辑器时，GrapesJS 非常适合你的用户 控制——着陆页、邮件、白标构建工具——由你自己的支持。 数据库。对于内嵌富文本，较轻的所见即所得（WYSIWYG）即可;全页 包含布局、样式和 HTML/CSS 导出的 composition 中，GrapesJS 更为强大， MIT授权的自托管选择。

下一步

参见相关产品 GrapesJS + Laravel 以及 GrapesJS + Django 指南， 浏览 GrapesJS市场，或者从 GJS。市场主页。

常见问题

我该如何将GrapesJS的内容保存到Rails后端？

配置存储管理器，并 type: 'remote' 指向 铁路线路。将元值发送 csrf-token 为 X-CSRF-Token 然后将项目 JSON 存储在模型上。

如何在不繁重构建步骤的情况下加载 GrapesJS？

你可以从CDN中加入ERB视图，或者用importmap-rails钉顶——两种方法都行 因为GrapesJS是纯浏览器JavaScript。

我应该把项目存放在哪里？

使用 jsonb 一栏来展示完整项目，并可选文本栏 用于渲染的HTML和CSS。