CKEditor 5 v46.x 升级迁移指南统一 API 导出、默认内容样式与破坏性变更全解析【免费下载链接】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 从 v45 及更早版本升级到 v46.x 的集成开发者系统梳理 v46.0.0v46.1.1 各版本的更新要点重点讲解 v46.0.0 这一大版本中引入的统一导出/重命名规则、默认内容样式--ck-content-*CSS 变量体系、列表与表格的标记变化以及多款破坏性变更的迁移方法。读完本文你将掌握 v46 升级中每一处可能影响现有集成的问题点、对应的迁移代码与 CSS 修复方案并了解 v46.0.3 安全补丁CVE-2025-58064的适用范围。升级前须知在开始升级 CKEditor 5 之前请务必确认以下两点所有包必须保持同一版本升级时应确保ckeditor5及其相关包全部更新到同一个 v46.x 版本避免因版本混用导致功能异常或编译错误。必要时清理锁文件重装如果升级后遇到依赖解析问题可以删除package-lock.json或yarn.lock视你的包管理器而定重新安装全部依赖后再重新构建编辑器并尽量使用最新的包版本。升级前建议先通读本文特别是 统一导出与 API 重命名 与 默认内容样式与 CSS 变量重命名 两节——它们是 v46.0.0 中影响面最大的两个变更点也是最容易在升级后触发编译错误或内容外观变化的来源。v46.0.0大版本核心变更概览v46.0.0 于 2025 年 7 月 9 日发布是一次主版本发布包含大量可能影响现有集成的变更涉及 API 精炼、新功能与既有功能的改进。官方明确提示升级时应通读完整升级指南并特别关注编辑器 API 中大量导入/导出名称的变更见下文统一导出与 API 重命名新引入的默认内容样式可能影响内容外观见下文默认内容样式。以下先介绍该版本带来的新功能与体验改进再逐个展开需要开发者动手迁移的破坏性变更。新功能行高Line Heightv46.0.0 引入了全新的行高Line Height功能允许调整文本行之间的垂直间距提升文档可读性与视觉协调性。该功能为高级premium功能可跨段落和文本块设置一致的行间距改善文档的可访问性并维持内容的视觉层级。行高功能在实现上同时推动了列表与表格中段落垂直间距的规范化修复详见 改进段落垂直间距这也是该版本内容外观可能发生变化的原因之一。Remove Format 改进点击清除格式按钮时此前未被打扫干净的内容现在会被正确清理表格、图片等块级元素上多余的样式以及 General HTML SupportGHS产生的节点和属性都会被一并移除同时保持文档结构本身不被破坏。列表标记样式继承使用样式化列表styled lists时列表标记项目符号和编号现在会自动继承文本的样式属性字号调整文字颜色变化字体粗细修改加粗、斜体。该改进让列表在无需额外配置的情况下即可获得视觉一致的专业外观并同样支持多级列表multi-level lists。重要提示该行为默认开启因此升级后加载旧内容到新版本编辑器时内容外观可能发生变化。如果这不是你期望的行为可以按照列表属性功能的说明选择退出禁用标记格式化。此变更的实现细节位于 packages/ckeditor5-list/src 的列表格式化相关模块中。Markdown 处理器依赖刷新Markdown 功能的依赖实现已全面现代化从原来的marked/turndown实现切换到unified生态体系采用同一技术家族的remarkMarkdown 解析与rehypeHTML 处理。这一变化带来更一致、更对称的 HTML ↔ Markdown 双向转换使文档处理实现更可靠、更易维护。仓库中对应的包为 packages/ckeditor5-markdown-gfm。手动 Token 刷新新增配置属性config.cloudServices.autoRefresh用于关闭自动 Token 刷新机制。当设置为false时Token 必须由开发者手动刷新。该属性为需要自定义 Token 处理逻辑的场景例如特定的安全策略或认证流程打开了实现空间。相关配置在 packages/ckeditor5-cloud-services 包中解析使用。ClassicEditor.create( document.querySelector( #editor ), { cloudServices: { tokenUrl: https://example.com/token, autoRefresh: false // 关闭自动刷新改为手动刷新 } } );统一导出与 API 重命名这是 v46.0.0 中最重要、影响面最广的变更。自 v42.0.0 引入新安装方式NIM之后部分从 v41.x 直接升级到 v42.x 的开发者会遇到does not provide an export named …之类的报错。v46 从根因上解决了这一问题确立了长期执行的 API 导出规则每个公共 API 都必须通过包的index.ts导出每个内部 API 必须显式标注internal导出名称应遵循与其用途和上下文一致、具有描述性且唯一的命名模式源文件中不允许出现export default或export * from语句。这些规则带来的具体结果补充缺失的 re-export重命名导出项使其更具描述性并避免命名冲突对已导出但未标注internal的内部方法保留导出但增加_前缀——它们仍然可用但官方希望了解你的使用方式借机清理了多年未动的deprecated代码。官方同时开发了内部工具链为未来的 API 演进设置护栏防止此类问题再次发生。如何迁移你的导入语句如果升级后构建报错只需按照 migrating-imports.md 中的对照表将旧名称搜索替换为新名称即可。API 的行为没有改变改变的只是名称。该文档按字母顺序列出所有发生名称变更的导出项例如包文件原名称新名称adapter-ckfinderutils.tsgetCsrfToken_getCKFinderCsrfTokenalignmentalignmentconfig.tsSupportedOptionAlignmentSupportedOptionclipboarddragdrop.tsDragDrop_DragDropckboxutils.tsgetImageUrls_getCKBoxImageUrls…………由于需要手动更新的导入数量众多逐一修改耗时且容易出错官方建议将 migrating-imports.md 中变更名称的对照表作为上下文提供给 Copilot、ChatGPT 等 LLM 工具让其自动完成项目中所有导入的批量更新。内部 API 的_前缀访问方式在旧安装方式OIM下开发者可以依赖包内特定文件为内部用途而导出的函数。NIM 环境下这类内部 API 将不再出现在 index 中且未来 OIM 被废弃后源文件将不可用。为平滑过渡此前可用的所有内部导出现在统一从ckeditor5或ckeditor5-premium-features包的根入口以_前缀导出。以 adapter-ckfinder 的 CSRF Token 获取函数为例// 之前从深层文件路径导入内部函数 import { getCsrfToken } from ckeditor/ckeditor5-adapter-ckfinder/src/utils; // 现在从包根入口导入带 _ 前缀 import { _getCKFinderCsrfToken } from ckeditor5;需要留意的是这些_前缀的内部 API 可能在未来的版本中被移除且新的内部方法不会再加入 index。如果认为某个内部方法应当进入公共 API可通过官方支持渠道反馈。默认内容样式与 CSS 变量重命名引入默认内容样式层为了改善开箱即用体验与可访问性v46.0.0 开始在.ck-content上应用一层轻量默认样式。从该版本起编辑器内容区域默认使用以下 CSS 变量:root { --ck-content-font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif; --ck-content-font-size: medium; --ck-content-font-color: #000; --ck-content-line-height: 1.5; --ck-content-word-break: break-word; } .ck-content { font-family: var(--ck-content-font-family); font-size: var(--ck-content-font-size); color: var(--ck-content-font-color); line-height: var(--ck-content-line-height); word-break: var(--ck-content-word-break); }这些默认值均可通过覆盖 CSS 变量轻松替换。如果你此前使用更具体的选择器处理过这些样式从 v46 开始官方建议改用这些变量。注意默认字体颜色使用#000十六进制而非hsl()这是为了确保与邮件客户端的兼容性。迁移如果发现新版本的内容样式影响了内容外观请更新自定义样式表并使用新的变量名。内容区域 CSS 变量重命名为--ck-content-*前缀为提升一致性所有影响编辑器内容区域样式的 CSS 变量内容样式均已重命名为--ck-content-*前缀。涉及高亮、图片说明、提及、表格说明、图片样式间距、待办清单勾选标记等变量。完整对照如下旧变量名新变量名--ck-highlight-marker-yellow--ck-content-highlight-marker-yellow--ck-highlight-marker-green--ck-content-highlight-marker-green--ck-highlight-marker-pink--ck-content-highlight-marker-pink--ck-highlight-marker-blue--ck-content-highlight-marker-blue--ck-highlight-pen-red--ck-content-highlight-pen-red--ck-highlight-pen-green--ck-content-highlight-pen-green--ck-color-image-caption-background--ck-content-color-image-caption-background--ck-color-image-caption-text--ck-content-color-image-caption-text--ck-color-mention-background--ck-content-color-mention-background--ck-color-mention-text--ck-content-color-mention-text--ck-color-selector-caption-background⚠️ 新名称--ck-content-color-table-caption-background--ck-color-selector-caption-text⚠️ 新名称--ck-content-color-table-caption-text--ck-image-style-spacing--ck-content-image-style-spacing--ck-inline-image-style-spacing--ck-content-inline-image-style-spacing--ck-todo-list-checkmark-size--ck-content-todo-list-checkmark-size--ck-table-of-contents-padding--ck-content-table-of-contents-padding--ck-table-of-contents-line-height--ck-content-table-of-contents-line-height--ck-table-of-contents-items-start-padding--ck-content-table-of-contents-items-start-padding迁移请更新自定义样式表、主题与集成代码以使用新变量名旧变量名不再受支持设置后不会产生任何效果。示例:root { --ck-content-highlight-marker-yellow: #fdfd77; --ck-content-color-image-caption-background: hsl(0, 0%, 97%); }表格相关 CSS 变量重命名为-table-部分表格相关变量名称中的-selector-一词容易引起混淆、命名不一致现已统一改为-table-旧变量名新变量名--ck-color-selector-caption-highlighted-background--ck-color-table-caption-highlighted-background--ck-color-selector-column-resizer-hover--ck-color-table-column-resizer-hover--ck-color-selector-focused-cell-background--ck-color-table-focused-cell-background迁移更新自定义样式表与主题以使用新变量名旧名称不再受支持。示例:root { --ck-color-table-caption-highlighted-background: hsl(52deg 100% 50%); --ck-color-table-column-resizer-hover: var(--ck-color-base-active); --ck-color-table-focused-cell-background: hsla(212, 90%, 80%, .3); }列表相关变更多级列表标记结构变化为修复列表标记格式化问题多级列表Multi-level list功能的输出标记发生了变化。此变化没有视觉影响但可能触发某些自动化测试的断言失败。升级过程中无需迁移已有内容。变化前后对比!-- 之前 -- ol classmulti-level-list legal-list stylelist-style-type:none; li span classmulti-level-list__marker1. /spanFoo bar /li /ol !-- 之后 -- ol classmulti-level-list legal-list stylelist-style-type:none; li span classmulti-level-list__markerspan1./spannbsp;/spanFoo bar /li /ol从源码结构看这一变更涉及 packages/ckeditor5-list/src 中列表格式化list formatting相关的数据转换逻辑即标记文本被包进独立span并辅以nbsp;空格。列表项标识data-list-item-id编辑器数据中的li元素现在会带有一个data-list-item-id属性用于改进列表功能与其他编辑器功能的集成。该属性为列表项提供跨数据加载/保存保持稳定的标识解决了数据稳定性问题并提升了与外部系统及 diff 算法的兼容性。!-- 之前 -- ul li pFirst item/p pSecond paragraph/p /li liAnother item/li /ul !-- 之后 -- ul li>// 获取不含列表项 ID 的数据仅用于展示 const cleanHtml editor.getData( { skipListItemIds: true } );改进段落垂直间距在开发行高功能的过程中编辑器修复了一个长期存在的 bug列表与表格单元格中段落的间距行为。该修复通过自定义内容样式实现升级后可能带来可见的视觉变化。如果不满意可以通过以下 CSS 还原旧行为.ck-content li p:first-of-type { margin-top: revert; } .ck-content li p:only-of-type { margin-top: revert; margin-bottom: revert; } .ck-content table.table:not(.layout-table), .ck-content figure.table:not(.layout-table) table { thead, tbody { tr { td, th { p:first-of-type { margin-top: revert; } p:last-of-type { margin-bottom: revert; } } } } }评论Comments相关变更评论批注样式标准化评论批注的默认样式发生了显著变化。此前默认样式仅作用于部分评论 UI且评论 UI 会受主编辑器内容样式影响。现在引入了一组标准化的 CSS 变量同时作用于评论内容与输入框--ck-comment-content-font-family--ck-comment-content-font-size--ck-comment-content-font-color这些变量的默认值基于编辑器 UI 样式派生可能与当前设置不同。最明显的变化是默认字体颜色从黑色hsl(0, 0%, 0%)改为深灰色hsl(0, 0%, 20%)以与编辑器其余 UI 保持一致。迁移步骤升级编辑器后检查评论的外观若新默认样式不符合设计需求用新 CSS 变量设置自定义值:root { --ck-comment-content-font-family: Your preferred font family; --ck-comment-content-font-size: 14px; --ck-comment-content-font-color: hsl(0, 0%, 0%); /* 或你偏好的颜色 */ }新线程命令改进addCommandThread命令得到增强现在支持在指定范围range上创建评论线程也支持以给定的评论内容创建带初始评论的线程。次要破坏性变更AddCommandThreadCommand#isEnabled在文档选区为空时不再返回false因为命令现在支持在自定义范围上创建线程。如果你此前依赖该属性例如用于控制自定义 UI 元素应改用可观察属性AddCommentThreadCommand#hasContent。评论与建议批注的辅助方法v46 还引入了专门的方法用于更便捷地获取与某条评论或建议相关联的批注annotation以及反向的关联查询。安全修复CVE-2025-58064v46.0.3v46.0.3 于 2025 年 9 月 3 日发布修复了剪贴板包ckeditor5-clipboard中发现的跨站脚本XSS漏洞CVE-2025-58064。该漏洞可被特定的用户操作触发若攻击者成功向编辑器插入恶意内容可能在特定编辑器配置下发生将导致未经授权的 JavaScript 代码执行。该漏洞仅影响满足以下任一条件的编辑器配置启用了 HTML embed 插件启用了引入可编辑元素、且该元素实现了 view 层RawElement见 ckeditor5-engine 的引擎视图模型的自定义插件。如果使用以上配置请务必升级到 v46.0.3 或更高版本并参考相关安全公告了解详情。v46.0.1文档改版与分页能力增强v46.0.1 于 2025 年 8 月 11 日发布带来以下改进完整的文档重新设计新的文档主题提升了可读性修复了多处可访问性问题重新设计的导航栏更方便访问各产品文档分区改进的目录与搜索功能让查找指南更轻松。分页插件显著增强分页计算现在会考虑内容样式、书签标记并具备更好的容差计算分页还能为大型目录和高于页面的图片找到正确的分页断点。表格与分页、PDF 导出的配合分页与导出为 PDF 功能现在更好地支持包含一个或多个段落的表格导出表格时单元格边距被正确应用提升了分页渲染的精度。v46.0.2归档评论线程热修复v46.0.2 于 2025 年 8 月 19 日发布属于热修复版本修复了已归档的评论线程可能错误地出现在侧边栏中的问题确保归档线程始终正确地保留在评论归档中。v46.1.0稳定性与细节优化v46.1.0 于 2025 年 9 月 10 日发布是一个聚焦修复与 UX 改进的次要稳定版本iOS 上更流畅的拖拽更新了 iOS 触屏设备的拖放实现桌面端行为保持不变。分页改进回退了一项底层变更以提升分页稳定性尤其是包含长表格的场景。服务端编辑 API 支持隐藏用户服务端编辑器 API 现在支持hidden_in_presence_list用户标志可防止自动化脚本用户在脚本运行期间出现在编辑器的在线状态列表中。评论标记清理更好地处理标记指向不存在评论线程的边界情况例如因集成方失误造成此类标记现在会被自动移除以保持编辑器稳定。该版本的次要破坏性变更real-time-collaborationCloudServicesCommentsAdapter#getCommentThread在评论线程不存在时不再抛出错误而是返回null。v46.1.1开发基础设施现代化无 API 影响v46.1.1 于 2025 年 9 月 15 日发布是一个聚焦改进开发基础设施与发布流程的内部版本对集成方没有功能影响包管理从 Yarn Classic 迁移到pnpm带来更快的安装高效链接机制、更严格的依赖解析与更好的 peer dependency 处理以及消除跨项目重复包的磁盘效率提升引入依赖锁定机制提升构建过程的稳定性与可预测性确保开发环境与 CI/CD 管道环境一致。如果你 fork 了本仓库并基于源码开发需要按照仓库内开发环境指南见 docs/framework/contributing更新开发环境配置作为普通集成方本版本保持完全向后兼容无需任何改动。v46.0.0 破坏性变更汇总主要破坏性变更涉及包变更说明aiAI Assistant 默认模型从gpt-3.5-turbo升级为更先进的gpt-4o并移除了max_tokens的默认限制以支持更详细回复。若需沿用旧默认值请显式配置ai.openAi.requestParameters为{ model: gpt-3.5-turbo, max_tokens: 2000, stream: true }document-outline目录功能的内容区域 CSS 变量已重命名为--ck-content-*前缀覆盖过这些变量的集成需要更新list移除了列表项内的垂直间距重置li子元素p的边距table移除了表格单元格内的垂直间距折叠td/th中唯一子元素p的边距全部编辑器编辑器现在对编辑视图与渲染输出的文本内容强制应用浏览器默认样式可能影响现有样式与布局所有自定义 CSS 覆盖都应重新审查。新增--ck-content-font-familyHelvetica, Arial, Tahoma, Verdana, sans-serif、--ck-content-font-sizemedium、--ck-content-font-color#000十六进制以兼容邮件客户端、--ck-content-line-height1.5、--ck-content-word-breakbreak-word全部评论评论批注默认样式变更新增--ck-comment-content-font-family、--ck-comment-content-font-size、--ck-comment-content-font-color默认从hsl(0, 0%, 0%)改为hsl(0, 0%, 20%)需要审查升级后评论外观Highlight / Image / List / Table内容区域 CSS 变量重命名为--ck-content-*前缀Table名称不当的*-selector-*变量重命名为*-table-*次要破坏性变更涉及包变更说明commentsAddCommandThreadCommand#isEnabled在选区为空时不再为false改用可观察属性AddCommentThreadCommand#hasContentcore移除了已废弃的DataApiMixin函数与DataApi接口其功能已并入 Editor 类engine移除了已废弃的Batch#type属性list移除了DocumentList、DocumentListProperties、TodoDocumentList插件它们分别是List、ListProperties、DocumentList的别名markdown-gfm从marked/turndown迁移到remark/rehype提升可扩展性并融入现代 Markdown 生态同时启用了 Markdown 内容加载时的自动链接autolinking功能ui移除了FileDialogViewMixin创建按钮上的已废弃buttonView属性请直接使用按钮对象本身utils移除了已废弃的mix函数utils移除了已废弃的Locale#language属性请改用Locale#uiLanguage升级检查清单完成升级后建议按以下清单逐项核对确保迁移无遗漏依赖版本确认所有 CKEditor 5 相关包均为同一 v46.x 版本构建错误若出现does not provide an export named …对照 migrating-imports.md 更新所有导入名称内容外观检查编辑器内容区域的字体、行高、间距是否符合预期必要时覆盖--ck-content-*系列变量自定义样式全文搜索--ck-highlight-*、--ck-color-*、--ck-image-*、--ck-todo-list-*等旧变量名并替换为新名称列表与表格确认多级列表标记结构与data-list-item-id属性不会破坏你的数据处理或测试断言纯展示场景可用getData( { skipListItemIds: true } )评论/协作检查评论批注样式评估addCommandThread相关 UI 是否依赖isEnabled若依赖请改用hasContent安全若启用了 HTML embed 或自定义RawElement插件确认已升级到 v46.0.3 及以上版本AI 与云服务如需保持旧 AI 模型与 Token 行为显式配置ai.openAi.requestParameters与cloudServices.autoRefresh。完成以上核查后即可正常使用 CKEditor 5 v46.x 的完整能力并为后续版本迭代打下稳定的升级基础。【免费下载链接】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），仅供参考 CKEditor 5 v46.x 升级迁移指南：统一 API 导出、默认内容样式与破坏性变更全解析
CKEditor 5 v46.x 升级迁移指南统一 API 导出、默认内容样式与破坏性变更全解析【免费下载链接】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 从 v45 及更早版本升级到 v46.x 的集成开发者系统梳理 v46.0.0v46.1.1 各版本的更新要点重点讲解 v46.0.0 这一大版本中引入的统一导出/重命名规则、默认内容样式--ck-content-*CSS 变量体系、列表与表格的标记变化以及多款破坏性变更的迁移方法。读完本文你将掌握 v46 升级中每一处可能影响现有集成的问题点、对应的迁移代码与 CSS 修复方案并了解 v46.0.3 安全补丁CVE-2025-58064的适用范围。升级前须知在开始升级 CKEditor 5 之前请务必确认以下两点所有包必须保持同一版本升级时应确保ckeditor5及其相关包全部更新到同一个 v46.x 版本避免因版本混用导致功能异常或编译错误。必要时清理锁文件重装如果升级后遇到依赖解析问题可以删除package-lock.json或yarn.lock视你的包管理器而定重新安装全部依赖后再重新构建编辑器并尽量使用最新的包版本。升级前建议先通读本文特别是 统一导出与 API 重命名 与 默认内容样式与 CSS 变量重命名 两节——它们是 v46.0.0 中影响面最大的两个变更点也是最容易在升级后触发编译错误或内容外观变化的来源。v46.0.0大版本核心变更概览v46.0.0 于 2025 年 7 月 9 日发布是一次主版本发布包含大量可能影响现有集成的变更涉及 API 精炼、新功能与既有功能的改进。官方明确提示升级时应通读完整升级指南并特别关注编辑器 API 中大量导入/导出名称的变更见下文统一导出与 API 重命名新引入的默认内容样式可能影响内容外观见下文默认内容样式。以下先介绍该版本带来的新功能与体验改进再逐个展开需要开发者动手迁移的破坏性变更。新功能行高Line Heightv46.0.0 引入了全新的行高Line Height功能允许调整文本行之间的垂直间距提升文档可读性与视觉协调性。该功能为高级premium功能可跨段落和文本块设置一致的行间距改善文档的可访问性并维持内容的视觉层级。行高功能在实现上同时推动了列表与表格中段落垂直间距的规范化修复详见 改进段落垂直间距这也是该版本内容外观可能发生变化的原因之一。Remove Format 改进点击清除格式按钮时此前未被打扫干净的内容现在会被正确清理表格、图片等块级元素上多余的样式以及 General HTML SupportGHS产生的节点和属性都会被一并移除同时保持文档结构本身不被破坏。列表标记样式继承使用样式化列表styled lists时列表标记项目符号和编号现在会自动继承文本的样式属性字号调整文字颜色变化字体粗细修改加粗、斜体。该改进让列表在无需额外配置的情况下即可获得视觉一致的专业外观并同样支持多级列表multi-level lists。重要提示该行为默认开启因此升级后加载旧内容到新版本编辑器时内容外观可能发生变化。如果这不是你期望的行为可以按照列表属性功能的说明选择退出禁用标记格式化。此变更的实现细节位于 packages/ckeditor5-list/src 的列表格式化相关模块中。Markdown 处理器依赖刷新Markdown 功能的依赖实现已全面现代化从原来的marked/turndown实现切换到unified生态体系采用同一技术家族的remarkMarkdown 解析与rehypeHTML 处理。这一变化带来更一致、更对称的 HTML ↔ Markdown 双向转换使文档处理实现更可靠、更易维护。仓库中对应的包为 packages/ckeditor5-markdown-gfm。手动 Token 刷新新增配置属性config.cloudServices.autoRefresh用于关闭自动 Token 刷新机制。当设置为false时Token 必须由开发者手动刷新。该属性为需要自定义 Token 处理逻辑的场景例如特定的安全策略或认证流程打开了实现空间。相关配置在 packages/ckeditor5-cloud-services 包中解析使用。ClassicEditor.create( document.querySelector( #editor ), { cloudServices: { tokenUrl: https://example.com/token, autoRefresh: false // 关闭自动刷新改为手动刷新 } } );统一导出与 API 重命名这是 v46.0.0 中最重要、影响面最广的变更。自 v42.0.0 引入新安装方式NIM之后部分从 v41.x 直接升级到 v42.x 的开发者会遇到does not provide an export named …之类的报错。v46 从根因上解决了这一问题确立了长期执行的 API 导出规则每个公共 API 都必须通过包的index.ts导出每个内部 API 必须显式标注internal导出名称应遵循与其用途和上下文一致、具有描述性且唯一的命名模式源文件中不允许出现export default或export * from语句。这些规则带来的具体结果补充缺失的 re-export重命名导出项使其更具描述性并避免命名冲突对已导出但未标注internal的内部方法保留导出但增加_前缀——它们仍然可用但官方希望了解你的使用方式借机清理了多年未动的deprecated代码。官方同时开发了内部工具链为未来的 API 演进设置护栏防止此类问题再次发生。如何迁移你的导入语句如果升级后构建报错只需按照 migrating-imports.md 中的对照表将旧名称搜索替换为新名称即可。API 的行为没有改变改变的只是名称。该文档按字母顺序列出所有发生名称变更的导出项例如包文件原名称新名称adapter-ckfinderutils.tsgetCsrfToken_getCKFinderCsrfTokenalignmentalignmentconfig.tsSupportedOptionAlignmentSupportedOptionclipboarddragdrop.tsDragDrop_DragDropckboxutils.tsgetImageUrls_getCKBoxImageUrls…………由于需要手动更新的导入数量众多逐一修改耗时且容易出错官方建议将 migrating-imports.md 中变更名称的对照表作为上下文提供给 Copilot、ChatGPT 等 LLM 工具让其自动完成项目中所有导入的批量更新。内部 API 的_前缀访问方式在旧安装方式OIM下开发者可以依赖包内特定文件为内部用途而导出的函数。NIM 环境下这类内部 API 将不再出现在 index 中且未来 OIM 被废弃后源文件将不可用。为平滑过渡此前可用的所有内部导出现在统一从ckeditor5或ckeditor5-premium-features包的根入口以_前缀导出。以 adapter-ckfinder 的 CSRF Token 获取函数为例// 之前从深层文件路径导入内部函数 import { getCsrfToken } from ckeditor/ckeditor5-adapter-ckfinder/src/utils; // 现在从包根入口导入带 _ 前缀 import { _getCKFinderCsrfToken } from ckeditor5;需要留意的是这些_前缀的内部 API 可能在未来的版本中被移除且新的内部方法不会再加入 index。如果认为某个内部方法应当进入公共 API可通过官方支持渠道反馈。默认内容样式与 CSS 变量重命名引入默认内容样式层为了改善开箱即用体验与可访问性v46.0.0 开始在.ck-content上应用一层轻量默认样式。从该版本起编辑器内容区域默认使用以下 CSS 变量:root { --ck-content-font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif; --ck-content-font-size: medium; --ck-content-font-color: #000; --ck-content-line-height: 1.5; --ck-content-word-break: break-word; } .ck-content { font-family: var(--ck-content-font-family); font-size: var(--ck-content-font-size); color: var(--ck-content-font-color); line-height: var(--ck-content-line-height); word-break: var(--ck-content-word-break); }这些默认值均可通过覆盖 CSS 变量轻松替换。如果你此前使用更具体的选择器处理过这些样式从 v46 开始官方建议改用这些变量。注意默认字体颜色使用#000十六进制而非hsl()这是为了确保与邮件客户端的兼容性。迁移如果发现新版本的内容样式影响了内容外观请更新自定义样式表并使用新的变量名。内容区域 CSS 变量重命名为--ck-content-*前缀为提升一致性所有影响编辑器内容区域样式的 CSS 变量内容样式均已重命名为--ck-content-*前缀。涉及高亮、图片说明、提及、表格说明、图片样式间距、待办清单勾选标记等变量。完整对照如下旧变量名新变量名--ck-highlight-marker-yellow--ck-content-highlight-marker-yellow--ck-highlight-marker-green--ck-content-highlight-marker-green--ck-highlight-marker-pink--ck-content-highlight-marker-pink--ck-highlight-marker-blue--ck-content-highlight-marker-blue--ck-highlight-pen-red--ck-content-highlight-pen-red--ck-highlight-pen-green--ck-content-highlight-pen-green--ck-color-image-caption-background--ck-content-color-image-caption-background--ck-color-image-caption-text--ck-content-color-image-caption-text--ck-color-mention-background--ck-content-color-mention-background--ck-color-mention-text--ck-content-color-mention-text--ck-color-selector-caption-background⚠️ 新名称--ck-content-color-table-caption-background--ck-color-selector-caption-text⚠️ 新名称--ck-content-color-table-caption-text--ck-image-style-spacing--ck-content-image-style-spacing--ck-inline-image-style-spacing--ck-content-inline-image-style-spacing--ck-todo-list-checkmark-size--ck-content-todo-list-checkmark-size--ck-table-of-contents-padding--ck-content-table-of-contents-padding--ck-table-of-contents-line-height--ck-content-table-of-contents-line-height--ck-table-of-contents-items-start-padding--ck-content-table-of-contents-items-start-padding迁移请更新自定义样式表、主题与集成代码以使用新变量名旧变量名不再受支持设置后不会产生任何效果。示例:root { --ck-content-highlight-marker-yellow: #fdfd77; --ck-content-color-image-caption-background: hsl(0, 0%, 97%); }表格相关 CSS 变量重命名为-table-部分表格相关变量名称中的-selector-一词容易引起混淆、命名不一致现已统一改为-table-旧变量名新变量名--ck-color-selector-caption-highlighted-background--ck-color-table-caption-highlighted-background--ck-color-selector-column-resizer-hover--ck-color-table-column-resizer-hover--ck-color-selector-focused-cell-background--ck-color-table-focused-cell-background迁移更新自定义样式表与主题以使用新变量名旧名称不再受支持。示例:root { --ck-color-table-caption-highlighted-background: hsl(52deg 100% 50%); --ck-color-table-column-resizer-hover: var(--ck-color-base-active); --ck-color-table-focused-cell-background: hsla(212, 90%, 80%, .3); }列表相关变更多级列表标记结构变化为修复列表标记格式化问题多级列表Multi-level list功能的输出标记发生了变化。此变化没有视觉影响但可能触发某些自动化测试的断言失败。升级过程中无需迁移已有内容。变化前后对比!-- 之前 -- ol classmulti-level-list legal-list stylelist-style-type:none; li span classmulti-level-list__marker1. /spanFoo bar /li /ol !-- 之后 -- ol classmulti-level-list legal-list stylelist-style-type:none; li span classmulti-level-list__markerspan1./spannbsp;/spanFoo bar /li /ol从源码结构看这一变更涉及 packages/ckeditor5-list/src 中列表格式化list formatting相关的数据转换逻辑即标记文本被包进独立span并辅以nbsp;空格。列表项标识data-list-item-id编辑器数据中的li元素现在会带有一个data-list-item-id属性用于改进列表功能与其他编辑器功能的集成。该属性为列表项提供跨数据加载/保存保持稳定的标识解决了数据稳定性问题并提升了与外部系统及 diff 算法的兼容性。!-- 之前 -- ul li pFirst item/p pSecond paragraph/p /li liAnother item/li /ul !-- 之后 -- ul li>// 获取不含列表项 ID 的数据仅用于展示 const cleanHtml editor.getData( { skipListItemIds: true } );改进段落垂直间距在开发行高功能的过程中编辑器修复了一个长期存在的 bug列表与表格单元格中段落的间距行为。该修复通过自定义内容样式实现升级后可能带来可见的视觉变化。如果不满意可以通过以下 CSS 还原旧行为.ck-content li p:first-of-type { margin-top: revert; } .ck-content li p:only-of-type { margin-top: revert; margin-bottom: revert; } .ck-content table.table:not(.layout-table), .ck-content figure.table:not(.layout-table) table { thead, tbody { tr { td, th { p:first-of-type { margin-top: revert; } p:last-of-type { margin-bottom: revert; } } } } }评论Comments相关变更评论批注样式标准化评论批注的默认样式发生了显著变化。此前默认样式仅作用于部分评论 UI且评论 UI 会受主编辑器内容样式影响。现在引入了一组标准化的 CSS 变量同时作用于评论内容与输入框--ck-comment-content-font-family--ck-comment-content-font-size--ck-comment-content-font-color这些变量的默认值基于编辑器 UI 样式派生可能与当前设置不同。最明显的变化是默认字体颜色从黑色hsl(0, 0%, 0%)改为深灰色hsl(0, 0%, 20%)以与编辑器其余 UI 保持一致。迁移步骤升级编辑器后检查评论的外观若新默认样式不符合设计需求用新 CSS 变量设置自定义值:root { --ck-comment-content-font-family: Your preferred font family; --ck-comment-content-font-size: 14px; --ck-comment-content-font-color: hsl(0, 0%, 0%); /* 或你偏好的颜色 */ }新线程命令改进addCommandThread命令得到增强现在支持在指定范围range上创建评论线程也支持以给定的评论内容创建带初始评论的线程。次要破坏性变更AddCommandThreadCommand#isEnabled在文档选区为空时不再返回false因为命令现在支持在自定义范围上创建线程。如果你此前依赖该属性例如用于控制自定义 UI 元素应改用可观察属性AddCommentThreadCommand#hasContent。评论与建议批注的辅助方法v46 还引入了专门的方法用于更便捷地获取与某条评论或建议相关联的批注annotation以及反向的关联查询。安全修复CVE-2025-58064v46.0.3v46.0.3 于 2025 年 9 月 3 日发布修复了剪贴板包ckeditor5-clipboard中发现的跨站脚本XSS漏洞CVE-2025-58064。该漏洞可被特定的用户操作触发若攻击者成功向编辑器插入恶意内容可能在特定编辑器配置下发生将导致未经授权的 JavaScript 代码执行。该漏洞仅影响满足以下任一条件的编辑器配置启用了 HTML embed 插件启用了引入可编辑元素、且该元素实现了 view 层RawElement见 ckeditor5-engine 的引擎视图模型的自定义插件。如果使用以上配置请务必升级到 v46.0.3 或更高版本并参考相关安全公告了解详情。v46.0.1文档改版与分页能力增强v46.0.1 于 2025 年 8 月 11 日发布带来以下改进完整的文档重新设计新的文档主题提升了可读性修复了多处可访问性问题重新设计的导航栏更方便访问各产品文档分区改进的目录与搜索功能让查找指南更轻松。分页插件显著增强分页计算现在会考虑内容样式、书签标记并具备更好的容差计算分页还能为大型目录和高于页面的图片找到正确的分页断点。表格与分页、PDF 导出的配合分页与导出为 PDF 功能现在更好地支持包含一个或多个段落的表格导出表格时单元格边距被正确应用提升了分页渲染的精度。v46.0.2归档评论线程热修复v46.0.2 于 2025 年 8 月 19 日发布属于热修复版本修复了已归档的评论线程可能错误地出现在侧边栏中的问题确保归档线程始终正确地保留在评论归档中。v46.1.0稳定性与细节优化v46.1.0 于 2025 年 9 月 10 日发布是一个聚焦修复与 UX 改进的次要稳定版本iOS 上更流畅的拖拽更新了 iOS 触屏设备的拖放实现桌面端行为保持不变。分页改进回退了一项底层变更以提升分页稳定性尤其是包含长表格的场景。服务端编辑 API 支持隐藏用户服务端编辑器 API 现在支持hidden_in_presence_list用户标志可防止自动化脚本用户在脚本运行期间出现在编辑器的在线状态列表中。评论标记清理更好地处理标记指向不存在评论线程的边界情况例如因集成方失误造成此类标记现在会被自动移除以保持编辑器稳定。该版本的次要破坏性变更real-time-collaborationCloudServicesCommentsAdapter#getCommentThread在评论线程不存在时不再抛出错误而是返回null。v46.1.1开发基础设施现代化无 API 影响v46.1.1 于 2025 年 9 月 15 日发布是一个聚焦改进开发基础设施与发布流程的内部版本对集成方没有功能影响包管理从 Yarn Classic 迁移到pnpm带来更快的安装高效链接机制、更严格的依赖解析与更好的 peer dependency 处理以及消除跨项目重复包的磁盘效率提升引入依赖锁定机制提升构建过程的稳定性与可预测性确保开发环境与 CI/CD 管道环境一致。如果你 fork 了本仓库并基于源码开发需要按照仓库内开发环境指南见 docs/framework/contributing更新开发环境配置作为普通集成方本版本保持完全向后兼容无需任何改动。v46.0.0 破坏性变更汇总主要破坏性变更涉及包变更说明aiAI Assistant 默认模型从gpt-3.5-turbo升级为更先进的gpt-4o并移除了max_tokens的默认限制以支持更详细回复。若需沿用旧默认值请显式配置ai.openAi.requestParameters为{ model: gpt-3.5-turbo, max_tokens: 2000, stream: true }document-outline目录功能的内容区域 CSS 变量已重命名为--ck-content-*前缀覆盖过这些变量的集成需要更新list移除了列表项内的垂直间距重置li子元素p的边距table移除了表格单元格内的垂直间距折叠td/th中唯一子元素p的边距全部编辑器编辑器现在对编辑视图与渲染输出的文本内容强制应用浏览器默认样式可能影响现有样式与布局所有自定义 CSS 覆盖都应重新审查。新增--ck-content-font-familyHelvetica, Arial, Tahoma, Verdana, sans-serif、--ck-content-font-sizemedium、--ck-content-font-color#000十六进制以兼容邮件客户端、--ck-content-line-height1.5、--ck-content-word-breakbreak-word全部评论评论批注默认样式变更新增--ck-comment-content-font-family、--ck-comment-content-font-size、--ck-comment-content-font-color默认从hsl(0, 0%, 0%)改为hsl(0, 0%, 20%)需要审查升级后评论外观Highlight / Image / List / Table内容区域 CSS 变量重命名为--ck-content-*前缀Table名称不当的*-selector-*变量重命名为*-table-*次要破坏性变更涉及包变更说明commentsAddCommandThreadCommand#isEnabled在选区为空时不再为false改用可观察属性AddCommentThreadCommand#hasContentcore移除了已废弃的DataApiMixin函数与DataApi接口其功能已并入 Editor 类engine移除了已废弃的Batch#type属性list移除了DocumentList、DocumentListProperties、TodoDocumentList插件它们分别是List、ListProperties、DocumentList的别名markdown-gfm从marked/turndown迁移到remark/rehype提升可扩展性并融入现代 Markdown 生态同时启用了 Markdown 内容加载时的自动链接autolinking功能ui移除了FileDialogViewMixin创建按钮上的已废弃buttonView属性请直接使用按钮对象本身utils移除了已废弃的mix函数utils移除了已废弃的Locale#language属性请改用Locale#uiLanguage升级检查清单完成升级后建议按以下清单逐项核对确保迁移无遗漏依赖版本确认所有 CKEditor 5 相关包均为同一 v46.x 版本构建错误若出现does not provide an export named …对照 migrating-imports.md 更新所有导入名称内容外观检查编辑器内容区域的字体、行高、间距是否符合预期必要时覆盖--ck-content-*系列变量自定义样式全文搜索--ck-highlight-*、--ck-color-*、--ck-image-*、--ck-todo-list-*等旧变量名并替换为新名称列表与表格确认多级列表标记结构与data-list-item-id属性不会破坏你的数据处理或测试断言纯展示场景可用getData( { skipListItemIds: true } )评论/协作检查评论批注样式评估addCommandThread相关 UI 是否依赖isEnabled若依赖请改用hasContent安全若启用了 HTML embed 或自定义RawElement插件确认已升级到 v46.0.3 及以上版本AI 与云服务如需保持旧 AI 模型与 Token 行为显式配置ai.openAi.requestParameters与cloudServices.autoRefresh。完成以上核查后即可正常使用 CKEditor 5 v46.x 的完整能力并为后续版本迭代打下稳定的升级基础。【免费下载链接】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），仅供参考