PHP 中配置 FCKeditor 編輯器完整指南：精簡部署與中文優化

前言

FCKeditor (現已更名為 CKEditor 4/5) 曾是 Web 富文本編輯器的主流選擇。雖然官方已停止更新，但大量存量專案仍在使用。本文詳細記錄 PHP 環境下 FCKeditor 的精簡部署、核心配置、文件上傳啟用與中文路徑亂碼解決方案，助你快速落地遷移。

一、精簡部署：目錄瘦身指南

官方完整包超 5MB，實際生產僅需核心文件。刪除以下冗餘內容：

FCKeditor/
├── fckconfig.js          # 核心配置（保留）
├── fckeditor.js          # 核心 JS（保留）
├── fckstyles.xml         # 樣式定義（保留）
├── fcktemplates.xml      # 模板定義（保留）
├── fckeditor.php         # PHP 服務端整合類（保留）
├── editor/
│   ├── _source/          # 刪除：源碼調試版
│   ├── _testcases/       # 刪除：測試用例
│   ├── _samples/         # 刪除：示例頁面
│   ├── filemanager/
│   │   ├── browser/
│   │   │   └── default/
│   │   │       └── connectors/
│   │   │           ├── php/        # 保留：PHP 連接器
│   │   │           ├── asp/        # 刪除
│   │   │           ├── aspx/       # 刪除
│   │   │           ├── jsp/        # 刪除
│   │   │           └── ...         # 刪除其他語言
│   │   └── upload/
│   │       ├── php/        # 保留
│   │       └── ...         # 刪除其他語言
│   └── lang/
│       ├── en.js           # 保留：英文
│       ├── zh.js           # 保留：繁體中文
│       ├── zh-cn.js        # 保留：簡體中文
│       └── *.js            # 刪除其他語言

刪除後核心目錄僅約 800KB，加載速度顯著提升。

二、核心配置：fckconfig.js 關鍵設置

<?php
// fckconfig.js 關鍵配置段
// 1. 默認語言設置
FCKConfig.DefaultLanguage = 'zh-cn'; // 或 'zh' (繁體)

// 2. 文件瀏覽與上傳語言指向 PHP
var _FileBrowserLanguage = 'php';  // 原為 'asp'
var _QuickUploadLanguage = 'php';  // 原為 'asp'

// 3. 編輯器皮膚 (可選)
FCKConfig.SkinPath = FCKConfig.BasePath + 'editor/skins/office2003/';

// 4. 工具欄配置 (精簡版)
FCKConfig.ToolbarSets["Basic"] = [
    ['Source', 'DocProps', '-', 'Save', 'NewPage', 'Preview', '-', 'Templates'],
    ['Cut', 'Copy', 'Paste', 'PasteText', 'PasteWord', '-', 'Print', 'SpellCheck'],
    ['Undo', 'Redo', '-', 'Find', 'Replace', '-', 'SelectAll', 'RemoveFormat'],
    '/',
    ['Bold', 'Italic', 'Underline', 'StrikeThrough', '-', 'Subscript', 'Superscript'],
    ['OrderedList', 'UnorderedList', '-', 'Outdent', 'Indent', 'Blockquote'],
    ['JustifyLeft', 'JustifyCenter', 'JustifyRight', 'JustifyFull'],
    ['Link', 'Unlink', 'Anchor'],
    ['Image', 'Flash', 'Table', 'Rule', 'Smiley', 'SpecialChar', 'PageBreak'],
    '/',
    ['Style', 'FontFormat', 'FontName', 'FontSize'],
    ['TextColor', 'BGColor'],
    ['FitWindow', 'ShowBlocks', '-', 'About']
];

FCKConfig.ToolbarSets["Default"] = FCKConfig.ToolbarSets["Basic"];
?>

三、啟用文件上傳：雙連接器配置

FCKeditor 使用兩套獨立連接器：文件瀏覽器 (瀏覽服務器文件) 與 快速上傳 (工具欄圖標直接上傳)，必須雙雙啟用。

1. 文件瀏覽器連接器

文件： editor/filemanager/browser/default/connectors/php/config.php

<?php
// 啟用連接器
$Config['Enabled'] = true;

// 設置用戶文件虛擬路徑 (URL 訪問路徑)
$Config['UserFilesPath'] = '/uploads/'; // 必須以 / 結尾，對應 Web 根目錄下 uploads/

// 設置用戶文件物理路徑 (服務器絕對路徑)
$Config['UserFilesAbsolutePath'] = '/var/www/html/uploads/'; // 建議使用絕對路徑

// 允許上傳的文件類型
$Config['AllowedExtensions']['File']    = ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'zip', 'rar'];
$Config['DeniedExtensions']['File']     = ['php', 'php3', 'php5', 'phtml', 'asp', 'aspx', 'jsp', 'exe', 'bat'];
$Config['AllowedExtensions']['Image']   = ['jpg', 'jpeg', 'png', 'gif', 'webp'];
$Config['DeniedExtensions']['Image']    = [];
$Config['AllowedExtensions']['Flash']   = ['swf', 'flv'];
$Config['DeniedExtensions']['Flash']    = [];

// 最大文件大小 (bytes) - 0 為不限制 (受限於 php.ini)
$Config['MaxFileSize'] = 10 * 1024 * 1024; // 10MB

// 安全：禁止 HTML 執行
$Config['HtmlExtensions'] = ['html', 'htm', 'shtml', 'shtm'];
$Config['SecureImageUploads'] = true; // 檢測圖片偽裝腳本
?>

<?php
$Config['Enabled'] = true;
$Config['UserFilesPath'] = '/uploads/';
$Config['UserFilesAbsolutePath'] = '/var/www/html/uploads/';

// 同樣配置允許/禁止擴展名、大小限制...
// 關鍵差異：此處處理工具欄「插入圖片/文件」直接上傳的請求
?>

<?php
require_once 'FCKeditor/fckeditor.php'; // 引入整合類

// 實例化編輯器
$oFCKeditor = new FCKeditor('article_content'); // 表單字段名
$oFCKeditor->BasePath = '/FCKeditor/';          // 編輯器相對網站根目錄 URL
$oFCKeditor->Value = '<p>初始內容...</p>';    // 初始值 (已編碼 HTML)
$oFCKeditor->Width = '100%';
$oFCKeditor->Height = '400';
$oFCKeditor->ToolbarSet = 'Basic';              // 使用精簡工具欄
$oFCKeditor->Config['CustomConfigurationsPath'] = ''; // 禁用自定義配置文件
$oFCKeditor->Create();                          // 輸出 HTML
?>

<?php
// 在文件保存前，統一將文件名從 UTF-8 轉為系統編碼 (Linux 通常為 UTF-8，Windows 為 GBK)
// 但為跨平台兼容，建議：上傳時重命名為 UUID + 原擴展名，資料庫記錄原文件名

function sanitizeFileName($fileName) {
    $ext = strtolower(pathinfo($fileName, PATHINFO_EXTENSION));
    $allowedExt = ['jpg','jpeg','png','gif','pdf','doc','docx','xls','xlsx','zip','rar'];
    if (!in_array($ext, $allowedExt)) $ext = 'bin';
    
    // 生成唯一文件名：時間戳 + 隨機數 + 擴展名
    $newName = date('YmdHis') . '_' . mt_rand(1000, 9999) . '.' . $ext;
    return $newName;
}

// 在 move_uploaded_file 之前調用
$originalName = $_FILES['NewFile']['name'];
$safeName = sanitizeFileName($originalName);
$targetPath = $Config['UserFilesAbsolutePath'] . $safeName;

if (move_uploaded_file($_FILES['NewFile']['tmp_name'], $targetPath)) {
    // 返回給編輯器的 URL (使用安全文件名)
    $url = $Config['UserFilesPath'] . $safeName;
    // 可選：將原始文件名存入資料庫，供下載時恢復
    // saveFileMapping($safeName, $originalName);
    echo "";
} else {
    echo "";
}
?>

CREATE TABLE `editor_files` (
  `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  `storage_name` VARCHAR(100) NOT NULL COMMENT '存儲文件名 (UUID)',
  `original_name` VARCHAR(255) NOT NULL COMMENT '用戶原始文件名',
  `file_path` VARCHAR(500) NOT NULL COMMENT '相對存儲路徑',
  `file_size` INT UNSIGNED DEFAULT 0,
  `mime_type` VARCHAR(100) DEFAULT '',
  `upload_ip` VARCHAR(45) DEFAULT '',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY `uk_storage` (`storage_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

<!-- CKEditor 5 經典模式快速上手 -->
<script src="https://cdn.ckeditor.com/ckeditor5/39.0.1/classic/ckeditor.js"></script>
<textarea id="editor" name="content"></textarea>
<script>
ClassicEditor.create(document.querySelector('#editor'), {
    language: 'zh-cn',
    toolbar: ['heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'blockQuote', 'undo', 'redo']
}).catch(error => console.error(error));
</script>