CKEditor + CKFinder + PHP 文件上傳完整配置指南

架構說明

CKEditor 4/5 只負責編輯，文件上傳由獨立組件 CKFinder 處理，通過連接器 (Connector) 與後端交互。

1. 下載與目錄結構

/project-root/
├── ckeditor/           # CKEditor 核心
│   ├── ckeditor.js
│   └── ...
├── ckfinder/           # CKFinder 核心
│   ├── config.php      # 主配置
│   ├── core/
│   │   └── connector/
│   │       └── php/
│   │           └── php5/
│   │               └── CommandHandler/
│   │                   └── FileUpload.php  # 上傳處理
│   └── ...
└── upload/             # 上傳目錄 (需寫權限)

2. 核心配置步驟

步驟 1：啟用認證 (config.php)

<?php
// ckfinder/config.php 第 ~21 行
function CheckAuthentication() {
    // ⚠️ 生產環境必須實現真實認證邏輯！
    // return isset($_SESSION['user']) && $_SESSION['user']['role'] === 'admin';
    return true; // 開發測試臨時開啟
}
?>

步驟 2：設置上傳目錄 URL (config.php)

<?php
// 第 ~63 行
$baseUrl = '/upload/'; // 訪問 URL 路徑，必須以 / 結尾

// 確保目錄存在且可寫
// chmod 777 upload/ (Linux)
?>

步驟 3：按日期自動創建子目錄 (config.php)

<?php
// 第 ~189 行 $config['ResourceType'] 陣列
$config['ResourceType'][] = array(
    'name' => 'Files',
    'url' => $baseUrl . 'files/' . date('Y') . '/' . date('m') . '/',
    'directory' => $baseDir . 'files/' . date('Y') . '/' . date('m') . '/',
    'maxSize' => 0,
    'allowedExtensions' => '7z,aiff,asf,avi,bmp,csv,doc,docx,fla,flv,gif,gz,gzip,jpeg,jpg,mid,mov,mp3,mp4,mpc,mpeg,mpg,ods,odt,pdf,png,ppt,pptx,pxd,qt,ram,rar,rm,rmi,rmvb,rtf,sdc,sitd,swf,sxc,sxw,tar,tgz,tif,tiff,txt,vsd,wav,wma,wmv,xls,xlsx,zip',
    'deniedExtensions' => '',
);

// Images, Flash 同理修改 url 和 directory

步驟 4：上傳文件重命名 (防中文亂碼/衝突)

<?php
// ckfinder/core/connector/php/php5/CommandHandler/FileUpload.php
// 在類中添加方法
protected function generateFileName($originalName) {
    $ext = pathinfo($originalName, PATHINFO_EXTENSION);
    $ext = $ext ? '.' . $ext : '';
    
    // 格式: 年月日時分秒_微秒_隨機數.擴展名
    $time = explode(' ', microtime());
    $rand = substr(str_shuffle('abcdefghijklmnopqrstuvwxyz0123456789'), 0, 6);
    return date('YmdHis') . substr($time[0], 2, 6) . '_' . $rand . $ext;
}

// 在 onUpload 方法中，文件驗證後調用
// 找到 (約第 63 行):
if ($sFileName != $sUnsafeFileName) {
    $iErrorNumber = CKFINDER_CONNECTOR_ERROR_UPLOADED_INVALID_NAME_RENAMED;
}
// 在此處添加:
$sExtension = CKFinder_Connector_Utils_FileSystem::getExtension($sFileName);
$sFileName = $this->generateFileName($sFileName) . $sExtension;

3. 前端 CKEditor 集成

<!-- HTML 頁面 -->
<script src="/ckeditor/ckeditor.js"></script>
<script src="/ckfinder/ckfinder.js"></script>

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

<script>
CKEDITOR.replace('editor', {
    height: 400,
    // CKFinder 集成
    filebrowserBrowseUrl: '/ckfinder/ckfinder.html',
    filebrowserImageBrowseUrl: '/ckfinder/ckfinder.html?type=Images',
    filebrowserUploadUrl: '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files',
    filebrowserImageUploadUrl: '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images',
    // 允許的內容規則 (CKEditor 4)
    allowedContent: true,
    // 或自定義 toolbar
    toolbar: 'Full'
});

// CKFinder 獨立彈窗 (可選)
function openFinder() {
    CKFinder.popup({
        chooseFiles: true,
        width: 800,
        height: 600,
        onInit: function(finder) {
            finder.on('files:choose', function(evt) {
                var file = evt.data.files.first();
                alert('選擇: ' + file.getUrl());
            });
        }
    });
}
</script>

4. 權限與安全配置

<?php
// ckfinder/config.php 關鍵安全配置

// 1. 禁止執行上傳目錄下的腳本
// Nginx:
# location /upload/ {
#     location ~ \.php$ { deny all; }
# }

# Apache (.htaccess 在 upload/ 目錄):
# 
#     Order Allow,Deny
#     Deny from all
# 

// 2. 文件類型驗證 (雙重保險)
$config['CheckDoubleExtension'] = true;
$config['DisallowedExtensions'] = ['php','php3','php5','phtml','asp','aspx','jsp','exe','bat','sh','pl','cgi'];
$config['HtmlExtensions'] = ['html','htm','xml','xhtml','js'];

// 3. 文件大小限制
$config['MaxFileSize'] = 20 * 1024 * 1024; // 20MB

// 4. 圖片尺寸限制 (可選)
$config['Images'] = [
    'maxWidth' => 2000,
    'maxHeight' => 2000,
    'quality' => 85
];

5. 常見問題排查

版本兼容性提示

• CKFinder 3.x 需 PHP 5.4+，推薦 PHP 7.4+
• CKEditor 4 配合 CKFinder 3 穩定
• CKEditor 5 需 CKFinder 3.5+ 或使用 CKBox (新產品)
• 商業授權：生產環境請購買授權