Contentful.js：用 JavaScript 操作内容管理的轻量方案

内容管理和前端开发之间的协作，一直是 Web 项目中的一个痛点。传统 CMS 把内容和页面模板绑在一起，前后端耦合严重。Contentful 作为一款 headless CMS，把内容从展示层剥离出来，通过 API 交付结构化数据。而 contentful.js 就是官方提供的 JavaScript SDK，用于在 Node.js 和浏览器环境中对接 Contentful 的内容交付接口。

目前这个项目在 GitHub 上有 1,291 个 Star。

contentful.js 封装了 Contentful 的 Content Delivery API 和 Content Preview API，开发者通过它可以直接在 JavaScript 应用里获取、查询存储在 Contentful 平台上的内容。

它能做什么

这个库的核心能力包括几个方面：

1. 内容检索：通过 Delivery API 获取已发布的内容，通过 Preview API 获取草稿或未发布的内容。
2. 同步机制：支持增量同步，适合需要缓存或离线场景的应用。
3. 多语言支持：Contentful 原生支持多 locale，SDK 也内置了对应的参数处理。
4. 链接解析：Contentful 的内容之间通过链接关联，SDK 会自动解析内联的引用关系。
5. 内置限流与重试：遇到 500 或 429 响应时会自动重试，不用开发者自己处理。
6. 多环境支持：从 v6.0.0 开始支持 Contentful 的 Environments 功能。

支持的运行环境

Chrome、Firefox、Edge、Safari 这几个主流浏览器都在支持范围内，Node.js 方面支持 LTS 版本，React Native 也可以通过 Metro bundler 使用。

库本身以 ESM 模块构建，同时也提供 CommonJS 格式的导出，方便不同环境的项目接入。如果需要在浏览器里直接用，还可以通过 CDN 加载打包好的文件。

基本用法

安装很简单：

npm install contentful

一个最基本的请求示例：

import * as contentful from 'contentful'

const client = contentful.createClient({
  space: 'your_space_id',
  accessToken: 'your_access_token',
})

client.getEntry('entry_id')
  .then((entry) => console.log(entry))
  .catch((err) => console.log(err))

创建客户端时需要提供 space ID 和 access token，这两个都可以在 Contentful 的 Web 管理界面里找到。

客户端链式修饰

从 v10.0.0 开始，SDK 引入了链式修饰符的设计。比如你想获取所有语言版本的数据，可以这样写：

const entries = await client.withAllLocales.getEntries()

如果想移除无法解析的链接对象：

const entries = await client.withoutUnresolvableLinks.getEntries()

这些修饰符可以组合使用，返回值的类型也会根据修饰符自动推导，对 TypeScript 用户比较友好。

游标分页

对于内容量较大的项目，SDK 提供了基于游标的分页方式：

const response = await client.getEntriesWithCursor({ limit: 10 })
console.log(response.items)
console.log(response.pages?.next)

拿到 next 游标后传入下一次请求即可翻页，比传统的 skip/limit 方式更适合大数据量场景。

Preview API

除了正式发布的内容，SDK 也能对接 Preview API，用来预览未发布的内容。只需要把 host 指向 preview.contentful.com，同时使用 Preview API 的 access token 就行。

写在后面

contentful.js 是一个定位明确的工具库，它不试图做太多事情，只专注于把 Contentful 的内容交付能力带给 JavaScript 开发者。如果你的项目用了 Contentful 作为内容管理平台，这个 SDK 是最直接的接入方式。

，只专注于把 Contentful 的内容交付能力带给 JavaScript 开发者。如果你的项目用了 Contentful 作为内容管理平台，这个 SDK 是最直接的接入方式。