Strapi 5 入门：安装、内容建模与 API 权限

Strapi 是一个 Headless CMS：后台负责内容模型、编辑流程和 API，网站或 App 负责展示。入门时最重要的不是先安装插件，而是先判断内容应该建成 Collection Type、Single Type、Component 还是 Dynamic Zone。

本文合并了本站旧版安装、后台语言和内容模型短文，示例以 Strapi 5 为准。

目录

• 创建 Strapi 5 项目
• 四种内容结构怎么选
  • Collection Type：可重复的独立内容
  • Single Type：全站只有一份的数据
  • Component：可复用的字段组合
  • Dynamic Zone：编辑者可组合的内容区块
• 建模前先回答五个问题
• 发布内容与 API 权限
• 为什么关联字段没有返回
• 推荐项目结构
• 上线前检查
• 参考资料

创建 Strapi 5 项目

准备受支持的 Node.js 版本和数据库环境后执行：

npx create-strapi@latest my-cms
cd my-cms
npm run develop

只想快速体验可以使用官方 quickstart 方式，但正式项目应在创建时明确数据库、部署环境和版本策略。首次启动后创建管理员账号；后台语言属于个人资料偏好，不影响 API 返回内容的 locale。

升级旧教程时不要机械复制 app.example.tsx 等路径。管理面板扩展方式会随主版本变化，应以当前 Strapi 官方文档 为准。

四种内容结构怎么选

Collection Type：可重复的独立内容

适合文章、作者、产品、分类等拥有多条记录的实体。

例如 Article：

• title：Text，必填。
• slug：UID，关联 title。
• excerpt：Text。
• content：Rich Text 或 Blocks。
• cover：Media，单图。
• author：Relation，关联 Author。
• category：Relation，关联 Category。

如果某种内容需要独立 URL、独立权限或被其他内容关联，通常应使用 Collection Type。

Single Type：全站只有一份的数据

适合网站设置、关于页、首页配置等全局内容。它们只有一个文档，不需要创建多条记录。

不要为了省事把所有设置塞进一个超大的 Single Type。权限、发布频率或维护人员不同的配置应该拆分。

Component：可复用的字段组合

组件不是独立内容实体，它嵌入所属文档中。适合 SEO 字段、地址、按钮、图片加说明等重复结构。

SEO Component
├── metaTitle
├── metaDescription
├── shareImage
└── noIndex

如果内容需要跨文章独立更新并保持同一份数据，应改用 Relation，而不是 Component。

Dynamic Zone：编辑者可组合的内容区块

适合落地页和模块化正文，例如 Hero、图文区块、FAQ、引用卡片。编辑者可以选择区块类型并调整顺序。

Dynamic Zone 灵活，但也会增加前端渲染分支。只有确实需要编辑者自由组合时才使用；结构固定的文章正文不必为了“以后可能用到”提前复杂化。

建模前先回答五个问题

1. 这种内容有一条还是多条？
2. 是否需要独立 URL、权限和发布状态？
3. 数据是复制到每篇内容，还是保持共享引用？
4. 编辑者是否需要自由调整模块顺序？
5. 前端列表和详情页实际需要哪些字段与关联？

先画出简单关系图再建模，比建完数据后频繁改字段安全得多。

发布内容与 API 权限

创建并发布一篇文章后，请求：

GET http://localhost:1337/api/articles

如果返回 403，通常不是接口不存在，而是 Public 角色没有读取权限。可以在后台的角色权限中只开放确实需要公开的 find、findOne，或由服务端使用范围受限的 API Token。

不要为了调通接口给 Public 角色开放创建、修改和删除权限。管理端管理员权限、用户角色权限和 API Token 是不同的安全边界。

为什么关联字段没有返回

Strapi REST API 默认不自动展开关联、媒体和组件。需要使用 populate 明确声明：

GET /api/articles?populate[cover]=true&populate[author]=true

复杂页面不要长期使用 populate=*。具体的字段选择、嵌套关系与性能边界见 Strapi 5 populate 完整指南。

推荐项目结构

src/
├── api/          # 内容类型、controller、service、route
├── components/   # Strapi Components
├── extensions/   # 插件扩展
└── admin/        # 管理面板定制

业务规则优先放在 service 或明确的 domain 层，controller 负责验证请求和组织响应。不要把敏感规则只写在前端，因为 API 可以被绕过直接调用。

上线前检查

• 数据库是否使用持久化存储并有备份。
• .env、API Token 和数据库凭据是否由部署环境注入。
• Public 角色是否只开放必要的读权限。
• 是否为列表 API 设置分页和字段限制。
• 媒体文件是否使用适合生产环境的持久化存储。
• 主版本升级前是否阅读迁移文档并备份数据库。

准备连接前端时，可以继续阅读 Next.js 与 Strapi 数据获取指南。

参考资料

• Strapi 5 官方文档
• Strapi Content-Type Builder
• Strapi REST API