部署

🌐 Deployment

Page summary:

部署选项涵盖硬件/软件要求、环境变量设置，以及上线前构建管理面板的步骤，还包括持续部署管道应遵循的原则。在文档中：提供了指向特定供应商和高级指南的链接，帮助选择合适的托管策略。

Strapi 为你的项目或应用提供了多种部署选项。你的 Strapi 应用可以部署在传统托管服务器上，或你偏好的托管提供商上。

🌐 Strapi provides many deployment options for your project or application. Your Strapi applications can be deployed on traditional hosting servers or your preferred hosting provider.

以下文档介绍了如何使用几个常见的托管选项准备 Strapi 以进行部署的基础知识。

🌐 The following documentation covers the basics of how to prepare Strapi for deployment on with several common hosting options.

Strapi Cloud

你可以使用 Strapi Cloud 快速部署和托管你的项目。

🌐 You can use Strapi Cloud to quickly deploy and host your project.

Tip

如果你已经使用内容类型构建器创建了内容结构，并通过内容管理器向本地（开发）Strapi 实例添加了一些数据，你可以利用数据管理系统将数据从一个 Strapi 实例传输到另一个实例。

🌐 If you already created a content structure with the Content-Type Builder and added some data through the Content Manager to your local (development) Strapi instance, you can leverage the data management system to transfer data from a Strapi instance to another one.

另一种可能的工作流程是首先在本地创建内容结构，将项目推送到基于 git 的存储库，将更改部署到生产环境，然后再将内容添加到生产实例。

🌐 Another possible workflow is to first create the content structure locally, push your project to a git-based repository, deploy the changes to production, and only then add content to the production instance.

Caution

对于自托管的 Kubernetes 部署，我们建议使用 npm 而不是 pnpm。pnpm 对依赖的激进提升可能会破坏你的应用依赖的原生模块，比如 mysql2。npm 更平整、更可预测的 node_modules 布局有助于确保原生包正确加载。

🌐 For self-hosted Kubernetes deployments, we recommend using npm rather than pnpm. pnpm aggressive hoisting of dependencies can break native modules, such as mysql2, that your application may rely on. npm flatter, more predictable node_modules layout helps ensure native packages load correctly.

一般指南

🌐 General guidelines

本节讲的是部署 Strapi 所需的硬件、软件和配置要求。

🌐 This section covers the hardware, software, and configuration requirements for deploying Strapi.

硬件和软件要求

🌐 Hardware and software requirements

为了为 Strapi 提供尽可能最佳的环境，以下要求适用于开发（本地）以及登台和生产工作流程。

🌐 To provide the best possible environment for Strapi the following requirements apply to development (local) and staging and production workflows.

在安装 Strapi 之前，你的计算机上必须安装以下要求：

🌐 Before installing Strapi, the following requirements must be installed on your computer:

• Node.js：仅支持 Active LTS or Maintenance LTS versions （目前为 v22、v24 和 v26）。Node 的奇数版本发布，称为 Node.js 的“当前”版本，不受支持（例如 v23、v25）。
• 你首选的 Node.js 包管理器：
  • npm (v6及以上)
  • pnpm （在 Strapi Cloud 上， Corepack 与项目的 package.json packageManager 字段中固定的 pnpm 版本匹配，如果没有固定，则使用 Corepack 打包的默认版本）
• Python （如果使用 SQLite 数据库）
• 受支持的网络浏览器：管理面板的目标浏览器是匹配默认 Browserslist 查询的浏览器：last 3 major versions、Firefox ESR、last 2 Opera versions 和 not dead。请参见 browsersl.ist 了解当前的覆盖矩阵。项目可以在项目根目录下通过 Browserslist 配置覆盖这些默认设置。

• 适用于你的操作系统的标准构建工具（在大多数基于 Debian 的系统上为 build-essentials 包）

• 服务器的硬件规范（CPU、RAM、存储）：

  硬件	推荐	最低
  CPU	2核以上	1核
  内存	4GB以上	2GB
  磁盘	32GB以上	8GB

• 支持的数据库版本：

数据库	推荐	最低
MySQL	8.4	8.0
MariaDB	11.4	10.3
PostgreSQL	17.0	14.0
SQLite	3	3

Strapi 不支持 MongoDB（或任何 NoSQL 数据库），也不支持任何“云原生”数据库（例如 Amazon Aurora、Google Cloud SQL 等）。

🌐 Strapi does not support MongoDB (or any NoSQL databases), nor does it support any "Cloud Native" databases (e.g., Amazon Aurora, Google Cloud SQL, etc.).

Database deployment

有关与 Strapi 一起部署数据库的内容，请参阅 数据库指南。

🌐 Deploying databases along with Strapi is covered in the databases guide.

• 受支持的操作系统：

  操作系统	推荐	最低
  Ubuntu (LTS)	24.04	20.04
  Debian	11.x	10.x
  RHEL	10.x	8.x
  macOS	26.0	11.x
  Windows 桌面	11	10
  Windows 服务器	不支持	不支持

应用配置

🌐 Application Configuration

将 Strapi 应用配置为生产环境需要两个步骤：通过环境变量设置配置，然后构建管理面板并启动服务器。

🌐 Configuring a Strapi application for production takes 2 steps: setting the configuration through environment variables, then building the admin panel and launching the server.

1. 配置

🌐 1. Configure

我们建议根据环境使用环境变量来配置你的应用，例如：

🌐 We recommend using environment variables to configure your application based on the environment, for example:

/config/server.js

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
});

当你创建新项目时，Strapi 会生成一个带有默认值的 .env 文件。你可以编辑此文件或在所选的部署平台中设置变量（参见 示例 .env 文件）：

🌐 Strapi generates a .env file with default values when you create a new project. You can edit this file or set variables in your chosen deployment platform (see example .env file):

HOST=10.0.0.1
PORT=1338

Tip

要了解更多关于配置的详细信息，请参阅 配置 文档。

🌐 To learn more about configuration details, see the configurations documentation.

2. 启动服务器

🌐 2. Launch the server

在生产中运行服务器之前，你需要构建生产管理面板：

🌐 Before running your server in production you need to build your admin panel for production:

yarn

terminal

NODE_ENV=production yarn build

npm

terminal

NODE_ENV=production npm run build

windows

terminal

npm install --save-dev cross-env

然后在你的 package.json 脚本部分：

🌐 Then in your package.json scripts section:

"build:win": "cross-env NODE_ENV=production npm run build",

然后运行：

🌐 And run:

terminal

npm run build:win

使用 production 设置运行服务器：

🌐 Run the server with the production settings:

yarn

terminal

NODE_ENV=production yarn start

npm

terminal

NODE_ENV=production npm run start

windows

terminal

npm install --save-dev cross-env

然后在你的 package.json 脚本部分：

🌐 Then in your package.json scripts section:

"start:win": "cross-env NODE_ENV=production npm run start",

然后运行：

🌐 And run:

terminal

npm run start:win

Caution

我们强烈建议使用像 PM2 这样的进程管理器来管理你的进程。

🌐 We highly recommend using a process manager such as PM2 to manage your process.

如果你需要一个 server.js 文件来运行 node server.js 而不是 npm run start，那么请创建一个 ./server.js 文件，如下所示：

🌐 If you need a server.js file to be able to run node server.js instead of npm run start then create a ./server.js file as follows:

./server.js

const strapi = require('@strapi/strapi');
strapi.createStrapi(/* {...} */).start();

Caution

如果你正在开发一个基于 TypeScript 的项目，必须提供 distDir 选项来启动服务器。 欲了解更多信息，请查阅 TypeScript 文档。

🌐 If you are developing a TypeScript-based project you must provide the distDir option to start the server. For more information, consult the TypeScript documentation.

Health check endpoint

Strapi 在 /_health 提供了一个轻量级的健康检查路径，用于运行时间监控和负载均衡器。当服务器准备就绪时，它会返回一个 HTTP 204 No Content 状态和一个 strapi: You are so French! 头值，你可以使用它来确认应用可访问。

🌐 Strapi exposes a lightweight health check route at /_health for uptime monitors and load balancers. When the server is ready, it responds with an HTTP 204 No Content status and a strapi: You are so French! header value, which you can use to confirm the application is reachable.

高级配置

🌐 Advanced configurations

如果你想将管理界面托管在不同于 API 的服务器上，请查看此专门部分。

🌐 If you want to host the administration on another server than the API, please take a look at this dedicated section.

持续部署

🌐 Continuous deployment

上面描述的构建和启动命令是部署流水线自动执行的步骤。Strapi 不要求使用特定的持续集成工具。任何能够安装依赖、构建管理面板并运行服务器的流水线都可以。这包括 GitHub Actions、GitLab CI、Jenkins 以及你托管服务提供商自己的构建系统。

🌐 The build and start commands described above are the steps a deployment pipeline automates. Strapi does not require a specific continuous integration tool. Any pipeline that can install dependencies, build the admin panel, and run the server works. This includes GitHub Actions, GitLab CI, Jenkins, and your hosting provider's own build system.

以下示例会在每次推送到 main 分支时构建一个 Strapi 项目。它会在构建步骤停止，因为部署步骤取决于你的托管服务提供商：

🌐 The following example builds a Strapi project on every push to the main branch. It stops at the build step, as the deployment step depends on your hosting provider:

.github/workflows/deploy.yml

name: Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: yarn

      - run: yarn install --frozen-lockfile

      # NODE_ENV is set on the build step only: setting it at the job level
      # would skip devDependencies during yarn install
      - run: yarn build
        env:
          NODE_ENV: production
          APP_KEYS: ${{ secrets.APP_KEYS }}
          API_TOKEN_SALT: ${{ secrets.API_TOKEN_SALT }}
          ADMIN_JWT_SECRET: ${{ secrets.ADMIN_JWT_SECRET }}
          JWT_SECRET: ${{ secrets.JWT_SECRET }}
          TRANSFER_TOKEN_SALT: ${{ secrets.TRANSFER_TOKEN_SALT }}
          ENCRYPTION_KEY: ${{ secrets.ENCRYPTION_KEY }}

      # Add your provider's deployment step here, for instance uploading the
      # build output, pushing a Docker image, or triggering a remote deploy.

上面的例子遵循了任何 Strapi 流程都应该遵守的原则，无论你使用哪种工具：

🌐 The example above follows the principles any Strapi pipeline should respect, whichever tool you use:

• 在流水线中构建管理面板，并将 NODE_ENV 设置为 production。管理面板是一个静态包，每当代码或管理配置发生变化时都必须重新构建。
• 从 CI 工具注入密钥，绝不要从已提交的 .env 文件中注入。至少，APP_KEYS、API_TOKEN_SALT、ADMIN_JWT_SECRET、JWT_SECRET、TRANSFER_TOKEN_SALT、ENCRYPTION_KEY 以及数据库凭证必须对构建和运行中的服务器可用（参见 环境配置）。
• 在同一环境的部署中使用相同的秘密。在两次部署之间重新生成 APP_KEYS、ADMIN_JWT_SECRET 或 JWT_SECRET 会使现有的会话和 API 令牌失效。
• 保持环境隔离：测试环境的流程绝不应该指向生产数据库。
• 注意模式同步：使用修改后的内容类型模式启动 Strapi 会更改数据库，删除内容类型会删除其表。在部署到生产环境之前，先查看它带来的更改（参见 数据库迁移）。

Caution

在一个环境中创建的内容类型会随着你的代码一起移动，而不是随着你的数据。内容类型不能在生产环境中创建或更新（参见 FAQ），所以模式更改必须来自已部署的代码。要在环境之间移动内容，请使用 数据管理 功能。

🌐 Content-types created in one environment travel with your code, not with your data. Content-types cannot be created or updated in production (see FAQ), so schema changes must come from the deployed code. To move content between environments, use the Data Management feature.

Tip

Strapi Cloud 会为你处理这个流程：它会在每次向被跟踪的分支推送时 构建和部署，所以不需要任何工作流文件。

部署指南

🌐 Deployment guides

Prerequisites

在按照下面列出的任何指南之前：

🌐 Before following any of the guides listed below:

• 你的 Strapi 项目已创建。
• 你已经阅读了一般部署指南。

以下指南涵盖了在反向代理后面部署 Strapi 以及在进程管理器下运行它的方法：

🌐 The following guides cover serving Strapi behind a reverse proxy and running it under a process manager:

使用 Caddy 进行代理

通过 Caddy 反向代理提供 Strapi 服务，并自动启用 HTTPS。

使用 HAProxy 进行代理

通过 HTTPS 使用 HAProxy 负载均衡器来提供 Strapi 服务。

使用 Nginx 代理

通过 HTTPS 使用 Nginx 反向代理来提供 Strapi 服务。

使用 Traefik 进行代理

通过 Traefik 用 HTTPS 提供容器化的 Strapi 应用。

使用 PM2 进程管理器

用 PM2 保持 Strapi 运行，并在重启后再次启动它。

此外，Strapi 网站的 integrations page 包括关于如何将 Strapi 与许多资源集成的信息，包括如何在以下第三方平台上部署 Strapi。这些指南假设你的代码托管在 GitHub 上：

在 AWS 上部署 Strapi

在 Azure 上部署 Strapi

在 DigitalOcean 应用平台上部署 Strapi

在 Heroku 上部署 Strapi

以下外部指南（非 Strapi 官方维护）可能也有助于在各种环境中部署 Strapi：

🌐 The following external guide(s), not officially maintained by Strapi, might also help deploy Strapi on various environments:

[微软社区] 在 Azure 上部署

Multi-tenancy

如果你在寻找多租户选项，Strapi 博客有一个 comprehensive guide。