常见问题

页面摘要： 常见问题涵盖 Strapi 的常见主题，包括内容类型管理、部署、身份验证、数据库处理、无服务器限制、插件、Docker、SSL 配置、TypeScript 支持和功能可用性。

以下是在使用 Strapi 时可能遇到的最常见问题的解答与解决方案。

为什么我无法在生产/预发布环境中创建或更新内容类型？

Strapi 将模型配置文件（定义模型模式的内容）存储在诸如 ./src/api/restaurant/content-types/restaurant/schema.json 的文件中。由于 Node.js 的工作方式，要使更改生效，需要 Node 重启服务器。这可能会导致你的生产服务停机，并且这些更改也应在某种源代码管理中跟踪。

通常你的开发"流程"会遵循以下路径：

• 开发 - 在本地主机上开发你的 Strapi 应用，然后将更改推送到源代码管理
• 预发布 - 将源代码管理中的更改部署到"类生产"环境进行测试
• 生产 - 如果不需要其他更改，则部署到生产环境
• 根据需要重复，建议你在过程中对应用进行正确的版本控制和测试

目前及未来都没有计划允许在生产环境中创建或更新模型，也暂无计划将模型设置移入数据库。对此没有已知或推荐的变通方案。

Strapi 是否处理内容的部署或迁移？

Strapi 确实提供了一个称为 数据传输 的功能，允许你将一个 Strapi 实例的内容导出和导入到另一个实例，或从文件归档中导出和导入。这对于将内容从一个环境迁移到另一个环境很有用。

用户无法登录管理面板

在 Strapi 3.0 beta 版本发布时，发生了一个根本性变化：最终用户（REST 和 GraphQL 用户）与管理员（管理面板用户）被分离，普通用户无法获得管理面板的访问权限。如果你想了解更多关于此更改的原因，可以阅读 Strapi 关于此事的 博客文章。

Strapi 已发布管理面板与权限（RBAC - 基于角色的访问控制），它确实允许在一定程度上控制用户可在管理面板内访问的内容，并包含一些字段级权限。你还可以为角色授予针对内容类型、单一类型、插件和设置等内容的特定权限。

为什么使用 HTTP 而非 HTTPS 时管理面板登录会失败？

从 v5.24.0 开始，Strapi 管理面板依赖安全的、仅 HTTP 的 cookie 来存储会话数据。浏览器拒绝在不安全的 HTTP 连接上存储或发送这些 cookie，这意味着如果管理面板通过非 HTTPS 提供，则登录无法完成。要恢复访问：

• 在 Strapi 前端终止 TLS（例如使用 Nginx、Caddy、Traefik、负载均衡器或你的云提供方），并通过 HTTPS 暴露管理面板。
• 确保代理转发适当的头部（例如 X-Forwarded-Proto），以便 Strapi 能够检测到安全连接。

使用内置 Strapi 服务器的本地开发仍然有效，因为开发配置不会将 cookie 设置为安全。

为什么我的应用在 PaaS 类服务上的数据库和上传会被重置？

如果你使用 --quickstart 创建 Strapi 项目，默认使用 SQLite 数据库。PaaS 系统（Heroku、DigitalOcean Apps、Google App Engine 等）的文件系统通常是 临时（ephemeral） 或只读的，这意味着每次 dyno（容器）重置时，所有文件系统更改都会丢失。由于 SQLite 和本地上传都存储在文件系统上，自上次 dyno 重置以来对它们所做的任何更改都将被删除。通常 dyno 每天至少重置一次，并且在大多数情况下每天多次重置，或在向这些服务推送新代码时重置。

建议使用 Heroku 的 PostgreSQL 之类的数据库附加组件。对于文件上传，你需要使用 Cloudinary 或 AWS S3 等第三方提供方之一。

如何更改我的 Strapi Cloud 方案？

使用 Strapi Cloud 项目设置中的 方案（Plans） 部分来升级或降级你的方案（参见 Cloud 文档中的 升级到另一个方案 和 降级到另一个方案）。

Strapi 能否在无服务器环境中运行？

由于应用的架构方式，Strapi 不太适合无服务器环境。Strapi 启动时会执行若干操作，可能需要几秒钟。无服务器部署通常要求应用非常快速地冷启动。Strapi 被设计为始终运行的服务，并且在可预见的未来我们不打算缩短冷启动时间。因此，在无服务器环境中运行 Strapi 的体验并不好，因为每个请求的响应需要数秒而非毫秒。选择冷启动还是热启动是许多软件开发人员需要从很早阶段就做出的架构决策，因此请在选择使用 Strapi 时考虑这一点。

我能否将内容管理器的布局配置存储在模型设置中？

目前 Strapi 不支持这一点，已添加 config:dump 和 config:restore 命令，以便在不同部署和环境之间迁移这些设置时更容易。

出于以下几个原因，我们不提供将这些配置存储在模型设置中的能力：

• 在管理界面的内容国际化和翻译情况下会产生冲突。
• 布局可能因角色和权限而不同。
• 虽然无论创建什么内容，模型都是相同的，但贡献界面可以不同。例如，我们有创建一个仅供贡献者的移动应用的想法。标签和布局配置可能因设备和界面而异。

出于所有这些原因以及其他原因，我们认为如果将配置存储在模型设置文件中将是一个错误，并可能让用户感到困惑。最终的解决方案是让跨环境的迁移和部署更简单。

如何自定义插件？

Strapi 使用一个称为 扩展 的系统，因为插件存储在 node_modules 文件夹中。因此，扩展通过 Strapi 利用编程钩子来覆盖插件的某些部分来工作。

我可以添加自己的第三方身份验证提供方吗？

可以，你可以按照以下 文档 操作，也可以查看 users-permissions 代码并提交拉取请求，将该提供方纳入以供所有人使用。最终 Strapi 确实计划从当前的 grant/purest 提供方迁移到类似于上传提供方的拆分式系统。

不过，目前此迁移没有预计时间。

Strapi 是否允许我更改默认的 ID 类型或名称？

目前不行，Strapi 没有能力更改默认 id 名称，也不允许切换数据类型（例如 PostgreSQL 中的 UUID），未来会考虑对此提供支持。

我可以禁用外键创建吗？

Strapi 依赖外键来维护内容类型之间的关系完整性。目前没有受支持的配置选项来禁用外键生成。

如果你的数据库环境限制外键（例如 PlanetScale 或类似不支持外键的分布式数据库），这是一个已知限制。请参阅 Strapi 仓库上的 相关讨论 了解背景和社区分享的变通方案。

对于需要无外键模式的数据库环境，请考虑将 Strapi 与完全支持外键的数据库（PostgreSQL、MySQL、MariaDB 或 SQLite）一起使用。

能否对动态区域和多态关系进行过滤和/或深度过滤？

目前我们不计划允许对动态区域或多态关系进行过滤，因为这样做会带来各种复杂性和性能问题。

如何在 Strapi 中配置 SSL？

Strapi 本身不实现任何 SSL 方案，这是因为直接以低端口将 Node.js 应用暴露到公共网络极其不安全。

在基于 Linux 的操作系统上，你需要 root 权限才能绑定到 1024 以下的任何端口，而典型 SSL 端口为 443，因此你需要以 root 身份运行应用。

同样，由于 Strapi 基于 Node.js，要使 SSL 证书的更改生效（例如证书过期时），你需要重启应用才能使更改生效。

由于这两个问题，建议使用代理应用（如 Nginx、Caddy、HAProxy、Apache、Traefik 或许多其他工具）来处理到 Strapi 的边缘路由。服务器配置 有一个用于上游代理的 proxy 块。将 proxy.koa 设置为信任转发的头部，并将 proxy.maxIpsCount 设置为 Strapi 前面的代理数量。proxy.ipHeader 是可选的，默认值为 X-Forwarded-For。然后，身份验证提供方和上传插件等后端插件会根据 url 选项而非 localhost:1337 构建其 URL。

我可以在 Strapi 项目中使用 TypeScript 吗？

从 v4.2.0-beta.1 起，Strapi 项目支持 TypeScript。核心开发者文档中提供了 TypeScript 代码示例，并有一个 专用的 TypeScript 支持页面。

如何修复构建错误 Error: Cannot find module @strapi/XXX

Strapi 当前版本需要依赖提升（hoisting）。

默认情况下，大多数包管理器都启用了 hoisting，但如果它未按预期工作，你可以尝试通过包管理器的配置强制启用。

• 如果你使用的是 npm 或 pnpm：在你的项目的 .npmrc 文件中添加 hoist=true。详情请查阅 pnpm 官方文档
• 如果你使用的是 Yarn：在你的 .yarnrc 文件中设置 nmHoistingLimits。更多细节请查阅 Yarn 官方文档

如何为管理面板贡献翻译？

你正在阅读的文档在 strapi/documentation 仓库中以英文编写和审阅。这里的这些 Markdown 页面没有单独的社区翻译流程。

如果你想修复已发布语言区域（例如不完整的简体中文标签）的内置管理界面字符串，请向 Strapi monorepo 提交拉取请求。核心键位于 packages/core/admin/admin/src/translations/ 下的 JSON 文件中，其他带有管理 UI 的包或插件在其自有文件夹中附带同级的 translations 目录。请遵循该仓库的 CONTRIBUTING.md（需要 CLA），并将每次更改限定在你所改进的本地化文件范围内，以便审阅者验证语言。

如果你只需要在单个项目内修改措辞而无需上游合并，请按照管理面板自定义指南中的说明使用 src/admin/app 中的 config.translations。

X 功能是否已可用？

你可以查看 公开路线图，了解当前正在处理哪些功能请求、哪些尚未开始，并添加新的功能请求。

为什么 Strapi 不提供官方 Docker 镜像？

Strapi 是一个用于构建许多不同类型应用的框架。单个 Docker 镜像无法涵盖所有使用场景，因此 Strapi 改为提供 Dockerfile 示例。详情请参阅 Docker 安装指南。

为什么在 Docker 中为开发和生产使用不同的 Dockerfile？

Strapi 使用 React 构建管理面板，并在构建过程中将其打包进应用。Strapi 后端作为 Web 服务器提供管理面板，并且以下环境变量被静态编译到构建后的管理面板中：

• STRAPI_ADMIN_BACKEND_URL
• ADMIN_PATH（如果使用自定义管理路径）

由于这些值在构建时就被固化，你必须将它们作为 ARG 传入 Dockerfile，或在它们更改时重新构建镜像。否则，管理面板可能会指向 localhost:1337 而非你的生产 URL。

此外，开发镜像未针对性能进行优化，不应暴露到公共互联网。为每个环境构建单独的 Docker 镜像可确保正确的配置和更好的安全性。

有关完整的 Dockerfile 示例，请参阅 Docker 安装指南。

Strapi 是否有 MCP 服务器？

有。Strapi 包含一个内置的 模型上下文协议 (MCP) 服务器，向 AI 客户端暴露内容管理工具。有关配置和使用详情，请参阅 MCP 服务器功能页面。

还有一个单独的 文档 MCP 服务器 可用于查询 Strapi 文档。