Craft CMS 5.x 中GraphQL预览功能失效问题解析

问题背景

在Craft CMS 5.7.0版本中，开发者在使用Headless架构（如Astro前端）配合GraphQL API时，发现通过X-Craft-Token头信息无法正确获取内容草稿的预览版本。这是一个典型的CMS前后端分离场景下的预览功能实现问题。

技术原理

Craft CMS的预览系统通过两种机制协同工作：

1. x-craft-live-preview参数：主要用于防止浏览器缓存干扰，同时让系统识别当前是预览请求
2. token参数/X-Craft-Token头：这才是真正用于获取草稿内容的关键凭证

问题根源

开发者最初混淆了两种参数的作用，错误地将x-craft-live-preview参数值作为X-Craft-Token头的值传递。实际上：

• x-craft-live-preview参数是长哈希值（如b2d19640...）
• 真正的token参数是较短的字符串，仅在编辑内容时生成

正确实现方案

要实现正确的预览功能，前端需要：

1. 从iframe的URL中提取token参数
2. 将其作为X-Craft-Token头传递给GraphQL API

示例代码实现：

const urlParams = new URLSearchParams(document.location.search);
const token = urlParams.get('token');

// 在API请求中添加头信息
const headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Craft-Token': token
};

注意事项

1. token生成时机：只有在内容编辑状态下才会生成token参数
2. 默认行为：未提供有效token时，API会返回已发布的内容版本
3. 缓存控制：x-craft-live-preview参数虽不参与内容获取，但对防止缓存很重要

最佳实践建议

1. 实现前端逻辑时，应先检查token参数是否存在
2. 对于未登录用户或未提供token的情况，应有合理的回退机制
3. 在开发环境中，可使用浏览器开发者工具检查网络请求，确认头信息是否正确传递

通过正确理解Craft CMS的预览机制和参数用途，开发者可以构建稳定可靠的内容预览功能，为内容编辑提供流畅的实时预览体验。