Workflow-js项目中使用QStash调度时请求头配置注意事项
在基于Next.js的Workflow-js项目中，开发者可能会遇到一个典型的签名验证问题：当通过QStash调度服务调用pages路由中的工作流时，系统会返回"body hash does not match"的错误。这个问题的根源在于请求头配置的差异。
问题现象
当开发者按照标准方式在pages路由中实现工作流时，使用QStash进行调度调用会触发签名验证失败。具体表现为：
- 服务端返回签名不匹配的错误提示
- 本地调用可以正常执行
- 移除签名密钥后也能工作
- 在app路由中使用serve方法可以正常运行
技术原理分析
这个问题的本质在于HTTP请求体的哈希计算方式。Workflow-js的签名验证机制会严格校验请求内容的哈希值，而不同的Content-Type头会导致请求体解析方式的差异：
- 当使用
application/json时，请求体可能被自动解析为JSON对象 - 使用
text/plain时，请求体会被作为原始文本处理 - 这两种处理方式会产生不同的哈希计算结果
解决方案
经过验证，在pages路由中调用工作流时，必须确保QStash调度请求包含以下请求头：
Content-Type: text/plain
这个配置可以确保请求体以原始文本形式传输，与签名验证时的哈希计算方式保持一致。值得注意的是，当直接使用workflow客户端调用时，application/json可以正常工作，但QStash调度服务需要特别配置。
最佳实践建议
- 对于pages路由中的工作流端点，统一要求
text/plain内容类型 - 在QStash调度配置中显式设置Content-Type头
- 如果必须使用JSON格式，建议考虑迁移到app路由架构
- 在开发测试阶段，可以使用签名验证禁用模式进行快速验证
这个案例提醒我们，在不同架构和中间件组合使用时，需要特别注意内容协商和签名验证机制的兼容性问题。理解底层技术原理有助于快速定位和解决这类边界情况。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
