如何用 Vite 设置 GrapesJS（2026 年完整指南）

为什么要用Vite来找GrapesJS

Vite 为 GrapesJS 提供了一个快速的开发服务器和优化的生产包 几乎没有配置。GrapesJS发布ESM构建，Vite负责处理 盒子。本指南安装 GrapesJS，导入 CSS 和核心，并初始化 编辑。

1. 安装

npm create vite@latest my-editor
cd my-editor
npm install grapesjs

2. 初始化在入口文件中

载于 src/main.js：

import grapesjs from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

const editor = grapesjs.init({
  container: '#gjs',
  height: '100vh',
  fromElement: true,
  storageManager: false,
  components: '<h1>Hello from GrapesJS</h1>',
});

export default editor;

将容器 index.html添加到：

<div id="gjs"></div>
<script type="module" src="/src/main.js"></script>

3. 奔跑与建设

npm run dev     # fast HMR dev server
npm run build   # optimized production bundle

如果你看到预打包警告，请把GrapesJS钉入 vite.config.js：

export default {
  optimizeDeps: { include: ['grapesjs'] },
};

4. 添加插件

import grapesjs from 'grapesjs';
import preset from 'grapesjs-preset-webpage';

grapesjs.init({
  container: '#gjs',
  plugins: [preset],
  pluginsOpts: { 'grapesjs-preset-webpage': {} },
});

故障排除

如果编辑器加载时看起来没有样式，那说明你忘了在输入文件里做 import 'grapesjs/dist/css/grapes.min.css' 样式。如果 Vite 在捆绑前记录了依赖警告，请在 中添加 grapesjs optimizeDeps.include vite.config.js。在SSR模式下使用Vite（SvelteKit、Nuxt、Astro）？只在客户端初始化GrapesJS——开发服务器也会在服务器上渲染，编辑器需要DOM。生产时不需要特别的 vite build ：像任何ESM依赖一样，树摇和捆绑GrapesJS。

前提条件

你需要Node.js 18+和一个Vite项目（npm create vite@latest）。 GrapesJS 出厂了一个 ES 模块，所以 Vite 几乎没有配置就能处理—— 本指南涵盖了少数需要轻推的情形。

向编辑器添加自定义方块

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

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

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

在 Vite 上的框架中使用 GrapesJS

如果你的 Vite 应用使用 React 或 Vue，可以把 GrapesJS 挂载成仅客户端的效果，这样它 在任何SSR传递期间都不会运行，容器首先存在：

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

export default function Editor() {
  const ref = useRef(null);
  useEffect(() => {
    let editor;
    import('grapesjs').then(({ default: grapesjs }) => {
      editor = grapesjs.init({ container: ref.current, height: '100vh' });
    });
    return () => editor?.destroy();
  }, []);
  return <div ref={ref} />;
}

表演技巧

动态导入GrapesJS（import('grapesjs')），这样Vite会将其拆分为 它是一个独立的区块，应用的其他部分保持轻量。 vite build 树木摇晃并微型化，无需额外工作量。如果只是你的一部分 应用使用编辑器，加载它在需要它的路由后面。

排查常见问题

编辑器加载时没有样式 说明你忘了 import 'grapesjs/dist/css/grapes.min.css' 在你的日记中。 答 预打包警告 通过添加 grapesjs optimizeDeps.include 在 vite.config.js。 一个SSR “文档未定义” （SvelteKit/Nuxt/Astro 在 Vite 上）意味着你必须 仅在客户端初始化编辑器。

Vite与Webpack for GrapesJS

Vite是配置较低的选择——它负责ESM构建和CSS导入 Box，给你一个快速的开发服务器。仅在已有项目时才使用 Webpack 已经对它进行了标准化;GrapesJS的设置在两者上同样简单。

下一步

参见相关 GrapesJS + Svelte 以及 GrapesJS + React 指南，浏览 GrapesJS 市场，或者从那里开始 GJS。市场主页。

常见问题

我该如何在 Vite 中导入 GrapesJS 样式？

导入 'grapesjs/dist/css/grapes.min.css' 你的入口文件 — Vite 把它注入开发，打包到生产环境。

GrapesJS 需要特殊的 Vite 配置吗？

通常不会。如果遇到预打包问题，可以添加 grapesjs optimizeDeps.include。

我可以用插件配合Vite吗？

是的——通过 npm 安装，导入，然后传入 plugins grapesjs.init。