概述
在 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 与第三方平台集成的场景——无论是对接微信小程序、飞书文档、还是企业微信，认证兼容性和内容适配都是必须认真对待的工程问题。
