在 Vanilla JS 项目中安装 CKEditor 5：npm 与 ZIP 完整快速上手指南

在 Vanilla JS 项目中安装 CKEditor 5：npm 与 ZIP 完整快速上手指南

【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5

本指南面向不使用前端框架、以原生 JavaScript（Vanilla JS）构建 Web 应用的前端开发者，介绍在当前 CKEditor 5 开源仓库（包版本 48.5.0）中通过npm或ZIP 压缩包两种方式安装并运行 CKEditor 5 的完整流程。读完本文，你将掌握包安装、模块与 CSS 导入、编辑器创建与配置、以及商业版 premium features 的集成方法，能够在浏览器中快速跑起一个可用的富文本编辑器。

为什么需要两种安装方式？

CKEditor 5 是一个模块化架构的富文本编辑器框架。不同于"下载一个 JS 文件就完事"的传统编辑器，它的源码按包（package）拆分并基于 ES Modules 组织，因此安装方式会直接影响你后续的构建与部署策略：

• npm 方式适合已经（或愿意）引入 JavaScript 打包器的现代前端工程，可以按需引入插件，构建产物更小；
• ZIP 方式适合不想引入打包器、也不依赖 CDN 的部署场景，直接使用官方预构建好的完整 bundle。

两种方式在44.0.0 版本之后都要求配置licenseKey属性才能运行编辑器（详见下文"许可证要求"）。

方式一：通过 npm 安装

前置条件：需要一个打包器

使用 npm 安装时，**必须借助打包器（bundler）**来正确构建 JavaScript 文件。CKEditor 5 兼容目前所有主流现代 JavaScript 打包器；如需快速搭建一个全新项目，官方推荐使用 Vite（在其脚手架指南中可以找到npm create vite一类的初始化命令）。

安装主包

执行下面的命令安装包含全部开源插件的 CKEditor 5 主包：

npm install ckeditor5

在当前仓库中，该包对应 packages/ckeditor5/package.json。从其中可以确认两点关键事实：

1. 该包是一个"type": "module"的 ES Module 包，其入口为src/index.ts，发布产物为dist/ckeditor5.js；
2. 它的 dependencies 以workspace:*的方式聚合了仓库内几乎全部官方开源包，从编辑引擎、六大编辑器类型，到字体、表格、图片、列表、代码块等特性插件。

更具体地说，packages/ckeditor5/src/index.ts 只是把所有这些官方包统一export *出来。所以import { ClassicEditor, ... } from 'ckeditor5'时，你拿到的其实是跨包的聚合出口——这也是为什么"一个包搞定所有开源插件"。

导入模块与样式

安装完成后，即可从ckeditor5包导入所有模块。同时，CSS 样式必须单独导入（JS 与样式分离，便于打包器处理树摇与按需加载）：

import { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } from 'ckeditor5'; import 'ckeditor5/ckeditor5.css';

提示（非英语界面）：导入并注册 UI 翻译仅对美式英语是可选的。如需其他语言界面，请参考 UI 语言设置指南中介绍的翻译导入方式。

许可证要求

从版本 44.0.0 起，licenseKey属性是使用编辑器的必要条件。如果你通过 npm 使用自托管（self-hosted）编辑器：

• 要么必须遵守 GPL 协议，在配置中填'GPL'；
• 要么购买自托管分发许可证。

也可以注册免费试用计划来测试编辑器、评估自托管方案。

关于'GPL'键，许可证与激活指南还补充了一个重要限制：'GPL'键只适用于自托管分发（npm 或 ZIP），云托管 CDN 分发不接受该键，云分发始终要求商业许可证键。此外该指南详细区分了 trial（14 天试用）、development（开发，不消耗 editor loads，但限制本地域名）、production（生产，按用量计费时消耗 loads）与 evaluation 四种许可证键类型，需要正式商用前务必先阅读。

创建一个最小可运行编辑器

创建编辑器的核心模式是：选择编辑器类型 → 配置插件与工具栏 → 调用create()。以最常用的经典编辑器（ClassicEditor）为例：

ClassicEditor .create( { attachTo: document.querySelector( '#editor' ), licenseKey: '<YOUR_LICENSE_KEY>', // 或 'GPL'。 plugins: [ Essentials, Bold, Italic, Font, Paragraph ], toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor' ], root: { placeholder: 'Type here...' } } ) .then( /* ... */ ) .catch( /* ... */ );

配合如下 HTML 挂载点（create()返回 Promise，初始化成功后可在then回调中拿到editor实例，失败时进入catch）：

<div id="editor"> <p>Hello from CKEditor 5!</p> </div>

这就是让一个"骨架级"编辑器在浏览器中运行所需的全部代码。

对上述配置稍作拆解：

• attachTo：指向编辑器挂载的 DOM 元素。注意不同编辑器类型的挂载配置不同——Inline、Balloon、Decoupled 等多使用root.element，而 MultiRoot 编辑器需要roots对象同时声明多个根，详见 编辑器类型指南。原文档特别强调：多根编辑器（multi-root editor）需要更高级的 roots 配置。
• plugins：传入已导入的插件类。其中Essentials是一个"必备功能合集"。从源码 packages/ckeditor5-essentials/src/essentials.ts 可以看到，它聚合了AccessibilityHelp、Clipboard、Enter、SelectAll、ShiftEnter、Typing、Undo七个插件，使编辑器具备与<textarea>类似的基础编辑能力；但它不定义任何块级容器（例如段落Paragraph），因此文档明确提示"如果编辑器需要处理块级内容，务必额外引入Paragraph"——这正是上面示例同时引入Paragraph的原因。
• toolbar：按字符串 ID 列出工具栏按钮，'|'用于插入分隔符。可用的按钮 ID 由已注册插件决定，例如bold/italic来自Bold/Italic，fontSize等来自Font。更全面的配置方法见 配置指南 与 工具栏指南。
• root.placeholder：设置编辑区占位提示文本；与之同族的root.initialData可用来以编程方式指定初始内容（详见下文"下一步"）。

方式二：通过 ZIP 压缩包安装

如果你不想用 npm 构建项目，也无法依赖 CDN 交付，可以下载包含 CKEditor 5 及其全部插件的现成文件。

下载与解压

1. 从官方 CDN 的ckeditor5-{版本号}/zip/路径下载最新 CKEditor 5 分发的 ZIP 压缩包（当前仓库对应版本为 48.5.0，下载地址中的版本号应与你实际使用的版本一致）；
2. 将压缩包解压到项目内的专用目录（例如vendor/），建议在目录名中包含编辑器版本号，这样每次升级新版本时可确保正确的缓存失效策略。

ZIP 包内的文件清单

解压后你会得到以下文件：

ZIP 方式同样受 44.0.0 起的licenseKey要求约束：自托管场景下需遵守 GPL 或购买自托管分发许可证。

运行示例页面

查看编辑器实际效果最快捷的方式，是用 HTTP 服务器来托管index.html。

重要警告：必须在本地服务器环境运行。ZIP 包默认通过 import maps 加载模块；直接用浏览器打开本地 HTML 文件会触发浏览器的安全规则（CORS 策略要求模块必须同源加载）。因此请使用nginx、caddy、http-server等工具将文件以 HTTP/HTTPS 方式提供服务。

安装商业版 premium features

开源版之外，CKEditor 5 还有一系列商业付费特性（premium features），如 Format Painter（格式刷）、协作编辑、导出 PDF/Word 等。它们与开源版一样支持 npm 与 ZIP 两种安装方式。

通过 npm 安装 premium features

所有 premium features 都打包在独立的ckeditor5-premium-features包中，安装方式与开源包一致：

npm install ckeditor5-premium-features

之后从两个包分别导入模块，并分别导入各自的 CSS：

import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Font } from 'ckeditor5'; import { FormatPainter } from 'ckeditor5-premium-features'; import 'ckeditor5/ckeditor5.css'; import 'ckeditor5-premium-features/ckeditor5-premium-features.css'; ClassicEditor .create( { attachTo: document.querySelector( '#editor' ), licenseKey: '<YOUR_LICENSE_KEY>', plugins: [ Essentials, Bold, Italic, Paragraph, Font, FormatPainter ], toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|', 'formatPainter' ], root: { placeholder: 'Type here...' } } ) .then( /* ... */ ) .catch( /* ... */ );

<div id="editor"> <p>Hello from CKEditor 5!</p> </div>

要点与开源版一致：把导入的插件传入create()配置、在toolbar中添加对应的工具栏项。但请注意，使用 premium features 必须用合法的许可证键激活，参见下文"获取 premium features 许可证键"。从 npm 自托管时，同样需要购买 premium features 的许可证。

通过 ZIP 安装 premium features

1. 从官方 CDN 的ckeditor5-premium-features-{版本号}/zip/路径下载包含 premium features 的最新分发压缩包；
2. 解压到项目内专用目录（同样建议目录名带上版本号以利于缓存失效）。

ZIP 包结构如下：

• index.html—— 包含可用编辑器的示例页；
• ckeditor5/目录：
  • ckeditor5.js—— 编辑器 ESM bundle（推荐构建）；
  • ckeditor.js.map—— 上述 bundle 的 source map；
  • ckeditor5.umd.js—— 编辑器 UMD bundle（次要构建）；
  • ckeditor5.umd.js.map—— 上述 UMD bundle 的 source map；
  • *.css—— 编辑器样式表，多数场景用ckeditor5.css（其他文件见 编辑器与内容样式指南）；
  • translations/—— 编辑器 UI 翻译（见 UI 语言设置指南）；
  • ckeditor5-premium-features/子目录：
    • ckeditor5-premium-features.js—— premium features 的 ESM bundle（推荐构建）；
    • ckeditor5-premium-features.umd.js—— premium features 的 UMD bundle（次要构建）；
    • *.css—— premium features 样式表，多数场景用ckeditor5-premium-features.css；
    • translations/—— premium features 的 UI 翻译；
• README.md、LICENSE.md。

与开源版 ZIP 一样，最快捷的验证方式是把index.html通过 HTTP 服务器托管；同样必须遵守 CORS 同源加载规则，不能直接双击打开本地 HTML 文件。

获取 premium features 许可证键

激活 CKEditor 5 premium features 需要商业许可证。最简单的途径是注册 CKEditor Premium Features 的14 天免费试用（无需绑定信用卡）来测试全部付费特性；也可以通过官方销售渠道获取定制方案。拿到激活密钥后，按 许可证与激活指南 将其填入配置的licenseKey字段即可。

下一步：让编辑器真正可用

安装完成、编辑器能渲染之后，通常会继续做三件事：

1. 读写编辑器数据：用editor.getData()获取内容（例如通过 JS 发送到服务器），用editor.setData()替换内容，或用root.initialData配置项以编程方式指定初始数据（它会覆盖 HTML 层提供的内容）。详细示例见 获取与设置数据指南。若编辑器挂载在<textarea>上，Classic editor 在表单提交时会自动把内容同步回该元素，无需额外 JS。
2. 进一步定制编辑器：参考 配置指南 了解全部配置项（如updateSourceElementOnDestroy、自动保存、PendingActions 等生命周期与行为控制）。
3. 按需开启更多特性：浏览 特性索引，挑选图片、表格、列表、协作等能力加入plugins与toolbar。

小结

无论选择 npm 还是 ZIP，CKEditor 5 的接入模式都统一为"选编辑器类型 → 装配插件 → 配置工具栏 →create()"。npm 路径适合已使用打包器的工程并支持按需引入；ZIP 路径则面向免构建、免 CDN 的部署。自 44.0.0 起两者都必须提供licenseKey（GPL 开源使用填'GPL'，商业使用申请对应许可证），premium features 则另需独立的商业激活密钥。结合本仓库中 packages/ckeditor5/src/index.ts 的聚合导出与 packages/ckeditor5-essentials/src/essentials.ts 的插件组合，你可以随时回到源码层面验证每个配置项的真实行为。

【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5