PHP 整合 CKEditor + CKFinder 實現圖片上傳功能完整教學

CKEditor 4 + CKFinder 3 整合指南：從安裝到圖片上傳完整流程

CKEditor 是功能強大的所見即所得編輯器，但預設不含圖片上傳功能，需搭配官方檔案管理器 CKFinder。本文詳述 PHP 環境下的安裝、配置、權限控管與前後端整合步驟。

一、目錄結構規劃

/project-root/
├── admin/
│   ├── ckeditor/          # CKEditor 核心
│   │   ├── ckeditor.js
│   │   ├── config.js
│   │   ├── styles.js
│   │   └── plugins/...
│   ├── ckfinder/          # CKFinder 核心 (與 ckeditor 同級)
│   │   ├── ckfinder.php
│   │   ├── config.php
│   │   ├── core/connector/php/connector.php
│   │   └── userfiles/     # 上傳檔案儲存目錄 (需寫入權限)
│   └── edit.php           # 使用編輯器的頁面
└── public/                # 公開可存取目錄
    └── uploads/           # 實際對外可訪問的上傳目錄 (符號連結或實體目錄)

二、CKEditor 安裝與基礎配置

1. 下載與部署

• 官網下載 CKEditor 4 Standard Package
• 解壓至 /admin/ckeditor/

2. 基礎配置 (config.js)

// /admin/ckeditor/config.js
CKEDITOR.editorConfig = function(config) {
    config.language = 'zh-cn';        // 介面語言
    config.uiColor = '#F7F7F7';       // 工具列顏色
    config.height = 400;              // 編輯區高度
    config.toolbar = 'Full';          // 工具列組合
    config.toolbar_Full = [
        { name: 'document', items: ['Source', '-', 'Save', 'NewPage', 'Preview', 'Print', '-', 'Templates'] },
        { name: 'clipboard', items: ['Cut', 'Copy', 'Paste', 'PasteText', 'PasteFromWord', '-', 'Undo', 'Redo'] },
        { name: 'editing', items: ['Find', 'Replace', '-', 'SelectAll'] },
        { name: 'forms', items: ['Form', 'Checkbox', 'Radio', 'TextField', 'Textarea', 'Select', 'Button', 'ImageButton', 'HiddenField'] },
        '/',
        { name: 'basicstyles', items: ['Bold', 'Italic', 'Underline', 'Strike', 'Subscript', 'Superscript', '-', 'RemoveFormat'] },
        { name: 'paragraph', items: ['NumberedList', 'BulletedList', '-', 'Outdent', 'Indent', '-', 'Blockquote', 'CreateDiv', '-', 'JustifyLeft', 'JustifyCenter', 'JustifyRight', 'JustifyBlock', '-', 'BidiLtr', 'BidiRtl'] },
        { name: 'links', items: ['Link', 'Unlink', 'Anchor'] },
        { name: 'insert', items: ['Image', 'Flash', 'Table', 'HorizontalRule', 'Smiley', 'SpecialChar', 'PageBreak', 'Iframe'] },
        '/',
        { name: 'styles', items: ['Styles', 'Format', 'Font', 'FontSize'] },
        { name: 'colors', items: ['TextColor', 'BGColor'] },
        { name: 'tools', items: ['Maximize', 'ShowBlocks'] },
        { name: 'about', items: ['About'] }
    ];
};

三、CKFinder 安裝與配置 (關鍵步驟)

1. 下載與部署

• 官網下載 CKFinder 3 PHP 版
• 解壓至 /admin/ckfinder/ (與 ckeditor 同級)

2. 核心配置 (config.php) - 必須修改

<?php
// /admin/ckfinder/config.php
$config = [];

// 【安全關鍵】認證函式：必須返回 true 才允許上傳/瀏覽
$config['authentication'] = function () {
    // 方案 A: 簡單 Session 驗證 (需在登入系統中設定 $_SESSION['is_admin'] = true)
    return isset($_SESSION['is_admin']) && $_SESSION['is_admin'] === true;
    
    // 方案 B: 整合現有 ACL 權限系統
    // return MyAuth::checkPermission('ckfinder_access');
    
    // ⚠️ 絕對不要直接 return true (生產環境極度危險)
};

// 【儲存路徑】上傳檔案的實體目錄 (需 Web 伺服器寫入權限)
// 建議放在 public 目錄下，並設定符號連結或直接指向
$config['backends'][] = [
    'name'         => 'default',
    'adapter'      => 'local',
    'baseUrl'      => '/public/uploads/',      // 公開可訪問的 URL 前綴
    'root'         => '/var/www/project/public/uploads/', // 實體絕對路徑 (根據實際環境修改)
    'chmodFiles'   => 0644,
    'chmodFolders' => 0755,
    'filesystemEncoding' => 'UTF-8',
];

// 其他常用設定
$config['defaultResourceTypes'] = 'Images,Files,Flash';
$config['htmlExtensions'] = ['html', 'htm', 'xml', 'js'];
$config['hideFolders'] = ['.git', 'CVS', '.svn'];
$config['hideFiles'] = ['.htaccess', 'web.config'];
$config['forceAscii'] = false; // 允許中文檔名
$config['secureImageUploads'] = true; // 驗證圖片檔頭防偽裝上傳
$config['checkSizeAfterScaling'] = true;
$config['maxImageSize'] = 0; // 不限制圖片尺寸
$config['thumbnails'] = [
    'url' => '/public/uploads/.thumbs/', // 縮圖 URL
    'directory' => '/var/www/project/public/uploads/.thumbs/', // 縮圖實體目錄
    'enabled' => true,
    'maxWidth' => 100,
    'maxHeight' => 100,
    'quality' => 80,
];

return $config;
?>

3. 設定目錄權限 (Linux)

chown -R www-data:www-data /var/www/project/public/uploads
chmod -R 755 /var/www/project/public/uploads
# 或使用 ACL 更精細控制
setfacl -R -m u:www-data:rwx /var/www/project/public/uploads

四、PHP 頁面整合 (後端渲染模式)

<?php
// /admin/edit.php
require_once __DIR__ . '/ckeditor/ckeditor.php';
require_once __DIR__ . '/ckfinder/ckfinder.php';

$CKEditor = new CKEditor();
$CKEditor->basePath = '/admin/ckeditor/';
$CKEditor->returnOutput = true;

// 關鍵：整合 CKFinder
CKFinder::SetupCKEditor($CKEditor, '/admin/ckfinder/'); // 相對於網站根目錄

// 初始內容 (來自資料庫)
$initialContent = '<p>歡迎使用 CKEditor + CKFinder</p>';

// 輸出編輯器 HTML
$editorHtml = $CKEditor->editor('content', $initialContent, ['id' => 'editor1']);
?>
<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>編輯文章</title></head>
<body>
    <form method="post" action="save.php">
        <?php echo $editorHtml; ?>
        <button type="submit">儲存</button>
    </form>
</body></html>

五、前端 JS 整合 (純 HTML/JS 頁面)

<!-- 引入 CKEditor -->
<script src="/admin/ckeditor/ckeditor.js"></script>
<!-- 引入 CKFinder -->
<script src="/admin/ckfinder/ckfinder.js"></script>

<textarea name="content" id="editor1"></textarea>

<script>
CKEDITOR.replace('editor1', {
    // CKFinder 整合設定
    filebrowserBrowseUrl: '/admin/ckfinder/ckfinder.html',
    filebrowserImageBrowseUrl: '/admin/ckfinder/ckfinder.html?type=Images',
    filebrowserFlashBrowseUrl: '/admin/ckfinder/ckfinder.html?type=Flash',
    filebrowserUploadUrl: '/admin/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files',
    filebrowserImageUploadUrl: '/admin/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images',
    filebrowserFlashUploadUrl: '/admin/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Flash'
});
</script>

六、常見問題排查

七、安全加固建議

1. 驗證檔案類型：CKFinder 預設驗證副檔名與 MIME，可額外啟用 secureImageUploads 驗證圖片檔頭。
2. 限制上傳大小：在 config.php 設定 maxFileSize，並在 PHP upload_max_filesize/post_max_size 同步調整。
3. 隔離執行權限：上傳目錄設定 php_flag engine off (Apache) 或 location ~ \.php$ { deny all; } (Nginx) 禁止腳本執行。
4. 定期掃毒：搭配 ClamAV 掃描上傳目錄。