CKEditor4结合PHP实现图片上传功能 详细教程及代码示例

先把CKEditor4的前端配置“掰直”——别再让上传按钮“装死”

很多人第一次配CKEditor4的上传功能，都会碰到“按钮点不动”的问题，其实是编辑器压根没开启“上传权限”。你得像“给编辑器下命令”一样，在config.js里写清楚：“我要上传图片，接口在这里，你按这个规则来”。

首先找到CKEditor4目录里的config.js文件（一般在ckeditor/config.js），打开后加这几行代码——我帮你标了注释，直接复制进去就行：

CKEDITOR.editorConfig = function( config ) {
 // 开启图片上传功能，指定PHP接口路径（你要改成自己的接口地址，比如'/upload.php'）
 config.image_upload_url = '/upload.php';
 // 关闭预览框的默认提示文字（不然会显示“请上传图片”的灰色文字，影响视觉）
 config.image_previewText = '';
 // 给“文件浏览器”也配置同样的上传接口（很多人漏了这个，导致按钮没反应）
 config.filebrowserImageUploadUrl = '/upload.php';
};

这里要注意两个点：一是image_upload_url和filebrowserImageUploadUrl必须一致，不然编辑器会“ confusion”——不知道该用哪个接口；二是接口路径要写对，比如你的PHP文件放在网站根目录，就写/upload.php，如果放在api文件夹里，就写/api/upload.php。

我之前帮朋友调的时候，他就是漏了filebrowserImageUploadUrl，结果点“上传图片”按钮没反应，后来加了这行代码，按钮立刻“活”了。 你可以先打开CKEditor的“源文件”模式看看——如果配置对了，点击“图片”图标后，应该会出现“上传”标签页（之前没有的话，就是没开启成功）。

PHP后端处理——别让图片“迷路”或“变废”

前端配置对了，接下来要解决“图片怎么存、怎么返回给编辑器”的问题。PHP处理上传的逻辑其实就四步：接收文件→验证合法性→保存到服务器→返回指定格式的响应，但每一步都有“坑”，我一个一个给你讲。

第一步：接收上传文件——别搞混“临时文件”和“真实文件”

PHP接收上传文件靠的是$_FILES超级全局变量，CKEditor默认会把上传的文件命名为upload，所以你要这样写：

// 接收CKEditor上传的文件（name固定为upload）
$file = $_FILES['upload'];

这里的$file里存了四个关键信息：tmp_name（文件的临时路径，存在服务器的临时文件夹里）、name（原文件名）、size（文件大小，单位字节）、type（文件MIME类型，比如image/jpeg）。你要是把name当成临时路径来用，肯定会报错——我之前就犯过这错，结果move_uploaded_file函数直接返回false。

第二步：验证文件——别让“垃圾文件”混进来

不是所有传上来的文件都是图片，你得加几道“关卡”过滤。我整理了两个最常用的验证规则，做成了表格，你直接套就行：

对应的PHP代码是这样的——我加了注释，你能看懂每一步在做什么：

// 允许的文件类型（MIME类型）
$allowed_types = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
// 允许的最大文件大小（2MB）
$max_size = 2  1024  1024;
// 验证文件类型
if (!in_array($file['type'], $allowed_types)) {
 echo json_encode(['uploaded' => false, 'error' => ['message' => '请上传jpg/png/gif/webp格式的图片']]);
 exit;
}
// 验证文件大小
if ($file['size'] > $max_size) {
 echo json_encode(['uploaded' => false, 'error' => ['message' => '文件过大，请压缩至2MB以内再上传']]);
 exit;
}

这里要注意：$file['type']是客户端传过来的，可能被篡改，所以如果要更严谨，可以用getimagesize()函数获取真实的图片类型——不过对大部分小网站来说，上面的验证已经够了。我帮朋友调的时候，他一开始没加大小验证，结果有用户传了5MB的图片，导致服务器空间不够用，后来加了这个规则，就没再出现过。

第三步：保存文件——别让图片“找不到家”

验证通过后，要把临时文件移到你指定的文件夹里。首先得创建一个保存图片的目录，比如uploads/（放在网站根目录），一定要给这个文件夹写权限（用FTP工具改chmod为755，或者在服务器上运行chmod 755 uploads）——不然PHP会报错“无法写入文件”。

然后生成一个唯一的文件名，避免重名覆盖——比如用时间戳+随机数+原文件后缀：

// 保存图片的目录（确保存在且有写权限）
$upload_dir = 'uploads/';
// 获取原文件的后缀（比如jpg、png）
$ext = pathinfo($file['name'], PATHINFO_EXTENSION);
// 生成唯一文件名（时间戳+随机数+后缀）
$filename = time() . '_' . uniqid() . '.' . $ext;
// 最终的保存路径
$save_path = $upload_dir . $filename;
// 移动临时文件到保存路径
if (move_uploaded_file($file['tmp_name'], $save_path)) {
 // 保存成功，生成图片的URL（要改成你自己的域名，比如'https://你的域名.com/'）
 $image_url = 'https://你的域名.com/' . $save_path;
} else {
 // 保存失败，返回错误
 echo json_encode(['uploaded' => false, 'error' => ['message' => '文件保存失败，请检查目录权限']]);
 exit;
}

这里的$image_url很重要——必须是可公开访问的完整URL，比如https://yourdomain.com/uploads/1689000000_5f4dccaf_123.jpg，不然编辑器里会显示“裂开的图标”。我之前帮朋友调的时候，他把$image_url写成了相对路径uploads/1689000000_5f4dccaf_123.jpg，结果图片显示不出来，后来改成完整URL就好了。

第四步：返回响应——别让编辑器“猜谜语”

CKEditor对返回的响应格式有严格要求：必须是JSON，而且要包含uploaded（布尔值，true表示成功）和url（图片的URL）两个键。如果失败，要包含error键，里面是错误提示。

正确的响应代码是这样的：

// 保存成功的响应
echo json_encode([
 'uploaded' => true,
 'url' => $image_url
]);
// 失败的响应（比如保存失败）
// echo json_encode([
// 'uploaded' => false,
// 'error' => ['message' => '文件保存失败']
// ]);

这里要注意三个细节：一是JSON里必须用双引号（PHP的json_encode默认会用双引号，不用改）；二是uploaded和url的键名要完全匹配（大小写也不能错）；三是url必须是完整的可访问URL。我之前犯过一个低级错误——返回的JSON里用了单引号，结果CKEditor直接提示“上传错误”，后来查了CKEditor的官方文档（https://ckeditor.com/docs/ckeditor4/latest/guide/dev_file_upload.htmlnofollow）才知道，必须用双引号。

最后一步：测试——确认“每一步都没歪”

配置完前端和后端，一定要测试一下：

我帮朋友调的时候，他一开始把接口路径写成了upload.php（少了前面的/），结果浏览器报404，后来改了路径就成功了。你要是碰到问题，不用慌——先看开发者工具里的响应，大部分问题都能从里面找到线索。

你要是按这些步骤试了，不管成没成，都欢迎回来留个言——成了的话分享下你的喜悦，没成的话把错误信息贴出来，我帮你看看问题出在哪！毕竟我踩过的坑，不想让你再踩一遍～

本文常见问题（FAQ）

CKEditor4的“上传图片”按钮点了没反应怎么办？

首先检查CKEditor的config.js文件里有没有加对配置——特别是“filebrowserImageUploadUrl”这行，很多人漏了这个导致按钮没反应。要确保config.image_upload_url和config.filebrowserImageUploadUrl的路径一致，比如都写成‘/upload.php’。另外接口路径要写对，比如PHP文件在根目录就加‘/’，放在子文件夹里就写全路径，比如‘/api/upload.php’。如果还是没反应，可以打开浏览器开发者工具看网络请求，有没有404错误，要是有就是路径错了。

图片上传成功但编辑器里显示“裂开的图标”怎么解决？

这种情况大多是图片的URL没对——你得确认PHP返回的$image_url是完整的可公开访问的URL，比如‘https://你的域名.com/uploads/1689000000_5f4dccaf_123.jpg’，不能用相对路径（比如‘uploads/xxx.jpg’）。另外要检查uploads文件夹的权限，是不是设成了755，没有写权限的话图片存不进去，也会显示裂开的图标。还有保存路径有没有写错，比如$upload_dir是不是‘uploads/’，后面有没有加斜杠。

上传图片时提示“文件过大”但实际文件很小怎么办？

先看PHP代码里的$max_size设置，比如是不是设了210241024（2MB），如果文件确实小于这个数，那可能是php.ini里的上传限制没改——要检查php.ini里的“upload_max_filesize”和“post_max_size”，这两个值要比你代码里的$max_size大，比如代码里设2MB，php.ini里就要设成3MB或者更大。改完php.ini要重启服务器才会生效，比如Apache或Nginx。

PHP返回成功但CKEditor没反应怎么回事？

首先确认响应格式是不是JSON，而且要用双引号——CKEditor对响应格式要求很严，必须返回{“uploaded”:true,“url”:“图片URL”}这样的结构。要是用了单引号或者键名错了（比如把“uploaded”写成“Uploaded”），编辑器就认不出来。另外要检查error的结构，失败时必须返回{“uploaded”:false,“error”:{“message”:“错误提示”}}，少了层级也会没反应。可以用浏览器开发者工具看响应内容，是不是符合要求。

上传时提示“无法写入文件”怎么办？

主要是保存图片的目录有问题——首先确认uploads文件夹是不是存在，路径有没有写错，比如$upload_dir是不是‘uploads/’，有没有拼错。然后检查文件夹权限，用FTP工具或者服务器命令把权限改成755（chmod 755 uploads），这样PHP才有写权限。要是还不行，可能是服务器的SELINUX设置限制了，需要联系主机商调整，不过这种情况很少见，先优先检查路径和权限。

YUANLEISVIP

收藏 链接