Docs Overview/
Contentful集成/

Contentful集成

Contentful 是一个基于云的 Headless CMS，通过 API 管理和分发内容。相比传统 CMS，Headless CMS 实现了内容与前端的分离，便于多端适配，提升开发效率和内容管理的灵活性。

概览

本文介绍如何使用 Contentful 作为内容管理系统，结合 AstroJS 静态网站生成器搭建博客站点。通过 EdgeOne Pages 的一键部署功能，您可以快速将网站部署到全球 CDN 节点，实现毫秒级访问速度。AstroJS 的"零 JavaScript 开销"特性与 EdgeOne 的全球加速能力相结合，为您的博客提供极致的访问体验。

快速入门

为了帮助您入门，我们使用 Contentful 和 AstroJS 构建了一个模板。部署后，只需在 Contentful 中调整内容配置，网站即可自动展示最新内容。
如果希望在本地进行开发和调试，也可以从 GitHub 获取模板，按照本文后续说明完成本地部署和预览。
Contentful的集成分为三个主要步骤：Contentful配置、生成静态文件、部署到EdgeOne Pages。下面将详细介绍每个步骤的具体操作。

Contentful配置

1、创建Contentful账号

访问 Contentful官网，点击"Log in"开始注册。在注册过程中，您需要填写基本信息并选择适合的套餐。对于个人博客或小型项目，免费版已经足够使用。

2、创建内容模型

注册Contentful账号后，建议先了解其核心概念和配置项。Contentful提供了详细的中文文档，建议访问Contentful官方文档了解以下核心概念：
Space（空间）：内容管理的独立工作区
Content Model（内容模型）：定义内容结构的框架
Content Type（内容类型）：不同类型内容的模板
Fields（字段）：内容的具体属性
Entries（条目）：根据模型创建的内容
Assets（资源）：图片、视频等媒体文件
Webhooks（钩子）：内容更新时的自动触发机制
API Keys（API密钥）：访问内容的凭证

熟悉这些概念后，我们就可以开始创建Space了：

Contentful创建Space界面



创建Space后，您不需要手动配置Content Model、Fields等内容。EdgeOne的集成模板已经包含了完整的配置示例，我们可以使用Contentful的命令行工具（contentful-cli）通过导入JSON文件的方式自动生成所有必要的配置（具体的导入细节下文的“生成静态文件”部分会说明）。这样可以确保配置的一致性，并节省手动配置的时间。

3、配置API访问

在开始导入配置之前，我们需要先配置API访问权限。API访问配置是连接Contentful与静态网站生成器的关键，它允许我们通过API安全地获取和管理内容。在Contentful控制台中，进入"Settings" > "API keys"页面，在这里我们可以创建和管理API密钥。


在API配置界面中，您需要特别关注以下信息：
Space ID：位于界面顶部，是您的内容空间的唯一标识
Content Delivery API：用于获取已发布的内容，适合静态网站生成器使用
Content Management API：用于管理内容，在导入配置时会用到
API Endpoint：API的访问地址，通常为 https://cdn.contentful.com
请妥善保存这些信息，它们将在后续的配置中用到。

生成静态文件

前面我们提到将使用contentful-cli来导入默认数据。在开始之前，建议先了解contentful-cli的基本使用。如果您对contentful-cli不熟悉，可以参考contentful-cli官方文档了解更多详情。
下面我们开始操作生成静态文件。首先，下载Contentful集成模板：

1、获取模板

git clone --depth 1 --single-branch https://github.com/TencentEdgeOne/pages-templates.git temp
mv temp/examples/blog-with-retypeset-and-contentful .
rm -rf temp
cd blog-with-retypeset-and-contentful
进入模板目录后，执行以下命令安装依赖 npm install。

2、安装和登陆contentful

接下来，我们需要安装 Contentful CLI工具并登录您的Contentful账号，这一步是为了导入模板提供的博文数据模型。
安装：执行 npm install -g contentful-cli 命令全局安装 Contentful CLI。
登录：安装完成后，执行 contentful login ， CLI 会打开浏览器窗口，请按照提示完成登录操作。

3、导入模型和数据

模板中包含了 contentful-blog-model.json 文件，这是预设的博客内容模型配置。如果您有自己的网站数据结构，可以修改此文件来适配您的需求。本文将以默认的博客模型为例进行说明。
登录后使用以下命令导入配置：
contentful space import --content-file contentful-blog-model.json --space-id ${your space id}
导入完成后，请访问 Contentful管理界面，查看是否已经生成了预设的内容模型和示例数据。如果可以看到这些内容，说明导入成功，我们可以进入下一步：读取Contentful接口数据并生成网页内容。

4、获取Contentful数据

模板已经配置好了Contentful API的访问。您可以通过以下命令测试API连接：
curl -H "Authorization: Bearer $CONTENTFUL_ACCESS_TOKEN" \
     "https://cdn.contentful.com/spaces/$CONTENTFUL_SPACE_ID/entries?content_type=blogPost"
如果配置正确，将返回类似以下的数据：
{
  "sys": {
    "type": "Array"
  },
  "total": 1,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "sys": {
        "id": "example-post",
        "type": "Entry",
        "contentType": {
          "sys": {
            "id": "blogPost"
          }
        }
      },
      "fields": {
        "title": "示例博客文章",
        "slug": "example-post",
        "content": "这是一篇示例博客文章的内容...",
        "publishDate": "2024-03-20T00:00:00.000Z",
        "tags": ["示例", "教程"]
      }
    }
  ]
}
确认API可以正常访问后，如果您想本地验证配置是否正确，可以打开 src/util/contentful.js 文件，填入您的Space ID和Access Token。

然后运行 npm run dev 命令，即可在本地预览网站效果：


注意：上述验证步骤仅用于确认配置是否正确。实际使用时，您不需要修改 src/util/contentful.js 的代码，因为它会自动从EdgeOne控制台配置的环境变量中获取Space ID和Access Token。这样可以避免在代码中暴露您的账户信息，保证了私密性。

部署到EdgeOne Pages

1、代码发布到 Git

将代码提交到git仓库即可完成部署。假设你已经创建了 blog-with-retypeset-and-contentful 项目，并且将当前目录关联到了该项目，使用以下命令提交：
git add .
git commit -m "Initial commit"
git push origin main

2、项目导入 Pages

提交完成后，如果你已经是EdgeOne Pages用户且已关联GitHub账户，访问 控制台 部署对应的项目即可。


3、添加环境变量

点击部署blog-with-retypeset-and-contentful后，在准备部署界面点击"Environment Variables"，分别配置以下环境变量：
CONTENTFUL_SPACE_ID：填入您的Contentful Space ID
CONTENTFUL_PREVIEW_TOKEN：填入您的Contentful Preview Token
CONTENTFUL_DELIVERY_TOKEN：填入您的Contentful Delivery Token


配置完成后，点击"Start Deployment"按钮，等待部署完成后将显示部署成功界面：

至此，我们已经完成了Contentful方案的完整部署流程。通过这个方案，你可以：
使用Contentful管理内容，享受其强大的Headless CMS功能
利用AstroJS生成静态文件，获得极致的访问速度
通过EdgeOne Pages实现自动化部署，简化运维工作
获得全球CDN加速，提升用户体验


更多相关内容

查看更多Contentful集成方案：EdgeOne Pages提供的Contentful模板
了解AstroJS更多功能：AstroJS官方文档
探索Contentful更多功能：Contentful API文档
自定义网站样式：AstroJS主题定制指南