WordPress REST API 調試實戰：從 NNNN 字符到完整修復

 

問題是如何出現的？

WordPress REST API 調試中最常見的陷阱就是 症狀與原因的巨大落差。你在前端看到 NNNN 字符和 n< 模式，但實際問題可能在完全不同的地方。

這篇文章根據真實的 WordPress 修復案例（超過 1,000 個 NNNN 字符、16 個表格損壞），詳細解析多層故障排除流程。

第 1 層：表面症狀 vs 實際原因

當 REST API 返回異常內容時，最危險的假設就是直接指責過濾器或編碼問題。實際上，以下三層都可能是問題來源：

你看到的	期望的原因	實際原因	解決難度
REST API 顯示 n<	過濾器損壞內容	資料庫中有字面 ‘n’ 字符	⭐⭐⭐⭐
NNNN 字符出現	轉義或編碼問題	‘nn’ 模式（字面n + 換行）	⭐⭐⭐⭐⭐
表格消失或亂碼	HTML 結構破壞	字面 ‘n’ 阻斷了 HTML 標籤解析	⭐⭐⭐⭐

表 1：WordPress 調試常見誤判清單 — 本表格列出 REST API 常見症狀、直觀的誤判原因，以及實際根本原因。這些誤判會導致調試花費 2-4 小時無果。

第 2 層：多層架構的信息失真

WordPress 資料從資料庫到瀏覽器經過多個轉換層，每一層都會改變你看到的表現形式：

層級	你看到的	實際的字節	驗證方式
MySQL 命令列	n（轉義序列）	0x0A（真實）或 0x6E（’n’ 字符）	od -c
PHP 讀取	實際換行或字面 ‘n’	二進位正確表示	strpos($str, “n”)
REST API JSON	n 字符或 n	JSON 正確轉義	jq + od -c
瀏覽器顯示	NNNN、亂碼或正常	HTML 渲染結果	DevTools 檢查

表 2：多層架構信息轉換對比 — 同一份資料在不同層級呈現出不同的表現。MySQL 命令列使用轉義表示，PHP 使用二進位，REST API 使用 JSON，瀏覽器進行 HTML 渲染。如果不理解這些轉換，很容易做出錯誤的根因判斷。

第 3 層：正確的調試順序

大多數 WordPress 調試問題都是因為調試順序錯誤。正確的調試順序應該是：

1. 直接檢查二進位資料（od -c）— 這是源頭事實，必須第一步做
2. 對比 DB ↔ Filter ↔ REST API 的三層輸出 — 縮小問題範圍
3. 假設反轉 — 如果不是編碼問題，那是資料損壞嗎？
4. 定位損壞位置 — 哪一層引入的？是資料庫本身還是更新時損壞？
5. 追蹤操作歷史 — 之前做過什麼導致損壞？

在真實案例中，調試花費了大量時間的原因是：第 1 次調查順序是 2 → 3 → 1 → 4 → 5，而正確順序應該是 1 → 2 → 3 → 4 → 5。

第 4 層：實際的修復步驟

步驟 1：使用 od -c 檢查資料庫的實際字節

docker exec wordpress mysql -u wpuser -pwp_password wordpress -e 
  "SELECT SUBSTRING(post_content, POSITION('' IN post_content), 50) 
   FROM wp_posts WHERE ID = 984;" | tail -1 | od -c | head -20

輸出應該顯示：

!   -   -   >   n      n   <   !   -   -
                    ^   ^
            字面'n'  實際換行

如果看到這個模式，你已經找到了根本原因：資料庫中有字面 ‘n’ 字符。

步驟 2：修復資料庫損壞

docker exec wordpress mysql -u wpuser -pwp_password wordpress -e "
UPDATE wp_posts
SET post_content = REPLACE(post_content, CONCAT('n', CHAR(10)), CHAR(10))
WHERE ID = 984;
"

這個 SQL 語句移除所有「字面 ‘n’ + 換行符」的組合，只保留實際的換行符。

步驟 3：驗證修復

curl -s http://localhost:8001/wp-json/wp/v2/posts/984 | jq -r '.content.rendered' | grep -o 'n<' | wc -l
# 應該返回 0

第 5 層：為什麼調試這麼困難？

困難點	為什麼	解決方案
信息不對稱	MySQL 顯示 n、PHP 顯示實際換行、REST API 顯示 n 字符	建立單一源頭（od -c），在那層定位問題
問題來源不清	用戶說「做表格後出現 NNNN」，但不知道之前對資料做過什麼	追蹤操作歷史，理解損壞何時引入
多層架構複雜	Database → Filter(6 個) → REST API → Browser	逐層檢查，縮小問題範圍到特定層級
工具轉換多次	MySQL CLI → od -c → PHP → curl → jq → JSON	固定驗證工具，避免多次轉換導致的失真

表 3：WordPress REST API 調試困難點分析 — 列出調試過程中的四個主要困難，以及每個困難對應的解決方案。這些都是基於真實的修復案例總結出來的。

第 6 層：最佳實踐清單

• 第一步永遠是 od -c — 不要猜測，直接看二進位數據
• 建立多層驗證 — 不要只檢查一層，Database + Filter + REST API 都要查
• 假設反轉 — 一個方向卡住了，立即反轉假設方向
• 追蹤操作歷史 — 理解「之前發生了什麼」比「現在看起來怎樣」更重要
• 表格要有邊框 — 使用 inline style: style="border: 1px solid #333; padding: 8px;"
• 保存配置檔 — WordPress API 認證信息應該存在 ~/.claude/projects/project-name/wordpress-config.env

常見問題（FAQ）

總結

WordPress REST API 調試的關鍵是理解 多層架構中的信息失真。症狀永遠不等於原因，你看到的 NNNN 字符只是冰山一角。

記住這個優先順序：

1. od -c 檢查二進位（源頭事實）
2. 逐層驗證（Database → Filter → REST API）
3. 假設反轉（卡住時反向思考）
4. 追蹤歷史（理解根本原因）
5. 修復並驗證（修完要驗證三層）

下次遇到 WordPress REST API 問題時，不要急著改過濾器或重建資料庫。先用 od -c 看看真正的二進位數據，一切就清楚了。