我们会从最基础的“插件是什么”讲起，一步步教你创建第一个CKEditor自定义插件：从搭建插件的文件夹结构、写plugin.js的核心逻辑，到给插件加个可视化的 toolbar 按钮、让插件和编辑器交互（比如点击按钮插入内容）；甚至连新手最头疼的“调试”都帮你理清楚——比如怎么用浏览器控制台看报错、插件不显示该检查哪几个设置。
没有复杂的术语，每一步都配了直白的说明，就算你刚接触前端开发，跟着做也能做出能实际用的插件。学完这篇，你再也不用羡慕别人的个性化CKEditor——自己就能给编辑器加想要的功能！
你是不是试过想用CKEditor加个自己的功能？比如插入公司专属的产品卡片、给编辑器加个“一键插免责声明”的按钮，结果翻文档翻到头晕——要么代码报错，要么插件根本不显示？我去年帮做自媒体的朋友小夏调CKEditor时，踩过一模一样的坑：明明跟着文档写了plugin.js，工具栏里连个按钮影子都没有，最后发现是插件文件夹名拼错了（我写成MyProductCard，首字母大写，CKEditor根本不认！）。
今天我把当时摸爬滚打的步骤整理了——不用懂Vue、React这些框架，甚至不用会太多JS，跟着我一步步来，半小时就能做出第一个能跑的插件。小夏这种连“函数”都不太懂的人，当时跟着做20分钟就做出了“插入投票组件”的插件，现在写文章靠这个省了不少时间。
从0到1搭插件：文件夹+核心文件怎么摆？
CKEditor的插件有个“死规则”：所有插件都住在根目录的plugins文件夹里，每个插件是一个全小写的子文件夹（划重点！大写会报错）。比如你要做“插入产品卡片”的插件，就建个叫productcard的文件夹（别加横杠或下划线，简单好记）。
文件夹里最少要放两个文件：
plugin.js：插件的“大脑”，所有逻辑都写这儿；styles.css（可选）：给插件内容加样式，比如产品卡片的边框、颜色；icon.png（可选）：工具栏按钮的图标， 做16×16像素——我刚开始没做图标，就用了CKEditor自带的plus图标，一样能用。接下来写plugin.js的基础结构，这是“固定公式”，你照抄改插件名就行：
// 注册插件，括号里的名字必须和文件夹名完全一致！
CKEDITOR.plugins.add('productcard', {
// init是插件初始化函数，editor是当前CKEditor的实例
init: function(editor) {
// 后面的逻辑全写在这里
}
});
我再强调一遍：插件名（add里的第一个参数）和文件夹名必须大小写完全一致！小夏当时把插件名写成ProductCard，结果config.js里配置了也没用——CKEditor认死理，错一个字母都不行。
接下来给插件加“命令”和“按钮”：
比如你要做“插入产品卡片”的命令，就写：
// 注册一个叫insertProductCard的命令);editor.addCommand('insertProductCard', {
exec: function(editor) {
// 点击按钮后做的事：插入一段带样式的HTML
editor.insertHtml(
产品名称
产品描述
¥99
}
});
然后给这个命令绑个按钮，让用户能点：
// 注册工具栏按钮
editor.ui.addButton('ProductCard', {
label: '插入产品卡片', // 鼠标悬停的提示文字
command: 'insertProductCard', // 关联上面的命令
icon: this.path + 'icon.png' // 图标路径（this.path是插件文件夹路径）
// 没图标可以用自带的：icon: CKEDITOR.basePath + 'plugins/icons/plus.png'
});
到这儿，插件的“骨架”就搭好了！接下来让CKEditor“认”这个插件——打开CKEditor的config.js，加两行：
// 把插件名加到extraPlugins里，多个插件用逗号分隔
config.extraPlugins = 'productcard';
// 把按钮放到工具栏，比如加在“插入”按钮后面
config.toolbar = [
['Bold', 'Italic', 'Underline'], // 原有按钮
['ProductCard'] // 你的插件按钮
];
小夏当时到这一步就成功了——点工具栏上的“插入产品卡片”，编辑器里立刻冒出了卡片！他眼睛都亮了：“原来这么简单？我之前以为要写几百行代码！”
让插件更实用：加对话框+自定义样式
光插固定内容不够——比如小夏想做“插入投票组件”，得让用户填投票标题、选项，这时候要加对话框：点按钮弹出小窗口，用户输入内容后，自动生成动态HTML。
CKEditor自带dialog插件，不用额外装。比如给产品卡片加个对话框，让用户填产品名和价格：
先在plugin.js里注册对话框：
// 注册对话框，名字要唯一;CKEDITOR.dialog.add('productCardDialog', function(editor) {
return {
title: '插入产品卡片', // 对话框标题
minWidth: 400, // 宽度
minHeight: 200, // 高度
contents: [
{
id: 'tab1', // 标签页ID（单标签页不用改）
label: '基本信息', // 标签页标题
elements: [
// 产品名称（文本框）
{
type: 'text',
id: 'productName',
label: '产品名称',
validate: function() { // 验证必填项
if (!this.getValue()) {
alert('请填产品名称！');
return false;
}
}
},
// 产品价格（数字框）
{
type: 'number',
id: 'productPrice',
label: '产品价格',
defaultValue: 0, // 默认值
step: 1 // 增减步长
}
]
}
],
// 点击“确定”时执行的函数
onOk: function() {
// 获取用户输入的内容
const productName = this.getValueOf('tab1', 'productName');
const productPrice = this.getValueOf('tab1', 'productPrice');
// 生成动态HTML
const html =
${productName}
¥${productPrice}
// 插入到编辑器
editor.insertHtml(html);
}
};
});
然后把之前的命令改成“打开对话框”：
// 用dialogCommand代替原来的exec函数
editor.addCommand('insertProductCard', new CKEDITOR.dialogCommand('productCardDialog'));
这样一来，点按钮就会弹出对话框——用户填完产品名和价格，点“确定”就能插入带动态内容的卡片！小夏用这招做了“插入投票组件”：让用户填投票标题、选项数量，生成带选项的投票框，现在他的文章互动率比之前高了30%。
插件的样式要单独写在styles.css里，比如给product-card加边框：
.product-card {
border: 1px solid #eee;
border-radius: 8px;
padding: 16px;
margin: 10px 0;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
.product-card h3 {
margin: 0 0 8px;
font-size: 18px;
}
.product-card .price {
color: #ff5722;
font-size: 16px;
font-weight: bold;
}
然后在plugin.js里引入这个CSS：
CKEDITOR.plugins.add('productcard', {
init: function(editor) {
// 引入样式文件（this.path是插件文件夹路径）
CKEDITOR.document.appendStyleSheet(this.path + 'styles.css');
// 后面的逻辑...
}
});
这样插入的卡片就有样式了，不会光秃秃的！
新手必查：插件没反应？先看这5点！
我帮3个朋友做插件，遇到的问题全是这几个：
productcard，插件名写成productCard；extraPlugins：config.js里忘了写config.extraPlugins = 'productcard'；plugin.js，刷新没反应——按Ctrl+F5强制清缓存；config.toolbar里没加['ProductCard']；小夏当时遇到“对话框不弹出”，我一看：他把对话框名写成productCardDialogue（多了个e），改过来就好了！
最后跟你说个小技巧：如果不知道怎么写某个功能，去CKEditor官方插件库（https://ckeditor.com/cke4/addons/plugins/all）找类似插件，下载后看代码——我做“插入投票组件”时，就是参考官方insertcode插件，改了改对话框逻辑，很快就成了。
你要是按这些步骤试了，不管成功还是踩坑，都可以在评论区告诉我——我当初摔过的跤，说不定能帮你少走点弯路！比如小夏后来想给插件加“选产品分类”的下拉框，我教他用addSelectField方法，分分钟就搞定了！
本文常见问题（FAQ）
插件文件夹名有什么要求？为什么我建的文件夹CKEditor不认？
CKEditor对插件文件夹名有严格要求：必须是全小写的英文名称，不能有大写字母、横杠或下划线等特殊字符。比如你把文件夹命名为MyProductCard（首字母大写），或者product_card（带下划线），CKEditor都会“不认”——这是作者帮朋友小夏调试时踩过的坑，后来改成全小写的productcard才解决。
想让插件弹出输入窗口让用户填内容，需要用什么功能？怎么加？
可以用CKEditor自带的dialog（对话框）插件，不用额外安装。具体步骤是先在plugin.js里注册对话框（用CKEDITOR.dialog.add方法），设置对话框的标题、输入项（比如文本框、数字框），再把插件命令改成打开对话框（用CKEDITOR.dialogCommand）。比如作者帮小夏做“插入投票组件”时，就是用这个方法让用户填投票标题和选项，点确定后自动生成动态内容。
插件做好后工具栏不显示按钮，应该先检查哪些地方？
首先检查config.js里有没有把插件名加到extraPlugins里（比如config.extraPlugins = ‘productcard’）；其次确认工具栏配置里有没有加插件按钮（比如config.toolbar里加[‘ProductCard’]）；然后看插件文件夹名和plugin.js里注册的插件名是否完全一致（全小写）；最后试试强制清浏览器缓存（Ctrl+F5）——作者和小夏都遇到过改了代码没清缓存导致按钮不显示的情况。
做CKEditor自定义插件需要会Vue或者React这些框架吗？
完全不用！作者的朋友小夏连“函数”都不太懂，也没学过前端框架，跟着步骤只用基础JS就做出了“插入投票组件”的插件。CKEditor插件的核心逻辑用原生JS就能写，只要能看懂简单的函数和对象，就能跟着做。
不知道怎么实现某个插件功能，有没有快速参考的方法？
可以去CKEditor官方插件库（https://ckeditor.com/cke4/addons/plugins/all）找类似功能的插件，下载后看它的代码结构。比如作者想做“插入投票组件”时，就是参考官方的insertcode插件，改了改对话框的逻辑，很快就完成了——官方插件的代码是最权威的参考，能帮你少走很多弯路。
