常见问题
🌐 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 的文件中。由于 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 upgrade my free Strapi Cloud to a paid plan?
Strapi Cloud 提供免费计划。无论何时，当你准备升级到其中一个 paid plans时，请使用你 Strapi Cloud 项目设置中的 Plans 部分（更多详情请参见 Cloud 文档）。
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 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
在尝试下面的修复之前，请确保你已经在项目中执行了包管理器的安装命令。
🌐 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 中找到
X功能已经可用了吗？
🌐 Is X feature available yet?
你可以查看 public roadmap ，了解当前正在开发的功能请求以及尚未开始的功能请 求，并添加新的功能请求。
Strapi有MCP服务器吗？
🌐 Is there an MCP server for Strapi?
目前没有可用的 MCP (Model Context Protocol) 服务器，但它正在开发中！ 首先，一个用于 Docs 的 MCP 服务器已经在开发中，并且应该很快可用，其他与 AI 相关的工具，包括用于各种 Strapi 操作的额外 MCP 服务器，目前正在讨论中。