Strapi getstarted 示例应用实战：用 SQLite/MySQL/PostgreSQL 快速验证本地改动

getstarted 是 Strapi monorepo 中内置的一整套"功能全家桶"示例应用（examples/getstarted/README.md），用于在开发者修改框架代码后快速跑起一个真实应用验证改动。本文以该 README 为主线，讲清楚它的环境要求、启动方式，以及如何通过 DB 环境变量在 SQLite、MySQL、PostgreSQL、MariaDB 之间切换，并结合 config/database.js 与 docker-compose.dev.yml 的源码，解释数据库连接配置的实际生效逻辑。

getstarted 应用在项目中的定位

getstarted 应用的官方定位一句话概括就是："an example app you can run to test your changes quickly"——一个可以快速运行以测试你改动的示例应用（见 examples/getstarted/README.md）。

从源码结构看，它覆盖了一个 Strapi 应用几乎会用到的全部定制点：

• src/api/ 下有 about、article、category、restaurant、review 等十余个内容类型，各自带 controllers/、routes/、services/；
• src/components/ 定义了 basic、blog、default 等 16 个组件；
• src/plugins/local-plugin/ 是一个本地插件，通过 config/plugins.js 中 myplugin 项以 resolve: './src/plugins/local-plugin' 方式接入；
• src/middlewares/test-middleware.js、src/policies/test-policy.js、src/custom/middleware.js 用于验证中间件、策略与自定义中间件；
• data/data.json 配合 data/uploads/ 提供了种子数据与附件，便于导入测试。

也就是说，如果你在 Strapi 核心包（如 packages/core/database）中修改了数据库相关代码，getstarted 就是那个"跑一遍就知道有没有崩"的验证场。

环境要求

README 明确列出三项前置要求：

• Docker
• Docker compose
• Node

其中 Docker 与 Docker Compose 仅在你需要连接 MySQL/PostgreSQL 时才用到；如果只使用默认的 SQLite，安装好 monorepo 依赖即可直接运行。Node 版本方面，examples/getstarted/package.json 的 engines 字段要求 >=20.0.0 <=26.x.x。

另外注意数据库驱动的依赖都已随应用声明：better-sqlite3（SQLite）、mysql2（MySQL/MariaDB）、pg（PostgreSQL），无需额外安装。

默认启动：直接使用 SQLite

README 的说明是：完成 monorepo 初始化（yarn 安装依赖）之后，就可以直接用 SQLite 数据库运行 getstarted 应用。

进入应用目录执行：

yarn develop

该脚本对应 examples/getstarted/package.json 中的 "develop": "strapi develop"。还有一个关闭企业版功能的变体 develop:ce（STRAPI_DISABLE_EE=true strapi develop），适合只关心 CE 能力的场景。

之所以"开箱即用"，是因为 config/database.js 的默认分支：

module.exports = {
  connection: process.env.DB ? db[process.env.DB] || db.sqlite : db.sqlite,
};

未设置 DB 环境变量时，永远落到 db.sqlite，其连接配置为：

const sqlite = {
  client: 'sqlite',
  connection: {
    filename: '.tmp/data.db',   // 数据文件落在应用目录下 .tmp/data.db
  },
  useNullAsDefault: true,
};

数据文件写入应用目录的 .tmp/data.db，不依赖任何外部服务。

使用 Docker 启动 MySQL 与 PostgreSQL

如果想用其他数据库验证，README 指引你使用仓库根目录的 docker-compose.dev.yml。

1. 启动数据库

在 monorepo 根目录（注意不是 getstarted 目录下）执行：

docker-compose -f docker-compose.dev.yml up -d

停止时：

docker-compose -f docker-compose.dev.yml stop

该 compose 文件定义了两个服务，凭据完全对齐 config/database.js 中的连接参数：

服务	镜像	用户/密码/库	端口映射	数据卷
postgres	postgres（latest）	strapi / strapi / 库名 strapi	5432:5432	pgdata:/var/lib/postgresql/data
mysql	mysql:8	strapi / strapi / 库名 strapi（root 密码同为 strapi，MYSQL_ROOT_HOST=%）	3306:3306	mysqldata:/var/lib/mysql

两个服务都设置了 restart: always，并用命名卷（pgdata、mysqldata）持久化数据，docker-compose stop 后重启不会丢库。

2. 以指定数据库运行应用

DB={dbName} yarn develop

{dbName} 的可选值取决于 database.js 中 db 对象暴露的键。

DB 环境变量如何映射到连接配置

examples/getstarted/config/database.js 中定义了四套连接，通过 process.env.DB 查表选取：

DB 取值	client	库名	用户/密码	主机:端口
（未设置）/ sqlite	sqlite	文件 .tmp/data.db	—	—
postgres	postgres	strapi	strapi/strapi	localhost:5432
mysql	mysql	strapi	strapi/strapi	localhost:3306
mariadb	mysql	strapi	strapi/strapi	localhost:3307

几个值得注意的实现细节：

1. MariaDB 复用 MySQL 驱动。mariadb 连接的 client 字段写作 'mysql'（与 mysql2 驱动兼容），仅把端口改到 3307 以区分本地实例。
2. 未识别的 DB 值会静默回退到 SQLite：db[process.env.DB] || db.sqlite 意味着写错变量名（例如 DB=MariaDB）不会报错，而是悄悄用 SQLite 启动——排障时先确认 DB 值是否为表中四个键之一。
3. 类型标注：每套连接都用 JSDoc 标注为 Core.Config.Database<'sqlite' | 'postgres' | 'mysql'>['connection']（见 config/database.js 顶部），依赖 examples/getstarted/jsconfig.json 的 JS 项目类型检查，可以在编辑器里直接获得连接参数的类型提示。

关于 MariaDB 的一个注意点

config/database.js 声明了 localhost:3307 的 mariadb 连接，但仓库根目录的 docker-compose.dev.yml 只定义了 postgres 和 mysql 两个服务，并未包含 mariadb 容器。可以推断：若要以 DB=mariadb 运行，需要自行在本机或另起容器把 MariaDB 暴露在 3307 端口，否则连接会失败——这也正是 README 末尾警告所指向的场景之一。

排障：本地数据库实例与 Docker 实例的端口冲突

README 给出了一个显式警告：连接数据库时可能会报错，原因常见于本机正在运行的数据库实例与 Docker 实例争抢同一端口（5432、3306）。两种处理方式：

1. 关闭本地数据库实例；
2. 或同时修改两处端口并保持一致——examples/getstarted/config/database.js 中对应的 port 字段，以及 docker-compose.dev.yml 中对应服务的 ports 映射。

由于连接参数、compose 文件、应用配置三者必须对齐（库名、用户、密码都是 strapi/strapi/strapi 这一套约定），改端口时最稳妥的做法是只改端口、不动凭据。

生产模式启动方式

除了开发用的 yarn develop，examples/getstarted/ecosystem.config.js 提供了 PM2 生产启动配置：

module.exports = {
  apps: [
    {
      name: 'strapi-getstarted',
      script: 'npm',
      args: 'start',
      env: { NODE_ENV: 'production' },
    },
  ],
};

配合 package.json 中的 "start": "strapi start"（以及带构建步骤的 "build": "strapi build"），即可在 NODE_ENV=production 下以 PM2 托管方式运行。服务默认监听 0.0.0.0:1337，这一默认值来自 config/server.js 的 host: env('HOST', '0.0.0.0') 与 port: env.int('PORT', 1337)。

小结与延伸阅读路径

getstarted 的工作流可以浓缩为四步：

1. monorepo 根目录 yarn 初始化依赖；
2. 默认直接用 SQLite 跑 yarn develop，零外部依赖；
3. 需要关系型数据库时，根目录执行 docker-compose -f docker-compose.dev.yml up -d 拉起 MySQL/PostgreSQL，再执行 DB={mysql|postgres} yarn develop；
4. 遇到连接报错，先核对 DB 值拼写、端口是否与本地实例冲突。

关键文件索引：

• 示例应用说明：examples/getstarted/README.md
• 数据库连接配置（DB 变量查表逻辑）：examples/getstarted/config/database.js
• 开发数据库编排文件：docker-compose.dev.yml
• 脚本与驱动依赖：examples/getstarted/package.json
• 生产启动配置：examples/getstarted/ecosystem.config.js
• 内容类型与自定义扩展：examples/getstarted/src/