CKEditor 5 从 legacy Online Builder 迁移到新安装方式NIM实战指南【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5CKEditor 5 在 42.0.0 版本引入了全新的安装方式New Installation MethodsNIM将安装路径收敛为 npm 包与浏览器构建CDN两类旧版 Online Builder 生成的自定义构建随之进入废弃周期。本文以仓库文档 docs/updating/nim-migration/online-builder.md 为骨架完整讲解从旧版 Online Builder 迁移到 CDN、ZIP 归档与 npm 包三种新方案的步骤并结合仓库源码深入剖析迁移背后的原理帮助你无痛完成升级并精简构建链。读完本文你将掌握如何用新版交互式 Builder 生成 CDN 与 ZIP 构建如何在保留既有构建的情况下将项目迁移到 npm 包方式并移除旧版构建所需的 webpack 专用插件如ckeditor/ckeditor5-dev-translations、postcss-loader、raw-loader等以及迁移后构建产物从 3 个文件变为 5 个文件的性能改进逻辑。迁移背景为什么旧版 Online Builder 需要被替代旧版安装方式Old Installation MethodsOIM下从 Online Builder 下载的自定义构建本质上是一个打包好的黑盒编辑器与全部插件被编译进一个 JavaScript 文件样式以内联方式注入。这种方式存在几个痛点文档 migration-to-new-installation-methods.md 中有详细对比需要维护一套 CKEditor 专用的 webpack 配置处理翻译、CSS、SVG 的 loader使用 TypeScript 时复杂度更高依赖全局状态style-loader注入样式、CKEDITOR_TRANSLATIONS全局翻译对象难以在多个实例或 SSR 场景下工作无法与现代打包器、元框架如 Next.js开箱即用插件、图标、样式的定制受到构建方式的限制。新安装方式NIM将路径收敛为两条npm 包与浏览器构建。两者都不再要求逐个安装数十个ckeditor/ckeditor5-*子包而是从统一的ckeditor5包开源功能和ckeditor5-premium-features包商业功能中导入编辑器与插件CSS 与 JS 分离翻译作为 JavaScript 对象传入编辑器实例不再依赖全局状态。这也是旧版 Online Builder 用户必须迁移的根因。三条迁移路径概览如何选择从旧版 Online Builder 迁移文档给出了三种目标方案选择取决于你是想要开箱即用的浏览器构建还是想要可定制、可优化的构建目标方案是否需要构建步骤适合场景定制能力CDN build否不想安装任何依赖、不想搭建构建流程快速在网页中接入通过新版 Builder 在线定制ZIP archive否不需要构建流程也不打算用 CDN希望自托管通过新版 Builder 在线定制npm package是需打包器/元框架需要自定义构建、只打包所需功能、追求最小体积完全自定义其中 npm 包是最灵活、最强大的安装方式它允许你创建一个只包含所需功能的编辑器自定义构建从而显著减小最终构建体积代价是你需要一个 JavaScript 打包器或元框架webpack、Vite、Next.js 等来产出该构建。如果你不想要构建流程则可以选择 CDN 构建或下载 ZIP 归档——这两者都包含编辑器及所有插件无需搭建构建流程即可使用 CKEditor 5 的全部功能。方案一迁移到 CDN build无构建流程CDN 构建是在不安装任何依赖、不搭建构建流程的前提下快速把 CKEditor 5 添加到网站的好选择。迁移步骤如下打开新版交互式 Builder按需定制构建在 Builder 的Installation安装部分选择Cloud (CDN)选项即可获得如何将编辑器添加到网站的完整代码。CDN 方式下编辑器通过link引入 CSS、通过script typeimportmap将包名映射到构建 URL再以script typemodule导入编辑器与插件。若运行环境不支持 import map 或 ES Module还可以改用 UMD 构建通过全局变量CKEDITOR与CKEDITOR_PREMIUM_FEATURES访问。完整示例代码可参阅 migration-to-new-installation-methods.md 中的Browser builds一节。方案二迁移到 ZIP archive自托管如果你既不想拥有构建流程也不打算使用 CDN 构建可以下载包含编辑器构建的 ZIP 归档。迁移步骤打开新版交互式 Builder按需定制构建在 Builder 的Installation部分选择Self-hosted (ZIP)选项即可获得如何将编辑器通常连同静态资源一起托管添加到网站的说明。方案三迁移到 npm package保留既有构建的完整步骤如果你决定使用 npm 包可以有两个选择使用新版交互式 Builder 直接创建新构建或者在既有项目中从旧版 Online Builder 升级。官方推荐使用新版交互式 Builder但如果你想保留既有构建可以按下面的 9 个步骤操作。第 1 步先完成自定义构建迁移首先按照 Migrating from customized builds 指南的步骤操作。该指南的核心内容是卸载所有ckeditor/ckeditor5-*子包与ckeditor5旧包然后统一安装ckeditor5含编辑器与全部开源插件与可选ckeditor5-premium-features商业功能并将导入语句收敛到这两个包# 卸载旧包示意完整清单见 customized-builds.md npm uninstall ckeditor/ckeditor5-editor-classic ckeditor/ckeditor5-essentials ... # 安装新包 npm install ckeditor5 npm install ckeditor5-premium-features # 可选仅商业功能// 迁移后的导入方式替换原先来自各子包的分散导入 import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } from ckeditor5; import { FormatPainter, SlashCommand } from ckeditor5-premium-features; import ckeditor5/ckeditor5.css; import ckeditor5-premium-features/ckeditor5-premium-features.css;这一步完成了包来源的统一接下来才涉及构建链本身的精简。第 2 步删除旧构建并重新构建完成上述迁移后删除旧的build文件夹运行以下命令创建新的 CKEditor 5 构建npm run build第 3 步核对新的构建产物新的build文件夹中应该有三个文件ckeditor.d.tsTypeScript 类型声明ckeditor.js编辑器源码ckeditor.js.mapSource Map确认产物无误后就可以开始移除一些无用的 webpack 插件并更新webpack.config.js文件了。第 4 步卸载旧的 devDependencies卸载以下与旧构建链绑定的开发依赖它们分别负责旧方式下的翻译打包、样式处理、SVG 内联与压缩等新方式下已不再需要npm uninstall \ ckeditor/ckeditor5-dev-translations \ ckeditor/ckeditor5-dev-utils \ ckeditor/ckeditor5-theme-lark \ css-loader \ postcss \ postcss-loader \ raw-loader \ style-loader \ terser-webpack-plugin说明ckeditor/ckeditor5-dev-translations的废弃在 migration-to-new-installation-methods.md 的废弃时间线一节也有明确交代——自定义构建方式支持到 2026 年第一季度3 月末届时该包将不再需要新包版本也不再包含src目录dist目录将成为主要入口。第 5 步安装新的 devDependencies安装以下用于CSS 与 JS 分离 压缩的构建依赖npm install --save-dev \ css-loader \ css-minimizer-webpack-plugin \ mini-css-extract-plugin \ terser-webpack-plugin其中mini-css-extract-plugin负责把 CSS 抽取为独立文件css-minimizer-webpack-plugin负责压缩 CSSterser-webpack-plugin负责压缩 JScss-loader负责在打包器中解析 CSS。第 6 步更新 webpack.config.js将webpack.config.js更新为以下内容该配置是文档提供的完整版本可直接复制使用use strict; /* eslint-env node */ const path require( path ); const TerserWebpackPlugin require( terser-webpack-plugin ); const MiniCssExtractPlugin require( mini-css-extract-plugin ); const CssMinimizerPlugin require( css-minimizer-webpack-plugin ); module.exports { devtool: source-map, performance: { hints: false }, entry: path.resolve( __dirname, src, ckeditor.ts ), output: { // 编辑器导出时使用的名称。 library: ClassicEditor, path: path.resolve( __dirname, build ), filename: ckeditor.js, libraryTarget: umd, libraryExport: default }, optimization: { minimize: true, minimizer: [ new CssMinimizerPlugin(), new TerserWebpackPlugin( { terserOptions: { output: { // 保留 CKEditor 5 许可声明注释。 comments: /^!/ } }, extractComments: false } ) ] }, plugins: [ new MiniCssExtractPlugin( { filename: ckeditor.css } ), ], resolve: { extensions: [ .ts, .js, .json ] }, module: { rules: [ { test: /\.ts$/, use: ts-loader }, { test: /\.css$/i, use: [ MiniCssExtractPlugin.loader, css-loader ] } ] } };与旧配置对比可以发现三处关键简化去掉了 CSS 处理链旧方式需要用style-loader内联注入样式postcss-loaderstyles.getPostCssConfig()来自ckeditor/ckeditor5-dev-utils处理ckeditor5-*/theme/*.css新方式直接用MiniCssExtractPlugin.loadercss-loader一条规则即可。去掉了翻译插件旧方式需要CKEditorTranslationsPlugin来自ckeditor/ckeditor5-dev-translations并保持language配置与 webpack 同步新方式下翻译以 JavaScript 对象形式在编辑器配置中传入不再需要 webpack 参与。去掉了 SVG loader旧方式需要raw-loader处理 SVG 图标新安装方式下图标已随包分发无需专门 loader。第 7 步在示例页面中引入独立 CSS由于 CSS 已从 JS 中分离需要在sample/index.html的其它 CSS 文件之前添加以下行link relstylesheet typetext/css href../build/ckeditor.css第 8 步重新构建删除旧的build文件夹再次运行以下命令创建新构建npm run build第 9 步核对最终构建产物这次新的build文件夹中应该出现五个文件ckeditor.cssckeditor.css.mapckeditor.d.tsckeditor.jsckeditor.js.map迁移结果解读3 个文件变为 5 个文件的性能改进新构建比旧构建多出两个文件原因是CSS 已从 JavaScript 文件中分离。相比旧的内联注入方式这带来了两点改进CSS 独立成文件后浏览器可以并行加载、缓存复用同时你也能更轻松地自定义或移除编辑器默认样式这一点在 migration-to-new-installation-methods.md 的Whats new?一节中同样被列为新方式的亮点JavaScript 与 CSS 文件都被压缩minified进一步改善加载性能。当更新使用build文件夹的项目时记得同时引入新的 CSS 文件——这是最容易遗漏的一步。仓库源码佐证新安装方式的包结构与构建脚本从仓库源码可以印证迁移目标的实现细节。聚合包 packages/ckeditor5/package.json 展示了ckeditor5包的结构{ name: ckeditor5, version: 48.5.0, type: module, main: ./src/index.ts, exports: { .: ./src/index.ts, ./*: ./* }, publishConfig: { main: ./dist/ckeditor5.js, types: ./dist/index.d.ts, exports: { .: { types: ./dist/index.d.ts, import: ./dist/ckeditor5.js }, ./*: ./dist/*, ... } } }解读两点发布时统一入口publishConfig中发布产物指向./dist/ckeditor5.js与./dist/index.d.ts这正是文档所述所有导入都通过包的 index 进行开发环境下则直接使用./src/index.tsTypeScript 源码与现代打包器开箱即用。依赖收敛ckeditor5通过workspace:*聚合了从ckeditor/ckeditor5-editor-classic到ckeditor/ckeditor5-word-count的全部开源功能包见 packages/ckeditor5/package.json 的dependencies所以你只需安装这一个包即可获得全部开源插件无需再逐个安装。其构建脚本指向仓库根目录下的 scripts/nim/build-ckeditor5.mjsbuild: node ../../scripts/nim/build-ckeditor5.mjs由仓库 CI 负责产出包含ckeditor.js、ckeditor.css、类型声明与翻译在内的发布产物。进一步优化构建体积如果你希望进一步优化构建例如启用树摇tree-shaking以剔除未使用的功能、按需加载插件可以继续参考仓库文档 Optimizing build size。该指南与本文互为补充本文解决如何迁移到新安装方式优化指南解决迁移后如何把体积压到最小。相关迁移指南与补充阅读新安装方式迁移是一个完整体系旧版 Online Builder 迁移只是其中一环。按文档体系建议按以下顺序完成整体迁移若维护自定义插件独立包monorepo 或发布到 npm先参考 Migrating custom plugins再根据你的旧安装方式选择对应指南Migrating from predefined builds预定义构建Migrating from legacy Online Builder本文旧版 Online BuilderMigrating from customized builds自定义构建Migrating from DLL buildsDLL 构建若使用 React / Vue / Angular 集成还需升级对应集成包React 需^8.0.0、Vue 需^6.0.0、Angular 需^8.0.0若从 v46 之前的版本升级导入名称已标准化可参考 Migrating imports (v46) 中的变更对照表。整体背景、新旧方式对比与废弃时间线预定义构建支持至 2025 年第一季度末、自定义构建与 DLL 支持至 2026 年第一季度末可通读 migration-to-new-installation-methods.md 获取全貌。常见问题与注意事项CSS 忘记引入迁移后build目录多出ckeditor.css若项目直接引用build目录务必在 JS 之前引入该 CSS否则编辑器将丢失全部样式。webpack 配置残留第 4 步卸载的raw-loader、style-loader、postcss-loader、ckeditor/ckeditor5-dev-translations等如果继续保留不仅多余还可能在新构建链中引发冲突第 6 步的配置是精简后的正确形态。构建环境前提npm 方式需要你具备 JavaScript 打包器或元框架webpack、Vite、Next.js 等完全不想接触构建工具则优先选 CDN 或 ZIP 方案。版本升级顺序迁移前请先按常规升级路径将项目更新到最新版 CKEditor 5以排除旧版本带来的干扰这是 customized-builds.md 中明确的前置条件。【免费下载链接】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），仅供参考