Strapi：开源 Headless CMS 安装与内容 API 搭建指南

Strapi 是开源、可自托管的 Headless CMS，让开发者快速构建内容 API，同时给内容编辑者提供友好的编辑界面。你定义好内容模型，Strapi 就自动生成完整的 REST 与 GraphQL API，供前端、移动 App、IoT 设备直接消费。100% JavaScript/TypeScript，灵活可定制。

一、项目官方信息

核心能力：可视化 Content-Type Builder 定义内容结构、自动生成 REST 与 GraphQL API、开箱即用的细粒度角色权限、内置媒体库、国际化（i18n）、草稿与发布、TypeScript 支持、可扩展插件系统。

二、官方图片

Strapi 官方 Logo：

Strapi 后端请求流程（Routes → Middlewares → Controllers → Services）：

三、环境要求

• Node.js（LTS，Strapi 官方文档列明支持版本）。
• 包管理器 npm/yarn/pnpm。
• 数据库：默认 SQLite（零配置）；生产推荐 PostgreSQL/MySQL/MariaDB。
• 内存：建议至少 2GB。

四、完整部署步骤

1. 用 Quickstart 创建项目

npx create-strapi@latest my-project

该命令会生成一个带默认功能的全新项目：认证、权限、内容管理、Content-Type Builder、文件上传。

2. 进入目录并启动开发服务器

cd my-project
npm run develop

启动后浏览器访问 http://localhost:1337/admin ，首次进入会引导创建管理员账号。

3. 创建管理员账号

在欢迎页填写邮箱、密码、名，即可进入 Strapi 管理后台。

4. 定义内容类型

在后台 Content-Type Builder 中点击「Create new collection type」，例如命名 Article，添加字段：title（文本）、content（富文本）、cover（媒体）、publishedAt（日期）。保存后 Strapi 自动重建并生成对应 API。

5. 录入内容并发布

进入 Content Manager，选择 Article，点击「Create new entry」填写内容，保存后点击「Publish」。

6. 暴露 API

在 Settings → Users & Permissions 里给 Public 角色勾选 Article: find、Article: findOne，保存后即可通过 REST 访问：

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

GraphQL 则访问 http://localhost:1337/graphql 。

7. Docker 部署

Strapi 不提供官方镜像，用社区 CLI 工具基于你的项目生成 Dockerfile 与 docker-compose：

npx @strapi-community/dockerize@latest

也可直接部署到 Strapi Cloud（https://cloud.strapi.io），官方托管含数据库、媒体库与 CDN。

五、使用方法

Content-Type Builder

可视化设计内容结构，无需写代码。支持文本、富文本、数字、布尔、日期、媒体、枚举、关系、组件、动态区等字段。

自动 API

每个内容类型自动生成 REST 与 GraphQL 接口，支持过滤、排序、分页、字段筛选、人口（populate）关联数据。

角色与权限

内置 Users & Permissions 插件，可对 Public/Authenticated 及自定义角色精细配置每个 API 的访问权限。

媒体库

内置媒体库管理上传的图片/文件，支持文件夹、替代文本、预览。

i18n 与草稿发布

开启国际化后内容可按多语言版本管理；Draft & Publish 支持草稿与已发布版本分离。

Strapi AI

内置 AI 层，可自动完成内容建模、媒体 alt 文本、翻译等工作。

六、常见问题 FAQ

1. 启动后访问不了 admin？ 确认 npm run develop 成功启动在 1337 端口；防火墙/反向代理放行；首次需在 /admin 创建管理员账号。

2. 为什么前端调 API 返回 403？ 没有给 Public 角色开放权限。到 Settings → Users & Permissions → Public 勾选对应内容类型的 find/findOne 后保存。

3. 生产环境用什么数据库？ 默认 SQLite 只适合开发/小规模；生产推荐 PostgreSQL 或 MySQL/MariaDB，在配置中切换连接。

4. 如何自定义 API 逻辑？ Strapi 的请求走 Routes → Middlewares → Controllers → Services，可在项目 src/api/ 下自定义 controller/service 覆盖默认行为。

5. 有官方 Docker 镜像吗？ 没有。用社区工具 npx @strapi-community/dockerize 基于项目生成 Dockerfile 与 compose；或直接用 Strapi Cloud。

6. 能用 GraphQL 吗？ 可以。安装 GraphQL 插件后，访问 /graphql 端点即可用 GraphQL 查询内容。

七、跳转链接

• GitHub 仓库：https://github.com/strapi/strapi
• 官方网站：https://strapi.io
• 官方文档：https://docs.strapi.io
• CLI 安装：https://docs.strapi.io/cms/installation/cli
• Strapi Cloud：https://cloud.strapi.io
• 演示模板 LaunchPad：https://github.com/strapi/LaunchPad