在 Docker 中运行 Strapi 5 — 完整中文指南
#

概览
#

本指南介绍如何使用 Docker 容器运行已有的 Strapi 5 项目。包含开发/暂存（development/staging）与生产（production）两类示例 Dockerfile、docker-compose 示例（支持 MySQL / MariaDB / PostgreSQL）、必要的环境变量说明、构建与发布镜像的常见命令，以及推荐的社区工具。

注意：Strapi 官方不维护任何通用的容器镜像。以下示例为社区实践示范，仅作参考。如有疑问请到 Strapi 社区 Discord 提问。

警告：Strapi 应用不应连接到非由 Strapi 创建的现有数据库，也不应直接连接到 Strapi v3 的数据库。这样做可能导致数据丢失（例如表被删除），Strapi 团队对这种不受支持的连接不提供支持。

先决条件
#

已安装 Docker：https://www.docker.com/
支持的 Node.js 版本（参见 Strapi 文档）
一个已存在的 Strapi 5 项目，或使用 Quick Start 新建项目
（可选）Yarn
（可选）Docker Compose

必需的环境变量
#

下面这些环境变量是运行 Strapi 容器时通常需要设置的：

变量名	说明
NODE_ENV	应用运行环境（development / production）
DATABASE_CLIENT	使用的数据库客户端（mysql / postgres / mariadb 等）
DATABASE_HOST	数据库主机
DATABASE_PORT	数据库端口
DATABASE_NAME	数据库名称
DATABASE_USERNAME	数据库用户名
DATABASE_PASSWORD	数据库密码
JWT_SECRET	Users-Permissions 插件签名 JWT 的密钥
ADMIN_JWT_SECRET	Admin 面板 JWT 签名密钥
APP_KEYS	用于签名 session cookies 的密钥列表

还可以设置其他可选环境变量，详见 Strapi 环境配置文档。

开发 / 暂存环境
#

在本地或暂存环境下，你可以使用一个较简单的 Dockerfile 来构建非生产镜像；若需要数据库也可用 docker-compose 启动数据库容器。

提示：如果使用 docker-compose，可以在 compose 文件或 .env 中定义环境变量，无需手动传入。

开发 Dockerfile（npm 示例）
#

文件：./Dockerfile

FROM node:22-alpine

# 安装 libvips 及构建依赖（用于 sharp）
RUN apk update && apk add --no-cache build-base gcc autoconf automake zlib-dev libpng-dev nasm bash vips-dev git

ARG NODE_ENV=development
ENV NODE_ENV=${NODE_ENV}

WORKDIR /opt/
COPY package.json package-lock.json ./

RUN npm install -g node-gyp
RUN npm config set fetch-retry-maxtimeout 600000 -g && npm install

ENV PATH=/opt/node_modules/.bin:$PATH
WORKDIR /opt/app
COPY . .
RUN chown -R node:node /opt/app
USER node
RUN ["npm", "run", "build"]
EXPOSE 1337
CMD ["npm", "run", "develop"]

可选：docker-compose（带数据库）
#

下面给出三种常见数据库的 docker-compose 示例。所有示例都将 Strapi 服务命名为 strapi，数据库服务命名为 strapiDB，并使用一个共享 volume 保存数据库数据。

使用 MySQL（示例）

文件：./docker-compose.yml

version: "3"
services:
  strapi:
    container_name: strapi
    build: .
    image: strapi:latest
    restart: unless-stopped
    env_file: .env
    environment:
      DATABASE_CLIENT: ${DATABASE_CLIENT}
      DATABASE_HOST: strapiDB
      DATABASE_PORT: ${DATABASE_PORT}
      DATABASE_NAME: ${DATABASE_NAME}
      DATABASE_USERNAME: ${DATABASE_USERNAME}
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}
      JWT_SECRET: ${JWT_SECRET}
      ADMIN_JWT_SECRET: ${ADMIN_JWT_SECRET}
      APP_KEYS: ${APP_KEYS}
      NODE_ENV: ${NODE_ENV}
    volumes:
      - ./config:/opt/app/config
      - ./src:/opt/app/src
      - ./package.json:/opt/package.json
      - ./yarn.lock:/opt/yarn.lock
      - ./.env:/opt/app/.env
      - ./public/uploads:/opt/app/public/uploads
    ports:
      - "1337:1337"
    networks:
      - strapi
    depends_on:
      - strapiDB

  strapiDB:
    container_name: strapiDB
    platform: linux/amd64 # 针对 Apple M1 芯片平台问题
    restart: unless-stopped
    env_file: .env
    image: mysql:8.0
    command: --default-authentication-plugin=mysql_native_password
    environment:
      MYSQL_USER: ${DATABASE_USERNAME}
      MYSQL_ROOT_PASSWORD: ${DATABASE_PASSWORD}
      MYSQL_PASSWORD: ${DATABASE_PASSWORD}
      MYSQL_DATABASE: ${DATABASE_NAME}
    volumes:
      - strapi-data:/var/lib/mysql
    ports:
      - "3306:3306"
    networks:
      - strapi

volumes:
  strapi-data:

networks:
  strapi:
    name: strapi
    driver: bridge

使用 MariaDB（示例）

只需将 strapiDB.image 改为 mariadb:latest，其余配置类似：

# 省略重复部分，参考 MySQL 示例，将 image: mysql:8.0 替换为 image: mariadb:latest

使用 PostgreSQL（示例）

# 省略重复部分，数据库服务改为：
  strapiDB:
    container_name: strapiDB
    platform: linux/amd64
    restart: unless-stopped
    env_file: .env
    image: postgres:16.0-alpine
    environment:
      POSTGRES_USER: ${DATABASE_USERNAME}
      POSTGRES_PASSWORD: ${DATABASE_PASSWORD}
      POSTGRES_DB: ${DATABASE_NAME}
    volumes:
      - strapi-data:/var/lib/postgresql/data/
    ports:
      - "5432:5432"
    networks:
      - strapi

提示：若在 Apple M1/M2（ARM）芯片上遇到镜像平台相关错误，可指定 platform: linux/amd64（性能会受影响）。

生产环境
#

生产环境的 Docker 镜像与开发镜像不同，主要在于 Admin 面板的构建与运行命令（生产环境使用 strapi start）。生产镜像通常使用多阶段构建来减少最终镜像体积并生成已构建的 admin 面板。

生产 Dockerfile（npm 多阶段示例）
#

# 多阶段构建：build 阶段
FROM node:22-alpine AS build
RUN apk update && apk add --no-cache build-base gcc autoconf automake zlib-dev libpng-dev vips-dev git > /dev/null 2>&1
ARG NODE_ENV=production
ENV NODE_ENV=${NODE_ENV}
WORKDIR /opt/
COPY package.json package-lock.json ./
RUN npm install -g node-gyp
RUN npm config set fetch-retry-maxtimeout 600000 -g && npm install --only=production
ENV PATH=/opt/node_modules/.bin:$PATH
WORKDIR /opt/app
COPY . .
RUN npm run build

# 生成最终的生产镜像
FROM node:22-alpine
RUN apk add --no-cache vips-dev
ARG NODE_ENV=production
ENV NODE_ENV=${NODE_ENV}
WORKDIR /opt/
COPY --from=build /opt/node_modules ./node_modules
WORKDIR /opt/app
COPY --from=build /opt/app ./
ENV PATH=/opt/node_modules/.bin:$PATH
RUN chown -R node:node /opt/app
USER node
EXPOSE 1337
CMD ["npm", "run", "start"]

构建生产镜像
#

示例命令：

docker build \\
  --build-arg NODE_ENV=production \\
  -t mystrapiapp:latest \\
  -f Dockerfile.prod .

你可以根据需要传入更多的 build-args（例如 STRAPI_URL）或使用 Docker BuildKit 等高级选项。

（可选）将镜像推送到镜像仓库
#

生产环境建议使用私有镜像仓库以保护镜像中的敏感信息。常见的容器注册表包括：

AWS ECR
Azure Container Registry
GCP Container Registry / Artifact Registry
DigitalOcean Container Registry
GitHub Container Registry
GitLab Container Registry

推送镜像示例（以 DockerHub 为例）：

docker tag mystrapiapp:latest myrepo/mystrapiapp:latest
docker push myrepo/mystrapiapp:latest

不同云厂商的推送命令与认证方式略有差异，请参照对应文档。

社区工具
#

Strapi 社区提供了一些工具来生成 Dockerfile 与自动部署：

@strapi-community/dockerize
- 用法：在项目根目录运行 npx @strapi-community/dockerize@latest，按照提示生成 Dockerfile 与 docker-compose
- 仓库：https://github.com/strapi-community/strapi-tool-dockerize

参考与链接
#

Strapi 文档（原文/英文）：https://docs.strapi.io/
Docker 官方文档：https://docs.docker.com/
Docker Compose 文档：https://docs.docker.com/compose/

在 Docker 中运行 Strapi 5 — 完整中文指南#

概览#

先决条件#

必需的环境变量#

开发 / 暂存 环境#

开发 Dockerfile（npm 示例）#

可选：docker-compose（带数据库）#

生产环境#

生产 Dockerfile（npm 多阶段示例）#

构建生产镜像#

（可选）将镜像推送到镜像仓库#

社区工具#

参考与链接#