CKEditor 4 Flash 插件弃用错误 `editor-plugin-deprecated` 的成因与手动测试验证指南
CKEditor 4 Flash 插件弃用错误 editor-plugin-deprecated 的成因与手动测试验证指南
CKEditor 4 自 4.17.0 版本起正式弃用并移除了 Flash 插件。仓库中的手动测试用例 tests/plugins/flash/manual/error.md 专门用来验证:当 Flash 插件被加载时,编辑器初始化流程会被主动中止,并在浏览器控制台输出错误码 editor-plugin-deprecated 与插件标识 { plugin: "flash" }。本文将围绕该手动测试用例,梳理其测试步骤、预期行为,并结合插件源码、核心日志机制与配套自动化测试,讲清这条错误信息从哪来、为什么出现、以及开发者应如何应对。
一、测试用例背景:Flash 插件为何被弃用
在 4.17.0 的版本记录 CHANGES.md 中明确写到:Adobe 已于 2020 年 12 月 31 日终止对 Flash Player 的支持,并从 2021 年 1 月 12 日起阻止 Flash 内容运行。为帮助保护用户系统安全、避免使用不安全的软件,CKEditor 团队决定弃用并移除 Flash 插件(对应 issue #4866)。
这一决定的直接体现就是:原本功能完整的 flash 插件被缩减为一个"占位"插件——它不再提供任何编辑能力,唯一的作用是在加载时报告自身已被弃用。因此,任何仍然在配置中引用 flash 插件的既有项目,升级到 4.17.0 及以后版本时都会立即在控制台看到该错误。
二、手动测试用例解读(文档主体)
手动测试文件 tests/plugins/flash/manual/error.md 的内容分为两部分:Bender 元数据声明与测试操作步骤。
1. Bender 元数据声明
@bender-tags: 4.17.0, feature, 4866
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, flash, basicstyles, link, undo
三行元数据各有含义:
@bender-tags: 4.17.0, feature, 4866:标记该测试关联的版本(4.17.0)、类型(feature,即验证新特性/行为)以及关联 issue 编号(4866);@bender-ui: collapsed:手动测试页面以折叠(collapsed)的编辑器 UI 呈现,聚焦于加载行为本身,而非完整的编辑界面;@bender-ckeditor-plugins: wysiwygarea, toolbar, flash, basicstyles, link, undo:测试页面加载的插件清单,其中flash正是本次验证的对象,其余插件用于模拟一个真实的编辑器配置环境。
2. 操作步骤与判定标准
操作步骤只有一步:打开浏览器控制台(Developer Tools → Console)。
预期结果(Expected):
编辑器加载过程被中止,并在控制台输出如下错误:
[CKEDITOR] Error code: editor-plugin-deprecated.
{ plugin: "flash" }
非预期结果(Unexpected):
- 编辑器被正常加载;
- 控制台没有错误,或输出了不同的错误信息。
判定逻辑非常直接:只要控制台里出现了 editor-plugin-deprecated 错误,就说明新版本的弃用机制生效;反之则说明行为回归,测试失败。
3. 测试页面本体
与 .md 配套的页面文件是 tests/plugins/flash/manual/error.html,其核心代码只有三处:
<div id="editor"></div>
<script>
if ( bender.tools.env.mobile ) {
bender.ignore();
}
CKEDITOR.replace( 'editor' );
</script>
其中 bender.tools.env.mobile 判断用于在移动端跳过测试(手动测试依赖桌面浏览器控制台),随后以 CKEDITOR.replace( 'editor' ) 创建一个绑定到 #editor 元素的经典(classic)编辑器实例——正是这个初始化动作触发了 Flash 插件的弃用错误。
三、源码级原理:错误是从哪里抛出的
1. 占位插件本身
打开 plugins/flash/plugin.js 可以看到,整个插件实现已缩减为:
CKEDITOR.plugins.add( 'flash', {
init: function() {
CKEDITOR.error( 'editor-plugin-deprecated', { plugin: 'flash' } );
}
} );
当插件管理器加载 flash 并调用其 init 方法时,CKEDITOR.error() 被立即调用。这与以往"插件正常初始化、提供命令与对话框"的行为截然不同——从源码结构看,4.17.0 之后该插件唯一的功能就是主动报告弃用。
2. 错误输出机制(核心日志框架)
CKEDITOR.error 定义在 core/log.js:
CKEDITOR.error = function( errorCode, additionalData ) {
if ( CKEDITOR.verbosity & CKEDITOR.VERBOSITY_ERROR ) {
CKEDITOR.fire( 'log', { type: 'error', errorCode: errorCode, additionalData: additionalData } );
}
};
完整链路如下:
- verbosity 开关:
CKEDITOR.verbosity是二进制标志位,默认值为CKEDITOR.VERBOSITY_WARN | CKEDITOR.VERBOSITY_ERROR(即1 | 2 = 3),两种级别的日志都会输出。开发者可通过CKEDITOR.verbosity = 0完全关闭控制台输出,或只保留 warn/error 其中之一; - log 事件:
CKEDITOR.error触发log事件,事件数据包含type(error)、errorCode(editor-plugin-deprecated)和additionalData({ plugin: 'flash' }); - 默认监听器:core/log.js 中注册的默认监听器将事件数据格式化为
[CKEDITOR] Error code: <errorCode>.,并把additionalData作为第二个参数传给console.error,最终得到测试用例中期望的输出:
[CKEDITOR] Error code: editor-plugin-deprecated.
{ plugin: "flash" }
同时默认监听器还会追加一行指向官方错误码文档的提示信息。开发者也可以自行注册 log 事件监听器并调用 evt.cancel() 来替换默认输出行为,实现自定义的日志上报(如接入前端监控)。
3. "编辑器加载被中止"的含义
Flash 插件不再提供任何实际能力,加载它不会让编辑器可用。结合 core/plugins.js 中插件加载流程(递归解析 requires 依赖、依次调用 onLoad 与 init),可以推断:手动测试中"编辑器加载过程被中止"是对"编辑器无法以含 flash 插件的配置正常初始化"这一事实的可观测描述——页面上的 #editor 区域不会出现可用编辑界面,控制台则留下唯一的弃用证据。
四、配套自动化测试:同一行为的一键验证
除了手动测试,仓库还提供了对应的 Bender 自动化测试 tests/plugins/flash/error.js,用 sinon spy 断言完全相同的错误输出:
bender.test( {
'test create editor with deprecated flash plugin': function() {
var spy = sinon.spy( CKEDITOR, 'error' );
bender.editorBot.create( {
name: 'editor'
}, function() {
spy.restore();
assert.areSame( 1, spy.callCount, 'Error was thrown' );
assert.isTrue( spy.calledWith( 'editor-plugin-deprecated' ), 'The error code is invalid' );
assert.isTrue( spy.calledWithExactly( 'editor-plugin-deprecated', sinon.match( {
plugin: 'flash'
} ) ), 'Appropriate error code and additional data should be used' );
} );
}
} );
该测试验证三点:CKEDITOR.error 被恰好调用一次、错误码为 editor-plugin-deprecated、附加数据包含 plugin: 'flash'。它与手动测试互为印证——手动测试负责在真实浏览器控制台里给出直观可见的证据,自动化测试则把同一行为固化进回归测试套件。
项目根目录的 bender.js 与 bender-runner.config.json 定义了 Bender 测试框架的加载方式与运行配置;运行该类测试需要本地安装 Bender 测试环境,具体命令可参考仓库 README 中关于测试的说明。
五、遗留的弃用配置项
虽然插件被移除,plugins/flash/plugin.js 仍保留了三个标记为 @deprecated 4.17.0 的配置项,供需要读取旧配置的升级场景参考:
| 配置项 | 默认值 | 原含义 |
|---|---|---|
config.flashEmbedTagOnly |
false |
仅保存为不推荐的 <embed> 标签 |
config.flashAddEmbedTag |
true |
在 <object><embed></embed></object> 中附加 <embed> 标签作为替代 |
config.flashConvertOnEdit |
false |
编辑时是否依据上述两项配置进行转换 |
注意:这些选项已不再产生任何实际效果,保留它们纯粹是为了兼容旧配置的解析。
六、开发者应对建议
- 移除 flash 插件引用:检查
config.extraPlugins、config.removePlugins及构建配置,删除flash,这是消除该错误最直接的方式; - 替换内容方案:若存量内容中包含
<object>/<embed>形式的 Flash 嵌入,Flash 技术本身已随浏览器支持终止而不可用,需替换为现代替代方案——本仓库中的 embed / embedsemantic 插件可承载 iframe 嵌入内容; - 监听并自定义日志:如需在应用内捕获该错误做统计或告警,可基于
CKEDITOR.on( 'log', ... )自定义处理(参考 core/log.js 的示例); - 配合测试验证:升级后运行 tests/plugins/flash/error.js 自动化测试与 tests/plugins/flash/manual/error.html 手动测试,确认弃用行为符合预期;反之,若你的应用需要彻底确认 flash 已被移除,该用例同样可作为判定标准。
七、小结
editor-plugin-deprecated 是 CKEditor 4.17.0 为已弃用插件设计的标准错误码。通过 tests/plugins/flash/manual/error.md 这一个简洁的手动测试用例,开发者可以在真实浏览器中快速验证弃用机制是否生效;结合 plugins/flash/plugin.js、core/log.js 与自动化测试 tests/plugins/flash/error.js,即可完整理解该错误从插件 init 触发、经 log 事件格式化、最终输出到控制台的整条链路,并据此完成旧项目的升级清理工作。