CKEditor 4 Flash 插件弃用错误 `editor-plugin-deprecated` 的成因与手动测试验证指南

原创2026-10-15 10:10:121,635 阅读
文章标签:前端UI组件

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 } );
	}
};

完整链路如下:

  1. verbosity 开关:CKEDITOR.verbosity 是二进制标志位,默认值为 CKEDITOR.VERBOSITY_WARN | CKEDITOR.VERBOSITY_ERROR(即 1 | 2 = 3),两种级别的日志都会输出。开发者可通过 CKEDITOR.verbosity = 0 完全关闭控制台输出,或只保留 warn/error 其中之一;
  2. log 事件:CKEDITOR.error 触发 log 事件,事件数据包含 type(error)、errorCode(editor-plugin-deprecated)和 additionalData({ plugin: 'flash' });
  3. 默认监听器: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 编辑时是否依据上述两项配置进行转换

注意:这些选项已不再产生任何实际效果,保留它们纯粹是为了兼容旧配置的解析。

六、开发者应对建议

  1. 移除 flash 插件引用:检查 config.extraPlugins、config.removePlugins 及构建配置,删除 flash,这是消除该错误最直接的方式;
  2. 替换内容方案:若存量内容中包含 <object>/<embed> 形式的 Flash 嵌入,Flash 技术本身已随浏览器支持终止而不可用,需替换为现代替代方案——本仓库中的 embed / embedsemantic 插件可承载 iframe 嵌入内容;
  3. 监听并自定义日志:如需在应用内捕获该错误做统计或告警,可基于 CKEDITOR.on( 'log', ... ) 自定义处理(参考 core/log.js 的示例);
  4. 配合测试验证:升级后运行 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 事件格式化、最终输出到控制台的整条链路,并据此完成旧项目的升级清理工作。

登录后查看全文
ckeditor4