Skip to main content

常见问题

¥Frequently Asked Questions

以下是你在使用 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.txt 之类的文件中。由于 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.

一般来说，你的 "flow" 开发会遵循以下路径：

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

  • 开发 - 在主机上本地开发 Strapi 应用，然后将更改推送到源代码管理中

    ¥Development - Develop your Strapi application locally on your host machine, then push changes into source control

  • 分期 - 将更改从源代码管理部署到 "production-like" 环境以进行测试

    ¥Staging - Deploy changes from source control to a "production-like" environment for testing

  • 生产 - 如果不需要其他更改，则部署到生产中

    ¥Production - If no other changes are needed, deploy into production

  • 根据需要重复，建议你正确版本化并测试你的应用

    ¥Repeat as needed, it is recommended that you properly version and test your application as you go

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

¥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 博客文章。

¥With the release of the Strapi 3.0 beta version a fundamental change occurred in that the end users (REST and GraphQL users) were split from the Administrators (admin panel users) in such a way that normal users can not be given access to the admin panel. If you would like to read more on why this change was done, you can read the Strapi blog post about it.

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.

为什么我的应用的数据库和上传在 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 重置以来对这些内容所做的任何更改都将被删除。通常，测功机每天至少重置一次，在大多数情况下，每天或在将新代码推送到这些服务时重置多次。

¥If you used --quickstart to create your Strapi project, by default this uses the SQLite database. PaaS systems (Heroku, DigitalOcean Apps, Google App Engine, etc.) file systems are typically ephemeral or read-only meaning that each time a dyno (container) is reset all filesystem changes are lost. And since both SQLite and local uploads are stored on the filesystem, any changes made to these since the last dyno reset will be deleted. Typically dynos are reset at least once a day, and in most cases multiple times per day or when new code is pushed to these services.

建议你使用数据库插件，例如 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 upgrade my free Strapi Cloud to a paid plan?

Strapi Cloud 提供免费计划。当你准备升级到 付费计划 之一时，请使用 Strapi Cloud 项目设置的“计划”部分（更多详情请参阅 云文档）。

¥Strapi Cloud provides a free plan. Whenever you're ready to upgrade to one of the paid plans, please use the Plans section of your Strapi Cloud project's settings (see Cloud documentation for more details).

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.

我可以将 Content Manager 布局配置存储在模型设置中吗？​

¥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:

  • 如果管理界面中的内容国际化和翻译会产生冲突。

    ¥It will create conflicts in case of content internationalization and translations in the admin interface.

  • 根据角色和权限，布局可能会有所不同。

    ¥The layout might be different according to the roles and permissions.

  • 尽管无论创建什么内容，模型都是相同的，但贡献界面可能不同。例如，我们有一个想法：为贡献者创建一个移动应用。根据设备和接口的不同，标签和布局配置可能会有所不同。

    ¥While the model is the same whatever the content created, the contribution interface can be different. For instance, we have an idea to create a mobile application for contributors only. The labels and layout configurations could be different according the device & interface.

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

¥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.

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

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

是的，你可以遵循以下 documentation，也可以查看 users-permissions 代码并提交拉取请求以包含每个人的提供程序。最终 Strapi 确实计划从当前的资助/最纯粹的提供者转向类似于上传提供者的分裂性质系统。

¥Yes, you can either follow the following documentation or you can take a look at the users-permissions code and submit a pull request to include the provider for everyone. Eventually Strapi does plan to move from the current grant/purest provider to a split natured system similar to the upload providers.

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

¥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 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、球童、HAProxy、Apache、Traefik 或许多其他应用）来处理到 Strapi 的边缘路由。环境 server.json 中有一些设置可以处理上游代理。代理块需要填写所有设置，并将修改任何后端插件，例如身份验证提供程序和上传插件，以将标准 localhost:1337 替换为代理 URL。

¥Due to these two issues, it is recommended you use a proxy application such as Nginx, Caddy, HAProxy, Apache, Traefik, or many others to handle your edge routing to Strapi. There are settings in the environment server.json to handle upstream proxies. The proxy block requires all settings to be filled out and will modify any backend plugins such as authentication providers and the upload plugin to replace your standard localhost:1337 with the proxy URL.

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

¥Can I use TypeScript in a Strapi project?

从 v4.2.0-beta.1 开始，Strapi 项目就支持 TypeScript TypeScript 代码示例可在整个核心开发者文档和 专用 TypeScript 支持页面.1 中找到。

¥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

提醒

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

¥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 文件中。从 官方 pnpm 文档 了解更多信息

    ¥If you are using npm or pnpm: Add hoist=true to your project's .npmrc file. Learn more about this from the official pnpm documentation

  • 如果你使用的是 Yarn：在你的 .yarnrc 文件中设置 nmHoistingLimits。更多详细信息，请参阅 Yarn 官方文档

    ¥If you are using Yarn: Set nmHoistingLimits in your .yarnrc file. More details can be found in the Yarn official documentation

X 功能可用了吗？​

¥Is X feature available yet?

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

¥You can see the public roadmap to see which feature requests are currently being worked on and which have not been started yet, and to add new feature requests.

Strapi 有 MCP 服务器吗？​

¥Is there an MCP server for Strapi?

目前没有可用的 MCP (模型上下文协议) 服务器，但正在开发中！首先，用于 Docs 的 MCP 服务器已在开发中，应该很快就会推出，其他 AI 相关工具，包括用于各种 Strapi 操作的附加 MCP 服务器，目前正在讨论中。

¥There’s currently no MCP (Model Context Protocol) server available, but it’s in the works! First, an MCP server for Docs is already in development and should be available soon, and other AI-related tools, including additional MCP servers for various Strapi actions, are currently under discussion.