概述
在 Headless WordPress 架構中，自訂 REST API 端點是與外部系統互動的核心通道。然而，生產環境常常面臨兩大挑戰：API 認證在各類伺服器配置下的相容性問題，以及第三方平台（如微信公眾號）對內容格式的嚴苛要求。本文分享薩龍網路在龍霄主題專案中針對這兩個痛點的優化實踐。
一、自訂 REST API 的安全加固
在之前的版本中，我們使用 define('HERMES_AI_PUBLISH_API_KEY', 'xxx') 定義 API 金鑰，並在認證回呼中透過常數比較驗證請求。這種方式在實際部署中暴露出兩個問題：
1. 常數被意外覆蓋
WordPress 的 define() 是冪等的——如果同一個常數名在其他地方先被定義，外掛中的定義會被靜默忽略。在薩龍網路的伺服器上，主題或框架程式碼中可能存在同名的常數定義，導致外掛中預設的金鑰失效。解決方案是使用 defined() 守衛和更獨特的常數名：
if (!defined('HERMES_PUBLISH_SECRET')) {
define('HERMES_PUBLISH_SECRET', 'hermes-ai-publish-key-2026');
}更徹底的做法是直接在認證邏輯中硬編碼金鑰進行比較，完全避免常數解析的不確定性：
return !empty($key) && $key === 'hermes-ai-publish-key-2026';2. 請求標頭的多層級回退
Nginx、CDN 或安全外掛可能會對自訂 HTTP 標頭進行規範化處理（如統一轉為小寫）甚至直接剝離。為保證相容性，認證邏輯需要建立多層級的 header 回退鏈：
$key = $request->get_header('X-Hermes-Key'); // WP 規範化
if (empty($key)) $key = $request->get_header('x-hermes-key'); // 全小寫
if (empty($key)) $key = $_SERVER['HTTP_X_HERMES_KEY'] ?? ''; // 原始標頭
if (empty($key)) $key = $request->get_param('key'); // URL 參數這個回退鏈覆蓋了 WP REST API 規範化、Nginx 小寫轉換、以及極端情況下標頭被剝離後透過 query string 傳遞的場景。
3. Debug 端點的價值
在生產環境中除錯 API 認證問題時，新增一個無需認證的 /debug 端點可以極大節省排查時間。該端點直接返回請求標頭的原始資訊和當前常數的解析值：
register_rest_route('hermes/v1', '/debug', [
'methods' => 'GET',
'callback' => function ($request) {
return rest_ensure_response([
'headers' => $request->get_headers(),
'param_key' => $request->get_param('key'),
'defined_key' => defined('HERMES_PUBLISH_SECRET')
? HERMES_PUBLISH_SECRET : 'NOT_DEFINED',
]);
},
'permission_callback' => '__return_true',
]);透過這個端點，可以快速確認：請求標頭是否正確到達了 WordPress、常數是否被覆蓋、以及認證失敗的具體環節。
二、微信公眾號文章排版自動化
薩龍網路的龍霄主題整合了微信公眾號草稿同步功能。當文章在 WordPress 後台發布後，需要自動將內容推送到微信公眾號的草稿箱。這個過程的核心挑戰在於：微信公眾平台對 HTML 的支援非常有限。
1. 從主題配置中提取排版參數
傳統的做法是硬編碼一套固定的字號和行高。但龍霄主題提供了豐富的主題選項，允許使用者自訂各級標題和正文字號。改進方案是動態讀取主題配置中的 style_general 選項：
$styleGeneral = (array) salong_theme_options('style_general');
// 提取 h1-h6 的 fontSize 和 lineHeight
foreach (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as $tag) {
$size = $styleGeneral[$tag]['width'] ?? '';
$height = $styleGeneral[$tag]['height'] ?? '';
$h[$tag] = [
'size' => $size ? $size . 'px' : '',
'height' => $height ? $height . 'px' : '',
];
}
// 正文優先使用行動端字號配置
$bodySize = $styleGeneral['post_content_mobile']['width']
?? $styleGeneral['body']['width']
?? '16px';這樣做的好處是：微信端的排版自動跟隨主題設定，無需額外維護一套獨立的樣式配置。
2. HTML 內容清洗管線
微信公眾號不支援 <iframe>、<video>、<audio>、<embed>、<script>、<style> 等標籤。此外，Gutenberg 編輯器會在輸出中插入大量區塊級 HTML 註解（如 <!-- wp:paragraph -->）。清洗管線如下：
// 1. 移除不支援的標籤
$html = preg_replace('/<iframeb[^>]*>.*</iframe>/is', '', $html);
$html = preg_replace('/<videob[^>]*>.*</video>/is', '', $html);
$html = preg_replace('/<audiob[^>]*>.*</audio>/is', '', $html);
$html = preg_replace('/<embedb[^>]*>/i', '', $html);
$html = preg_replace('/<scriptb[^>]*>.*</script>/is', '', $html);
$html = preg_replace('/<styleb[^>]*>.*</style>/is', '', $html);
$html = preg_replace('/<linkb[^>]*>/i', '', $html);
// 2. 移除 Gutenberg 區塊註解
$html = preg_replace('/<!--s*/?wp:.*?-->s*/s', '', $html);
// 3. 為段落和圖片注入內聯樣式
$html = preg_replace('/<p(?![^>]*bstyle=)([^>]*)>/i',
'<p style="margin:0 0 16px;"$1>', $html);
$html = preg_replace('/<img(?![^>]*bstyle=)([^>]*)>/i',
'<img style="max-width:100%;height:auto;"$1>', $html);3. 作者資訊自動填充
新版本還增加了從 WordPress 使用者資料自動獲取作者資訊的功能：
$author_id = (string) get_the_author_meta('ID', $post_id);
$author_data = User::data($author_id);
$article['author'] = $author_data['name'] ?? '';同時保留了「直接發布」模式的擴充點，為未來實現自動發布到微信公眾號（而非僅儲存草稿）預留了介面。
三、實踐總結
本次最佳化圍繞兩個核心原則：防禦性程式設計和配置驅動。
在 API 安全層面，不假設單一認證方式在所有環境下都能正常工作。透過多層回退、debug 端點、以及硬編碼兜底策略，確保服務的強固性。在內容格式化層面，將排版參數的控制權交還給主題配置系統，避免硬編碼帶來的維護負擔。
這些實踐同樣適用於其他 WordPress 與第三方平台整合的場景——無論是對接微信小程式、飛書文件、還是企業微信，認證相容性和內容適配都是必須認真對待的工程問題。
![龍霄主題-電商與會員一體化產品外掛：讓內容變現從[能賣]到[賣得好]](https://demo.salongweb.com/longxiao/thumb/43.webp?x-oss-process=image/resize,m_fill,w_600,h_338/quality,q_60/format,webp)
![龍霄主題-電商與會員一體化產品外掛：讓內容變現從[能賣]到[賣得好]](https://demo.salongweb.com/longxiao/thumb/43.webp?x-oss-process=image/resize,m_fill,w_120,h_120/quality,q_60/format,webp)