本文详解 node.js 中使用 contentful sdk 时因混用回调与 promise 导致的请求挂起问题，提供正确使用 `await` + `try/catch` 的标准写法，并附完整可运行示例。
在 Node.js 后端集成 Contentful CMS 时，一个常见却隐蔽的问题是：API 接口长时间无响应（浏览器转圈）、控制台无报错、Postman 却能正常返回数据。这通常并非网络或认证问题，而是 SDK 调用方式不匹配引发的异步逻辑阻塞。
Contentful JavaScript SDK 的 client.getEntries() 方法返回的是 Promise 对象，而非立即执行的同步函数。原代码中同时使用了回调函数（第 2 个参数）和 .catch()，属于典型的「Promise 与回调混用」反模式：
// ❌ 错误示范：混用回调与 Promise 链
client.getEntries({ ... }, (err, courses) => { ... }).catch(...)该写法会导致：
- 回调函数被忽略（SDK 在 Promise 模式下不触发回调）；
- Promise 未被 await 或 .then() 显式消费，Node.js 事件循环无法推进；
- 请求永久挂起，无响应、无错误——因为异常未被捕获，也未终止响应流。
✅ 正确做法是统一使用 async/await 语法，并配合 try/catch 处理异常：
const contentful = require('contentful');
const getCourses = async (req, res) => {
const client = contentful.createClient({
space: '9f3v4l5x639t',
accessToken: 'l83Wr4f12LlnCfo71Jv4NwSyt2x-M1Q0AQ22O5kRuEI'
});
try {
// ✅ 正确：await Promise，获取完整响应对象
const response = await client.getEntries({
content_type: 'course',
locale: 'en-US',
order: '-sys.createdAt',
include: 2
});
// 注意：Contentful 返回结构为 { items: [...], total: N, skip: 0, limit: 100 }
if (response.items.length === 0) {
return res.status(404).json({
success: false,
error: 'No courses found'
});
}
// ✅ 关键：返回 response.items（实际数据数组），而非整个 response 对象
return res.status(200).json({
success: true,
data: response.items
});
} catch (err) {
console.error('[Contentful Courses Fetch Error]:', err);
// 区分错误类型（如网络超时、token 失效、schema 不匹配）可进一步细化处理
return res.status(500).json({
success: false,
error: 'Failed to fetch courses from Contentful'
});
}
};
module.exports = getCourses;? 关键注意事项：
- 永远检查 response.items 而非 response.length：Contentful 响应是对象，不是数组；courses.length 会恒为 undefined，导致 !courses.length 恒为 true，意外触发 404。
- 避免硬编码敏感信息：将 space 和 accessToken 移至环境变量（如 .env 文件），使用 process.env.CONTENTFUL_SPACE_ID 等方式读取。
- 启用日志与监控：在 catch 块中打印完整 err（含 err.message、err.status、err.requestId），便于调试 Contentful 特定错误（如 403 权限不足、429 请求频次超限）。
- 考虑缓存与降级：生产环境建议添加 Redis 缓存层，并在 Contentful 不可用时返回兜底静态数据或友好提示。
通过以上修正，GET /api/courses 将稳定返回课程列表，与 MongoDB 接口（如 /movies）行为完全一致——这也印证了问题本质是 SDK 使用方式，而非路由或基础架构配置。
