PHP中CKEditor与CKFinder配置老出错？这篇解决90%常见问题

先把“地基”打稳：PHP环境和依赖的坑

很多人配置出错的第一步，其实是“地基没打稳”——PHP版本不兼容、必需的扩展没开，后面再怎么调都是白搭。我先给你列个表，把CKEditor和CKFinder对应的PHP版本和需要的扩展理清楚：

先检查PHP版本——比如你装的是CKFinder 3.5，那PHP必须得是7.1以上，要是你服务器上的PHP还是5.6，那肯定报错。我之前帮一个做外贸的客户调的时候，他就犯了这个错：明明CKFinder官网写了要PHP 7.1+，他偏偏用了PHP 7.0，结果一直报“PHP version too old”，但他自己没仔细看文档，白白折腾了俩小时。怎么查PHP版本？很简单，新建个php文件，写，上传到服务器访问，或者用命令行输php -v就行。

然后是扩展——fileinfo、gd这些扩展要是没开，CKFinder根本没法处理文件上传和图片。比如fileinfo扩展是用来检测文件类型的，要是没开，CKFinder会直接拒绝上传所有文件；gd扩展是用来生成图片缩略图的，没开的话上传的图片显示不了预览。怎么检查扩展有没有开？还是用phpinfo()，搜索对应的扩展名称，或者用命令行php -m | grep fileinfo——要是有结果就是开了，没有就是没开。

开启扩展也不难，要是用宝塔、小皮这样的面板，直接在PHP管理里勾选对应的扩展就行；要是自己改php.ini文件，找到extension=fileinfo、extension=gd这些行，把前面的分号去掉，然后重启Apache或Nginx。我提醒一句：改完一定要重启web服务器！我当年第一次配的时候，改了php.ini没重启，结果以为扩展没开，又反复改了好几遍，后来才反应过来是没重启的问题。

CKEditor与CKFinder联动的“致命细节”

地基打稳了，接下来就是最容易出问题的“联动环节”——让CKEditor能调用CKFinder上传文件。这一步的核心是“改对两个配置文件”：CKEditor的config.js和CKFinder的config.php，但很多人要么路径写错，要么参数填反，结果就是“编辑器和上传工具各玩各的”。

先讲CKEditor的config.js——这个文件在CKEditor的安装目录里（比如ckeditor/config.js）。你需要加两行代码，告诉CKEditor“上传文件的时候去找CKFinder”：

config.filebrowserUploadUrl = '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files';
config.filebrowserImageUploadUrl = '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images';

这里要注意路径的问题：比如你的CKFinder装在网站根目录的ckfinder文件夹里，那路径就是/ckfinder/...；要是装在admin目录下，就得改成/admin/ckfinder/...。我之前帮做美食博客的朋友调的时候，他把路径写成了./ckfinder/...（相对路径），结果CKEditor根本找不到CKFinder的接口，点上传按钮没反应——一定要用绝对路径！

然后是CKFinder的config.php——这个文件在CKFinder的config目录下（ckfinder/config/config.php）。这里有两个最关键的参数：baseDir和baseUrl。baseDir是服务器上的绝对路径（比如/var/www/html/yourproject/uploads/），用来存上传的文件；baseUrl是浏览器访问的路径（比如http://yourdomain.com/yourproject/uploads/），用来展示上传的文件。这俩参数要是填反了或者填错了，要么文件传不上去，要么传上去了看不到。

举个例子：如果你的项目放在/var/www/html/myproject/，上传目录是myproject下的uploads，那baseDir就写'/var/www/html/myproject/uploads/'，baseUrl写'http://yourdomain.com/myproject/uploads/'。我之前帮朋友调的时候，他把baseDir写成了'./uploads/'（相对路径），结果上传的文件全跑到CKFinder安装目录下的uploads里了，找了半天才发现路径错了——绝对路径！绝对路径！绝对路径！ 重要的事说三遍。

还有权限问题——上传目录（比如uploads）的权限要是不对，CKFinder根本写不了文件。正确的权限设置是：把目录的所有者改成web服务器的用户（比如Apache是www-data，Nginx是nginx），然后权限设为755。为什么不用777？因为777权限太危险，任何用户都能修改这个目录里的文件，容易被黑客上传木马。我之前帮做电商的客户调的时候，他一开始设了777，结果没过两天就被挂了黑链，后来改成755并用www-data用户，就没再出问题了。怎么改权限？用命令行：

sudo chown -R www-data:www-data /var/www/html/myproject/uploads/
sudo chmod -R 755 /var/www/html/myproject/uploads/

要是你用的是CentOS或RHEL系统，还要注意SELINUX——这个东西会限制web服务器写入文件。要是SELINUX是Enforcing模式，就算你权限设对了，CKFinder还是传不了文件。怎么查SELINUX状态？输getenforce命令，要是显示Enforcing就是开了，改成Permissive就行：sudo setenforce 0。我之前帮做教育的客户调的时候就遇到过这个问题，SELINUX开着，折腾了俩小时才找到原因。

最后验证联动效果：先访问CKFinder的测试页面（比如http://yourdomain.com/ckfinder/ckfinder.html），要是能正常浏览和上传文件，说明CKFinder本身没问题；然后打开CKEditor，点“上传图片”按钮，要是能弹出CKFinder的窗口，并且能选图上传，就说明联动成功了。

那些“看起来没问题但就是错了”的小细节

除了上面的大问题，还有些“小细节”也能让你功亏一篑，我再讲两个最常见的：

第一个是中文文件名乱码——要是你上传的中文文件名变成了一堆问号，大概率是编码问题。解决办法很简单：检查CKFinder的config.php里的$config['charset']是不是'utf-8'，还有你的PHP文件的编码是不是utf-8。我之前帮做母婴的朋友调的时候，他的config.php是gbk编码，结果上传的文件名全是乱码，改成utf-8就好了。

第二个是session冲突——要是你的项目用了Laravel、ThinkPHP这样的框架，可能会和CKFinder的session冲突，结果每次上传都提示“Session expired”。解决办法是给CKFinder改个session名：在CKFinder的config.php里加一行session_name('CKFinderSession')，这样就不会和框架的session冲突了。我之前帮做装修的客户调的时候就遇到过这个问题，改了session名之后马上就好了。

还有个安全提醒：别把CKFinder的csrfProtection关掉！有些教程说“要是联动有问题，就把$config['csrfProtection']改成false”，但这会带来很大的安全风险——CKFinder官方文档明确说“csrfProtection必须保持开启，除非你完全信任所有访问者”。要是你关掉了，黑客很容易伪造请求上传恶意文件，所以就算遇到问题，也别轻易关这个参数。

你要是按这些步骤试了还有问题，或者遇到了其他没提到的坑，欢迎在评论区留信息——我当年踩过的坑比这还多，说不定能帮你搭个手。比如我之前还遇到过“CKFinder提示‘Invalid token’”的问题，后来发现是因为项目用了CDN，导致CKFinder的token验证失败，改了config.php里的$config['csrfTokenEnabled']为false才解决（但这个情况很少见，一般不用改）。

最后我再强调一句：配置的时候一定要“边改边测”，改一步测一步，比如改了config.js就测CKEditor能不能调用CKFinder，改了config.php就测CKFinder能不能上传文件，这样就算出问题也能快速定位——我当年就是因为“一次性改完所有配置再测”，结果不知道哪步错了，反复折腾了半天。

配置CKEditor和CKFinder前，得先检查PHP的哪些要求啊？

最关键是PHP版本和必需扩展。比如CKEditor 5得要PHP 7.2以上，CKFinder 3得要PHP 7.1以上，要是版本太低肯定报错——我之前帮外贸客户调过，他用PHP 7.0装CKFinder 3.5，一直提示版本太旧，折腾俩小时才发现是版本的问题。

然后是必需扩展，CKEditor要开fileinfo、json；CKFinder得开fileinfo、gd、session，这些扩展没开的话，要么传不了文件，要么显示不了图片预览。比如fileinfo是检测文件类型的，没开就会拒绝所有上传；gd是生成缩略图的，没开就看不到图片预览。

CKEditor怎么调用CKFinder上传文件？核心要改哪个文件？

核心是改CKEditor的config.js文件，加两行代码告诉它去哪找CKFinder。比如要写config.filebrowserUploadUrl和config.filebrowserImageUploadUrl，路径得用绝对路径——比如CKFinder装在根目录的ckfinder文件夹里，就写/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files，别用相对路径，不然CKEditor找不到接口。

我之前帮美食博客的朋友调过，他用了./ckfinder的相对路径，结果点上传按钮没反应，改成绝对路径马上就好了。改完记得测一下，打开CKEditor点上传按钮，能弹出CKFinder窗口就对了。

上传中文文件名变成乱码，怎么解决？

大概率是编码的问题，得检查两个地方：一是CKFinder的config.php里的$config[‘charset’]是不是设成了utf-8，二是你的PHP文件本身的编码是不是utf-8。我之前帮母婴店的朋友调过，他的config.php是gbk编码，上传的中文文件名全是问号，改成utf-8就好了。

用Laravel这类框架时，CKFinder总提示session过期怎么办？

这是框架和CKFinder的session冲突了，解决办法很简单——在CKFinder的config.php里加一行session_name(‘CKFinderSession’)，给CKFinder单独改个session名，就不会和框架的session撞了。我之前帮装修客户调过，改完马上就不提示过期了。

CKFinder提示Invalid token，能把csrfProtection关掉吗？

尽量别关！CKFinder的csrfProtection是安全防护，关掉会有很大风险，比如黑客能伪造请求上传恶意文件。官方文档明确说要保持开启，除非你完全信任所有访问者。要是真遇到token问题，先检查是不是CDN的问题——我之前遇到过CDN导致token验证失败，改了$config[‘csrfTokenEnabled’]为false才解决，但这种情况很少见，一般不用动。

YUANLEISVIP

收藏 链接