企业官网建设流程全解析

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/ckeditor5

CKEditor 5 在 42.0.0 版本引入了全新的安装方式（New Installation Methods，NIM），将安装路径收敛为 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 Methods，OIM）下，从 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 迁移，文档给出了三种目标方案，选择取决于你是想要开箱即用的浏览器构建，还是想要可定制、可优化的构建：

其中 npm 包是最灵活、最强大的安装方式：它允许你创建一个只包含所需功能的编辑器自定义构建，从而显著减小最终构建体积；代价是你需要一个 JavaScript 打包器或元框架（webpack、Vite、Next.js 等）来产出该构建。如果你不想要构建流程，则可以选择 CDN 构建或下载 ZIP 归档——这两者都包含编辑器及所有插件，无需搭建构建流程即可使用 CKEditor 5 的全部功能。

方案一：迁移到 CDN build（无构建流程）

CDN 构建是在不安装任何依赖、不搭建构建流程的前提下快速把 CKEditor 5 添加到网站的好选择。迁移步骤如下：

1. 打开新版交互式 Builder，按需定制构建；
2. 在 Builder 的Installation（安装）部分选择Cloud (CDN)选项，即可获得如何将编辑器添加到网站的完整代码。

CDN 方式下编辑器通过<link>引入 CSS、通过<script type="importmap">将包名映射到构建 URL，再以<script type="module">导入编辑器与插件。若运行环境不支持 import map 或 ES Module，还可以改用 UMD 构建（通过全局变量CKEDITOR与CKEDITOR_PREMIUM_FEATURES访问）。完整示例代码可参阅 migration-to-new-installation-methods.md 中的"Browser builds"一节。

方案二：迁移到 ZIP archive（自托管）

如果你既不想拥有构建流程，也不打算使用 CDN 构建，可以下载包含编辑器构建的 ZIP 归档。迁移步骤：

1. 打开新版交互式 Builder，按需定制构建；
2. 在 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.ts（TypeScript 类型声明）
• ckeditor.js（编辑器源码）
• ckeditor.js.map（Source 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负责压缩 CSS，terser-webpack-plugin负责压缩 JS，css-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' ] } ] } };

与旧配置对比，可以发现三处关键简化：

1. 去掉了 CSS 处理链：旧方式需要用style-loader（内联注入样式）+postcss-loader+styles.getPostCssConfig()（来自@ckeditor/ckeditor5-dev-utils）处理ckeditor5-*/theme/*.css；新方式直接用MiniCssExtractPlugin.loader+css-loader一条规则即可。
2. 去掉了翻译插件：旧方式需要CKEditorTranslationsPlugin（来自@ckeditor/ckeditor5-dev-translations）并保持language配置与 webpack 同步；新方式下翻译以 JavaScript 对象形式在编辑器配置中传入，不再需要 webpack 参与。
3. 去掉了 SVG loader：旧方式需要raw-loader处理 SVG 图标；新安装方式下图标已随包分发，无需专门 loader。

第 7 步：在示例页面中引入独立 CSS

由于 CSS 已从 JS 中分离，需要在sample/index.html的其它 CSS 文件之前添加以下行：

<link rel="stylesheet" type="text/css" href="../build/ckeditor.css">

第 8 步：重新构建

删除旧的build文件夹，再次运行以下命令创建新构建：

npm run build

第 9 步：核对最终构建产物

这次新的build文件夹中应该出现五个文件：

• ckeditor.css
• ckeditor.css.map
• ckeditor.d.ts
• ckeditor.js
• ckeditor.js.map

迁移结果解读：3 个文件变为 5 个文件的性能改进

新构建比旧构建多出两个文件，原因是CSS 已从 JavaScript 文件中分离。相比旧的内联注入方式，这带来了两点改进：

1. CSS 独立成文件后，浏览器可以并行加载、缓存复用，同时你也能更轻松地自定义或移除编辑器默认样式（这一点在 migration-to-new-installation-methods.md 的"What's new?"一节中同样被列为新方式的亮点）；
2. 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.ts（TypeScript 源码），与现代打包器开箱即用。
• 依赖收敛：ckeditor5通过workspace:*聚合了从@ckeditor/ckeditor5-editor-classic到@ckeditor/ckeditor5-word-count的全部开源功能包（见 packages/ckeditor5/package.json 的dependencies），所以你只需安装这一个包即可获得全部开源插件，无需再逐个安装。

其构建脚本指向仓库根目录下的 scripts/nim/build-ckeditor5.mjs（"build": "node ../../scripts/nim/build-ckeditor5.mjs"），由仓库 CI 负责产出包含ckeditor.js、ckeditor.css、类型声明与翻译在内的发布产物。

进一步优化构建体积

如果你希望进一步优化构建（例如启用树摇（tree-shaking）以剔除未使用的功能、按需加载插件），可以继续参考仓库文档 Optimizing build size。该指南与本文互为补充：本文解决"如何迁移到新安装方式"，优化指南解决"迁移后如何把体积压到最小"。

相关迁移指南与补充阅读

新安装方式迁移是一个完整体系，旧版 Online Builder 迁移只是其中一环。按文档体系，建议按以下顺序完成整体迁移：

1. 若维护自定义插件独立包（monorepo 或发布到 npm）：先参考 Migrating custom plugins；
2. 再根据你的旧安装方式选择对应指南：
   • Migrating from predefined builds（预定义构建）
   • Migrating from legacy Online Builder（本文，旧版 Online Builder）
   • Migrating from customized builds（自定义构建）
   • Migrating from DLL builds（DLL 构建）
3. 若使用 React / Vue / Angular 集成，还需升级对应集成包（React 需^8.0.0、Vue 需^6.0.0、Angular 需^8.0.0）；
4. 若从 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