Headless CMS对接APP

Headless CMS 与 APP 对接的核心是让移动端通过 API 获取内容。
本文从零基础视角，用 Strapi 作为示例，覆盖 API 权限配置、移动端请求、数据渲染和排错，帮你实现内容 API 输出。

适用场景与前提

如果你的 APP 需要动态展示文章、商品或配置信息，又不希望每次修改都发版，Headless CMS 是合适的选择。
它只负责存储和提供内容，不限制展示层。

你需要准备：

• 一台已安装 Node.js 的服务器或本地环境（建议 Node.js 18 以上，以官方文档为准）
• 一个 Headless CMS 实例，本文以 Strapi 为例，其他如 Directus、Contentful 操作逻辑类似
• 移动端开发环境（Android Studio 或 Xcode）
• 基本的 HTTP 请求知识

第一步：在 CMS 中创建内容类型并开放 API

登录 Strapi 管理后台，默认地址是 http://你的服务器IP:1337/admin。

1. 进入 Content-Type Builder，点击 Create new collection type。
2. 显示名称填 Article，字段添加 title（文本）、content（富文本）、cover（媒体）。
3. 保存后，进入 Settings > Roles > Public。
4. 在 Article 权限下勾选 find 和 findOne，保存。

此时访问 http://你的服务器IP:1337/api/articles，应返回 JSON 数据。
如果返回 403，说明权限未开放。

关键点： 生产环境不要开放 Public 角色的写权限，只读接口建议配合 API Token 使用。

第二步：生成 API Token 并配置请求头

进入 Settings > API Tokens，点击 Create new API Token。

• 名称：mobile-app
• 令牌类型：Read-only
• 有效期：根据需求选择

生成后复制令牌，它只显示一次。
移动端请求时在 Header 中加入：

Authorization: Bearer 你的令牌

这样即使 Public 角色关闭，也能通过令牌读取内容。不要把令牌硬编码在 APP 源码中，建议通过后端中转或使用环境变量。

第三步：移动端发起请求并渲染内容

以 Android Kotlin 为例，使用 Retrofit 请求：

interface ApiService {
    @GET("api/articles")
    suspend fun getArticles(@Header("Authorization") token: String): Response
}

请求 URL 为 http://你的服务器IP:1337/api/articles。
返回数据结构通常包含 data 数组，每个对象有 id、attributes 字段。

解析时注意：Strapi v4 将字段放在 attributes 下，v5 可能调整，建议以实际返回为准。
渲染列表时使用 title 和 content 字段。

验证方式： 在 Postman 或 curl 中先测试接口，确认返回 200 和正确 JSON，再在 APP 中调试。

curl -H "Authorization: Bearer 你的令牌" http://你的服务器IP:1337/api/articles

常见报错与避坑指南

• 403 Forbidden：检查 Public 权限或 API Token 是否有效，确认请求头格式正确。
• CORS 错误：在 Strapi 的 config/middlewares.js 中配置 cors，允许你的 APP 域名或 IP。
• 图片无法显示：检查媒体库字段是否返回完整 URL，移动端需要拼接服务器地址。
• 分页问题：默认返回 25 条，使用 ?pagination[page]=1&pagination[pageSize]=10 控制。
• 生产环境建议：使用 HTTPS，避免明文传输令牌；为 API 设置速率限制。

不要在 APP 中直接使用管理员账号密码，也不要把 Token 提交到公开仓库。

如何验证对接成功

完成上述步骤后，按以下清单检查：

1. 浏览器直接访问 API 地址，能返回 JSON 且包含内容。
2. 使用 curl 带 Token 请求，状态码为 200。
3. 移动端 Logcat 或 Xcode 控制台无网络错误。
4. APP 界面正确显示 CMS 中发布的内容，修改 CMS 后下拉刷新能更新。

如果某一步失败，优先回看权限和网络配置。

常见疑问

Q：Headless CMS 和传统 CMS 对接 APP 有什么区别？
传统 CMS 通常绑定前端模板，API 能力弱；Headless CMS 只提供内容 API，移动端可自由渲染，更适合多端复用。

Q：必须用 Strapi 吗？
不是。Directus、Contentful、Sanity 等都可以，核心是理解 REST 或 GraphQL 的输出格式和鉴权方式。

Q：API 返回的数据字段和文档不一致怎么办？
以实际接口返回为准，不同版本字段结构可能有调整，建议查看官方文档或直接打印响应体。

Q：移动端需要缓存内容吗？
建议对不常变的内容做本地缓存，减少请求次数，提升加载速度。

以上就是 Headless CMS 对接 APP 并输出移动端内容 API 的完整流程。
先从只读接口跑通，再逐步加入缓存和错误处理，遇到问题优先检查权限和网络配置。