百度 UEditor 是國內廣泛使用的富文本編輯器，版本 1.4.3 穩定且功能豐富。許多 PHP 開發者在初次整合時常因前後端配置不當導致上傳失敗、工具欄缺失等問題。本文梳理從下載、前端引入、配置解析到後端控制器對接的完整流程，助你快速落地。
/ueditor/，結構如下：/ueditor/
├── ueditor.config.js # 前端靜態配置
├── ueditor.all.min.js # 核心 JS（含語言包）
├── themes/ # 主題樣式
├── dialogs/ # 對話框模板
├── lang/ # 多語言包
├── third-party/ # 第三方依賴
└── php/
├── config.json # 後端核心配置
└── controller.php # 統一入口控制器
在需要編輯器的頁面引入核心 JS，並在 textarea 或 div 上初始化：
<script src="/ueditor/ueditor.config.js"></script>
<script src="/ueditor/ueditor.all.min.js"></script>
<textarea id="editor" name="content"></textarea>
<script>
var ue = UE.getEditor('editor', {
// 動態配置示例：自定義工具欄
toolbars: [[
'fullscreen', 'source', '|', 'undo', 'redo', '|',
'bold', 'italic', 'underline', '|',
'insertimage', 'insertvideo', 'attachment'
]],
autoHeightEnabled: true,
autoFloatEnabled: true
});
</script>
瀏覽頁面即可看到編輯器渲染完成。
UEditor 採用「後端配置 > 實例化傳參 > 前端靜態配置」的優先級覆蓋機制。所有操作（獲取配置、上傳圖片、列表圖片等）均通過 GET 請求 serverUrl?action=xxx 完成。
php/config.json核心字段說明：
imageUrl：上傳圖片的接口地址（預設指向 controller.php?action=uploadimage）imagePath：圖片存儲的相對路徑imageFieldName：上傳表單字段名（預設 upfile）imageMaxSize：單位 KBimageAllowFiles：允許的副檔名陣列其他同理：scrawl（塗鴉）、catcher（遠程抓圖）、video、file、imageManager、fileManager 等。
瀏覽器直接訪問 /ueditor/php/controller.php?action=config，應返回合法 JSON。若出現 404/500，檢查：
php.ini 開啟 file_uploads、allow_url_fopenchmod 777 對應上傳目錄）config.json 中路徑是否為絕對路徑或相對網站根目錄serverUrl若後端入口非預設路徑，可在實例化時覆蓋：
var ue = UE.getEditor('editor', {
serverUrl: '/api/ueditor/controller.php' // 自定義後端入口
});
| 現象 | 可能原因 | 解決 |
|---|---|---|
| 上傳返回「後端配置項無法正常加載」 | controller.php?action=config 非 JSON 或報錯 | 直接訪問該 URL 查看錯誤日誌，修正 PHP 錯誤或路徑 |
| 圖片上傳成功但顯示不出來 | imagePath 與實際存儲路徑不一致 | 確保 imagePath 為網站可訪問的相對路徑，且與 imageUrl 返回的 url 前綴一致 |
| 工具缺失/樣式錯亂 | 前端靜態資源 404 | 檢查 ueditor.config.js 中 UEDITOR_HOME_URL 是否正確指向 /ueditor/ |
UEditor 只約定了「GET action=config 返回 JSON」與「POST 上傳返回 {state: 'SUCCESS', url: '', title: '', original: ''}」兩套協議。理解這一點後，Java、Go、Node.js、Python 等均可按協議實現 controller.php 邏輯，官方 Demo 目錄下提供了多語言參考實現。
整合 UEditor 核心在於「前端實例化 → 請求後端 config → 後端返回上傳接口 → 前端上傳 → 後端存檔並返回 URL」。掌握配置優先級與請求流向，配合瀏覽器 Network 面板觀察 action 參數，即可快速定位並解決 90% 的整合問題。
