常见问题

🌐 Frequently asked questions

Page summary:

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

🌐 Frequently asked questions covering common Strapi topics including content-type management, deployment, authentication, database handling, serverless limitations, plugins, Docker, SSL configuration, TypeScript support, and feature availability.

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

🌐 Below are answers and solutions to most common issues that you may experience when working with Strapi.

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

🌐 Why can't I create or update content-types in production/staging?

Strapi 将模型配置文件（定义模型架构的文件）存储在诸如 ./src/api/restaurant/content-types/restaurant/schema.json 的文件中。由于 Node.js 的工作方式，为了使更改生效，必须重新启动 Node 服务器。这可能会导致生产服务的停机，同样，这些更改应该在某种源代码管理中进行跟踪。

🌐 Strapi stores model configuration files (what defines the model schema) in files such as ./src/api/restaurant/content-types/restaurant/schema.json. Due to how Node.js works, in order for changes to take effect, that would require Node to restart the server. This could potentially cause downtime of your production service and likewise these changes should be tracked in some kind of source control.

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

🌐 Generally your "flow" of development would follow the following path:

• 开发 - 在本地主机上本地开发你的 Strapi 应用，然后将更改推送到源代码管理
• 暂存 - 将源代码控制中的更改部署到“类似生产”的环境中进行测试
• 生产 - 如果不需要其他更改，请部署到生产环境
• 根据需要重复，建议你正确版本化并测试你的应用

在此时及未来，没有计划允许在生产环境中创建或更新模型，并且目前也没有计划将模型设置迁移到数据库中。对此没有已知或推荐的解决方法。

🌐 At this time and in the future there is no plan to allow model creating or updating while in a production environment, and there is currently no plans to move model settings into the database. There are no known nor recommended workarounds for this.

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

🌐 Does Strapi handle deploying or migrating of content?

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

🌐 Strapi does offer a feature known as Data Transfer that allows you to export and import content from one Strapi instance to another or exporting and importing from a file archive. This is useful for migrating content from one environment to another.

用户无法登录管理面板

🌐 User can't login to the admin panel

随着 Strapi 3.0 测试版的发布，发生了一个根本性的变化，即终端用户（REST 和 GraphQL 用户）与管理员（管理面板用户）被分开，以至于普通用户无法被授予访问管理面板的权限。如果你想了解更多关于此更改原因的信息，你可以阅读 Strapi blog post 关于它的介绍。

Strapi 已发布了管理员和权限（RBAC - 基于角色的访问控制），它允许在一定程度上控制用户在管理员面板中可以访问的内容，并包括一些字段级别的权限。你还可以为角色赋予特定权限，例如内容类型、单一类型、插件和设置。

🌐 Strapi has released the Admin & Permissions (RBAC - Role-Based Access Control) that does allow for some degree of control over what users can access within the admin panel and includes some field level permissions. You can also give roles specific permissions for things like content-types, single types, plugins, and settings.

当我使用 HTTP 而不是 HTTPS 时，为什么管理员登录会失败？

🌐 Why does the admin login fail when I use HTTP instead of HTTPS?

从 v5.24.0 开始，Strapi 管理面板依赖安全的、仅限 HTTP 的 Cookie 来存储会话数据。浏览器拒绝在不安全的 HTTP 连接下存储或发送这些 Cookie，这意味着如果面板在没有 HTTPS 的情况下提供服务，管理员登录将无法完成。要恢复访问:

🌐 Starting from v5.24.0, the Strapi admin panel relies on secure, HTTP-only cookies to store session data. Browsers refuse to store or send these cookies over insecure HTTP connections, which means the admin login cannot complete if the panel is served without HTTPS. To restore access:

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

使用内置 Strapi 服务器的本地开发仍可正常工作，因为开发配置未将 cookie 设置为安全。

🌐 Local development using the built-in Strapi server continues to work because the development configuration does not set the cookies as secure.

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

🌐 Why are my application's database and uploads resetting on PaaS-type services?

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

建议你使用像 Heroku 的 PostgreSQL 这样的数据库插件。对于文件上传，你将需要使用第三方提供商之一，例如 Cloudinary 或 AWS S3。

🌐 It is recommended you use a database add-on like Heroku's PostgreSQL. For file uploads, you will need to use one of the 3rd party providers such as Cloudinary or AWS S3.

我如何更改我的 Strapi Cloud 计划？

🌐 How can I change my Strapi Cloud plan?

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

🌐 Use the Plans section of your Strapi Cloud project's settings to upgrade or downgrade your plan (see Upgrading to another plan and Downgrading to another plan in the Cloud documentation).

Strapi 可以在无服务器环境中运行吗？

🌐 Can Strapi be run in serverless environments?

由于应用的结构，Strapi 并不适合无服务器环境。Strapi 在启动时会执行多个操作，这些操作可能需要几秒钟的时间。而无服务器部署通常要求应用能够非常快速地冷启动。Strapi 设计为始终运行的服务，我们在可预见的未来没有计划减少冷启动时间。因此，在无服务器环境中运行 Strapi 体验不佳，因为每个请求的响应时间将是几秒而不是几毫秒。在冷启动和热启动之间进行选择是许多软件开发者需要从非常早期阶段做出的架构决策，因此在选择使用 Strapi 时请考虑这一点。

🌐 Strapi is not well suited for serverless environments due to how the application is structured. Several actions happen while Strapi is booting that can take several seconds. Serverless deployment usually requires an application to cold boot very quickly. Strapi is designed to run as an always-on service, and we don't plan to decrease the cold boot time for the foreseeable future. Therefore, running Strapi in serverless environments is not a great experience, as every request will take seconds to respond to instead of milliseconds. Choosing between a cold boot or a warm boot is an architectural decision that many software developers need to take from a very early stage, so please consider this when choosing to use Strapi.

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

🌐 Can I store my Content Manager layout configurations in the model settings?

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

🌐 Currently Strapi does not support this, a config:dump and config:restore command has been added to make migration of these settings easier when moving between different deployments and environments.

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

🌐 We don't offer the ability to store these configurations in the model settings for several reasons:

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

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

🌐 For all these reasons, and others, we think it'll be a mistake and might confuse users if we store the configuration in the model settings file. The final solution is to make the migration and deployment across environment easier.

我如何自定义一个插件？

🌐 How do I customize a plugin?

Strapi 使用一个名为 extension 的系统，因为插件存储在 node_modules 文件夹中。由于这些扩展的工作原理是 Strapi 利用编程钩子来覆盖插件的某些部分。

🌐 Strapi uses a system called extension as plugins are stored in the node_modules folder. Due to this extensions work by Strapi utilizing programmatic hooks to override certain parts of the plugin.

我可以添加我自己的第三方认证提供者吗？

🌐 Can I add my own 3rd party auth provider?

是的，你可以按照以下的文档操作，或者你可以查看 users-permissions 代码并提交一个拉取请求，以便为所有人包含该提供者。最终，Strapi 确实计划从当前的 grant/purest 提供者迁移到类似上传提供者的分离式系统。

不过，目前尚无此迁移的预计到达时间。

🌐 There is currently no ETA on this migration however.

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

🌐 Does Strapi allow me to change the default ID type or name?

不可以，目前无法允许更改默认 id 名称，也不允许你切换数据类型（例如 PostgreSQL 中的 UUID），将来会考虑对此的支持。

🌐 No, currently does not have the ability to allow for changing the default id name nor does it allow you to switch the data type (such as UUID in PostgreSQL), support for this is being looked at in future.

我可以禁用外键创建吗？

🌐 Can I disable foreign key creation?

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

🌐 Strapi relies on foreign keys to maintain relational integrity between content types. There is currently no supported configuration option to disable foreign key generation.

如果你的数据库环境限制外键（例如，PlanetScale 或类似不支持外键的分布式数据库），这是一个已知的限制。请参阅 Strapi 仓库上的 related discussion ，了解社区分享的背景信息和解决方法。

对于需要无外键架构的环境，考虑使用 Strapi 结合完全支持外键的数据库（PostgreSQL、MySQL、MariaDB 或 SQLite）。

🌐 For environments that require foreign key-free schemas, consider using Strapi with a database that fully supports foreign keys (PostgreSQL, MySQL, MariaDB, or SQLite).

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

🌐 Can you filter and/or deep filter on dynamic zones and polymorphic relations?

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

🌐 At this time we do not plan to allow for filtering on dynamic zones or polymorphic relations due to various complexity and performance issues that come from doing so.

我如何在 Strapi 中设置 SSL？

🌐 How do I setup SSL with Strapi?

Strapi 本身没有实现 SSL 解决方案，这是因为直接在低端口上向公共网络提供 Node.js 应用是极其不安全的。

🌐 Strapi implements no SSL solution natively, this is due to the fact that it is extremely insecure to directly offer a Node.js application to the public web on a low port.

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

🌐 On Linux based operating systems you need root permissions to bind to any port below 1024 and with typical SSL being port 443 you would need to run your application as root.

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

🌐 Likewise since Strapi is Node.js based, in order for changes with the SSL certificate to take place (say when it expires) you would need to restart your application for that change to take effect.

由于这两个问题，建议你使用代理应用，例如 Nginx、 Caddy、 HAProxy、Apache、Traefik或其他许多应用来处理到Strapi的边缘路由。在环境 server.json 中有设置可处理上游代理。代理块要求填写所有设置，并且会修改任何后端插件，例如身份验证提供程序和上传插件，将你的标准 localhost:1337 替换为代理URL。

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

🌐 Can I use TypeScript in a Strapi project?

从 v4.2.0-beta.1 起，Strapi 项目支持 TypeScript。在核心开发者文档的各处都可以找到 TypeScript 代码示例，以及一个专门的 TypeScript 支持页面。

🌐 TypeScript is supported in Strapi projects from v4.2.0-beta.1 TypeScript code examples are available throughout the core Developer Documentation and a dedicated TypeScript support page.

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

🌐 How to fix the build error Error: Cannot find module @strapi/XXX

Caution

在尝试下面的修复之前，请确保你已经在项目中执行了包管理器的安装命令。

🌐 Before trying the fix below, ensure you've executed your package manager's install command in your project.

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

🌐 Strapi in its current version requires dependency hoisting.

默认情况下，大多数包管理器都启用提升，但是，如果它没有按预期运行，你可以尝试通过包管理器的配置强制执行它。

🌐 By default, most package managers enable hoisting, however, if it's not functioning as expected, you can try enforcing it via your package manager's configuration.

• 如果你正在使用 npm 或 pnpm：将 hoist=true 添加到你项目的 .npmrc 文件中。你可以从 official pnpm documentation 了解更多信息
• 如果你正在使用 Yarn：在你的 .yarnrc 文件中设置 nmHoistingLimits。更多详细信息可以在 Yarn official documentation 中找到

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

🌐 How can I contribute translations for the admin panel?

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

🌐 The documentation you are reading is written and reviewed in English in the strapi/documentation repository. There is no separate community translation workflow for these Markdown pages here.

如果你想修复已发布本地化语言的内置管理接口字符串（例如简体中文标签不完整），请在 Strapi monorepo 提交一个拉取请求。核心键位于 packages/core/admin/admin/src/translations/ 下的 JSON 文件中，其它带有管理界面的包或插件会在各自的文件夹中提供对应的 translations 目录。请遵循该仓库的 CONTRIBUTING.md（需要签署 CLA），并将每次更改仅限于你正在改进的本地化文件，以便审查者能够验证语言内容。

🌐 If you want to fix built-in admin interface strings for a shipped locale (for example incomplete Simplified Chinese labels), open a pull request against the Strapi monorepo. Core keys live in JSON files under packages/core/admin/admin/src/translations/, and other packages or plugins with an admin UI ship sibling translations directories in their own folders. Follow that repository's CONTRIBUTING.md (CLA required) and keep each change scoped to the locale files you are improving so reviewers can verify the language.

如果你只需要在一个项目中更改措辞而不将其上游，按照管理员自定义指南中的说明使用 config.translations 在 src/admin/app。

🌐 If you only need wording changes inside one project without upstreaming them, use config.translations in src/admin/app as described in the admin customization guide.

X功能已经可用了吗？

🌐 Is X feature available yet?

你可以查看 public roadmap ，了解当前正在开发的功能请求以及尚未开始的功能请求，并添加新的功能请求。

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

🌐 Why doesn't Strapi provide official Docker images?

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

🌐 Strapi is a framework used to build many different types of applications. A single Docker image cannot cover all use cases, so Strapi provides Dockerfile examples instead. See the Docker installation guide for details.

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

🌐 Why use different Dockerfiles for development and production with Docker?

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

🌐 Strapi builds the admin panel with React and bundles it into the application during the build process. The Strapi backend serves the admin panel as a web server, and the following environment variables are statically compiled into the built admin panel:

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

因为这些值在构建时就已经内置，所以你必须在 Dockerfile 中将它们作为 ARG 传入，或者在它们改变时重建镜像。如果不这样做，管理面板可能会指向 localhost:1337 而不是你的生产 URL。

🌐 Because these values are baked in at build time, you must either pass them as ARG in your Dockerfile or rebuild the image when they change. Without this, the admin panel may point to localhost:1337 instead of your production URL.

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

🌐 Additionally, development images are not optimized for performance and should not be exposed to the public internet. Building separate Docker images for each environment ensures correct configuration and better security.

请参阅 Docker 安装指南 了解完整的 Dockerfile 示例。

🌐 See the Docker installation guide for full Dockerfile examples.

Strapi有MCP服务器吗？

🌐 Is there an MCP server for Strapi?

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

🌐 Yes. Strapi includes a built-in Model Context Protocol (MCP) server that exposes content management tools to AI clients. See the MCP server feature page for configuration and usage details.

还可以使用单独的 Docs MCP 服务器 来查询 Strapi 文档。

🌐 A separate Docs MCP server is also available for querying the Strapi documentation.