CKEditor 5 包生成器构建产物全解析npm、ZIP 与 CDN 三种集成路径实战指南【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5ckeditor5-package-generatorCKEditor 5 包生成器脚手架出来的自定义插件包执行npm run build后会在dist/下产出两套风味各异的构建结果一套面向 npm 安装一套面向浏览器直接加载。本指南以packageName示例为ckeditor5-callout为占位符系统讲解这些产物各自的作用、TypeScript 类型增强方式以及如何把它们接入 npm、ZIP 或 CDN 三种主流 CKEditor 5 发行渠道。读完本文你将能独立判断自己的项目该选用dist/下的哪个文件并完成可运行、可发布的插件集成。使用包生成器创建插件包、理解模板结构与日常开发命令可先阅读 Create a CKEditor 5 package with package generator。构建产物的基本定位运行npm run build会创建dist/目录其中包含两种构建产物一种用于 npm 安装一种用于浏览器直接加载。同一份生成出来的包可以配合标准的 CKEditor 5 npm、ZIP 或 CDN 发行版一起使用。需要特别强调的是生成的包是附加组件add-on而不是完整的编辑器构建。它不会打包ckeditor5不会创建 ZIP 压缩包也不会向 CKEditor Cloud CDN 发布任何内容。你必须始终把它与一个常规的 CKEditor 5 安装配合使用。本文统一使用packageName作为 npm 包名占位符Callout与CKCallout分别是ckeditor5-callout的示例插件类名与 UMD 全局名。你实际的包名、插件名和全局名取决于生成过程中填写的值。生成的项目结构生成出来的包结构小而可预期各路径职责如下路径用途src/插件源码文件与包入口点。sample/由npm run start加载的本地示例应用。tests/由 Vitest 运行的单元测试。theme/插件使用的图标与 CSS。lang/contexts.json用于同步的翻译上下文描述。scripts/辅助脚本包括翻译同步。dist/npm run build创建的产物。ckeditor5-metadata.json供 CKEditor 5 工具链使用的插件元数据。vite.config.[js\|ts]构建与测试配置。src/augmentation.ts、typings/、tsconfig*.jsonTypeScript 专属的类型支持文件。其中ckeditor5-metadata.json的格式可以在仓库内现成插件包中直接看到例如 ckeditor5-alignment 的元数据文件 就声明了插件名称、类名、源码路径、UI 组件以及htmlOutput等内容供 CKEditor 5 的相关工具读取。TypeScript 类型增强augmentation如果选择 TypeScript 模板生成器会创建src/augmentation.ts文件。这是生成包对 CKEditor 5 类型如PluginsMap进行增强augment的地方。当你新增插件或命令时需要同步更新这个文件。根据插件功能的不同通常会增强以下一个或多个接口EditorConfig定义于 editorconfig.ts当你的插件新增配置项时增强。PluginsMap定义于 plugincollection.ts当你希望editor.plugins.get()返回插件自身的类型时增强。CommandsMap定义于 commandcollection.ts当你新增命令并希望editor.commands.get()返回带类型的查询结果时增强。生成的模板已经在src/index.ts中导入了./augmentation.js注意保留.js扩展名这是生成模板有意为之的约定可保证产出的 ESM 文件合法。典型写法如下import type { Callout } from ./index.js; declare module ckeditor/ckeditor5-core { interface PluginsMap { [ Callout.pluginName ]: Callout; } }这种模块增强的写法在 CKEditor 5 自身的源码中同样被大量使用例如 ckeditor5-core 的 augmentation.ts 就是通过declare module向编辑器相关类型注入PluginsMap等接口的。仓库内packages/下的ckeditor5-core、ckeditor5-engine等包也都各自维护着augmentation文件这正是 CKEditor 5 类型生态的标准做法。dist/里都有什么执行npm run build之后输出结构大致如下dist/ ├─ index.js ├─ index.css ├─ index.d.ts # TypeScript only ├─ callout.d.ts # TypeScript only ├─ augmentation.d.ts # TypeScript only, if present ├─ translations/ │ ├─ language.d.ts │ ├─ language.js │ └─ language.umd.js └─ browser/ ├─ index.es.js ├─ index.umd.js └─ index.css每个文件职责不同文件用途dist/index.jsnpm 包入口。它是 ESM 格式且将ckeditor5保留为外部依赖。dist/index.css面向 npm 使用者的 CSS 文件。需在消费应用中单独引入。dist/*.d.ts由src/生成的 TypeScript 声明文件随 npm 构建一起发布。dist/translations/*.js由lang/translations/*.ts生成的 ESM 与 UMD 翻译资源。dist/browser/index.es.js面向typemodule与 import map 方案的浏览器 ESM 构建。它仍然期望ckeditor5被单独提供。dist/browser/index.umd.js面向普通script标签的浏览器 UMD 构建。它期望全局对象CKEDITOR已存在并将你的包暴露在构建时选定的全局名上。dist/browser/index.css面向 ZIP 与 CDN 式浏览器集成的 CSS 文件。package.json已经预先配置好发布包时会一并带上dist/与ckeditor5-metadata.json。npm 消费方通过包入口的types字段自动获得生成的声明文件。从仓库中ckeditor5主包的 package.json 可以看到其publishConfig中同样把main指向dist/ckeditor5.js、types指向dist/index.d.ts并利用exports字段对./*、./browser/*等子路径做了精细的发布映射——这也是生成包在 npm 上正常工作的底层机制。翻译资源的加载遵循一致约定npm 与 import map 集成应导入 ESM 翻译资源script 标签集成则加载对应的.umd.js文件。请参考 Setting the UI language 指南并从ckeditor5加载同一种语言这样编辑器才能拿到该语言的复数形式函数。生成器不会提供的东西没有内置 CKEditor 5 的完整编辑器 bundle。没有可直接下载的 ZIP 压缩包。没有自动的 CDN 托管。通过 npm 使用构建产物从 npm or ZIP quick start 开始然后在此基础上接入你生成的包。当你的应用已经使用包管理器与打包器时npm 构建是正确选择。你可以把包发布到 npm、从本地路径安装或通过 workspace 使用。无论哪种方式消费项目加载的都是包根入口package root而不是dist/browser/。npm install ckeditor5 packageNameimport { ClassicEditor, Essentials, Paragraph } from ckeditor5; import { Callout } from packageName; import ckeditor5/ckeditor5.css; import packageName/index.css; ClassicEditor .create( { attachTo: document.querySelector( #editor ), root: { initialData: pHello from CKEditor 5!/p }, licenseKey: YOUR_LICENSE_KEY, // Or GPL. plugins: [ Essentials, Paragraph, Callout ], toolbar: [ undo, redo, |, callout ] } ) .then( /* ... */ ) .catch( /* ... */ );这段配置中attachTo指定编辑器挂载的 DOM 元素root.initialData提供初始内容plugins声明要启用的插件包括来自packageName的Callouttoolbar则把插件命令callout放进工具栏。licenseKey可填写你自己的许可证密钥或使用GPL走开源授权。TypeScript 消费方会通过包的types入口自动获得类型声明。通过 ZIP 方案使用构建产物同样从 npm or ZIP quick start 开始然后把dist/browser/复制到你存放解压后 CKEditor 5 ZIP 文件的同一静态资源目录中。推荐方案ESM import maps当页面通过 ESM 文件与 import map 加载 CKEditor 5 时使用dist/browser/index.es.jsdiv ideditor/div link relstylesheet href./vendor/ckeditor5/ckeditor5.css / link relstylesheet href./vendor/callout/index.css / script typeimportmap { imports: { ckeditor5: ./vendor/ckeditor5/ckeditor5.js, ckeditor5/: ./vendor/ckeditor5/, packageName: ./vendor/callout/index.es.js } } /script script typemodule import { ClassicEditor, Essentials, Paragraph } from ckeditor5; import { Callout } from packageName; ClassicEditor .create( { attachTo: document.querySelector( #editor ), root: { initialData: pHello from CKEditor 5!/p }, licenseKey: YOUR_LICENSE_KEY, // Or GPL. plugins: [ Essentials, Paragraph, Callout ], toolbar: [ undo, redo, |, callout ] } ) .then( /* ... */ ) .catch( /* ... */ ); /scriptimport map 将ckeditor5、ckeditor5/以及packageName三个模块说明符解析到本地 vendor 目录浏览器随后在script typemodule中按裸导入名解析这些模块。备选方案UMD script 标签当页面使用 ZIP 包里的 UMD 文件时使用dist/browser/index.umd.jsdiv ideditor/div link relstylesheet href./vendor/ckeditor5/ckeditor5.css / link relstylesheet href./vendor/callout/index.css / script src./vendor/ckeditor5/ckeditor5.umd.js/script script src./vendor/callout/index.umd.js/script script const { ClassicEditor, Essentials, Paragraph } CKEDITOR; const { Callout } CKCallout; ClassicEditor .create( { attachTo: document.querySelector( #editor ), root: { initialData: pHello from CKEditor 5!/p }, licenseKey: YOUR_LICENSE_KEY, // Or GPL. plugins: [ Essentials, Paragraph, Callout ], toolbar: [ undo, redo, |, callout ] } ) .then( /* ... */ ) .catch( /* ... */ ); /script注意这里存在两个全局对象CKEDITOR由ckeditor5.umd.js提供承载编辑器核心类CKCallout是示例 UMD 全局名由index.umd.js暴露。如果你的包是ckeditor5-calloutCKCallout是建议的默认全局名否则请替换为生成过程中确认的全局名。UMD 全局名的默认建议规则可以追溯到生成器命令行选项--global-name详见 using-package-generator 文档。通过 CDN 或云方案使用构建产物从 CDN quick start 开始然后自行托管生成的浏览器文件。CKEditor 5 本体可以来自 CDN而你的插件始终来自你自己的服务器。本文示例中的{var ckeditor5-version}占位符表示 CDN URL 中的 CKEditor 5 版本号需要替换为你实际使用或当前仓库 package.json 中声明的如 48.5.0的版本。推荐方案import mapsdiv ideditor/div link relstylesheet hrefhttps://cdn.ckeditor.com/ckeditor5/48.5.0/ckeditor5.css / link relstylesheet href/plugins/callout/index.css / script typeimportmap { imports: { ckeditor5: https://cdn.ckeditor.com/ckeditor5/48.5.0/ckeditor5.js, ckeditor5/: https://cdn.ckeditor.com/ckeditor5/48.5.0/, packageName: /plugins/callout/index.es.js } } /script script typemodule import { ClassicEditor, Essentials, Paragraph } from ckeditor5; import { Callout } from packageName; ClassicEditor .create( { attachTo: document.querySelector( #editor ), root: { initialData: pHello from CKEditor 5!/p }, licenseKey: YOUR_LICENSE_KEY, // Or GPL. plugins: [ Essentials, Paragraph, Callout ], toolbar: [ undo, redo, |, callout ] } ) .then( /* ... */ ) .catch( /* ... */ ); /script提示如果你的应用还使用 Vite请扩展 CDN quick start 中的外部化externalization配置让 Vite 也把你的自定义包导入保留为未解析状态交由 import map 在浏览器端处理。备选方案UMD 全局变量div ideditor/div link relstylesheet hrefhttps://cdn.ckeditor.com/ckeditor5/48.5.0/ckeditor5.css / link relstylesheet href/plugins/callout/index.css / script srchttps://cdn.ckeditor.com/ckeditor5/48.5.0/ckeditor5.umd.js/script script src/plugins/callout/index.umd.js/script script const { ClassicEditor, Essentials, Paragraph } CKEDITOR; const { Callout } CKCallout; ClassicEditor .create( { attachTo: document.querySelector( #editor ), root: { initialData: pHello from CKEditor 5!/p }, licenseKey: YOUR_LICENSE_KEY, // Or GPL. plugins: [ Essentials, Paragraph, Callout ], toolbar: [ undo, redo, |, callout ] } ) .then( /* ... */ ) .catch( /* ... */ ); /script此方案下ckeditor5.umd.js从 CDN 加载并暴露CKEDITORindex.umd.js从你自己的静态目录加载并暴露CKCallout二者在浏览器全局空间中完成拼接。快速选择正确的产物面对不同的项目形态可按下表快速决策如果项目使用…请使用这些生成文件npm 与打包器dist/index.js和dist/index.cssZIP 文件 import mapsdist/browser/index.es.js和dist/browser/index.cssZIP 文件 普通script标签dist/browser/index.umd.js和dist/browser/index.cssCKEditor Cloud CDN 自有静态托管dist/browser/index.es.js或dist/browser/index.umd.js外加dist/browser/index.css选择的关键在于两点你的页面如何解析模块打包器 / import map / 全局变量以及 CKEditor 5 本体从哪个渠道获得npm / 本地 ZIP / CDN。npm 场景永远走dist/根入口浏览器直载场景永远走dist/browser/插件 CSS 在任何场景下都需要单独引入。在此基础上再结合 ui-language 指南 为插件与编辑器配置一致的语言资源即可完成一套完整的自定义插件发布与集成闭环。【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
