Strapi 应用模板入门：vanilla 模板 README 与脚手架命令全解析

本文基于 Strapi 官方脚手架模板中的 vanilla 模板 README（即 npx create-strapi-app 创建新项目后自动生成的“Getting started”文档）展开，完整讲解一份新建 Strapi 应用的四大核心命令（develop、start、build、deploy）、项目目录骨架与关键配置文件，并结合 create-strapi-app 包的源码说明这些命令与配置是如何被生成和驱动的。读完后你将能独立启动、构建并部署一个全新的 Strapi 应用，并理解其模板机制与配置约定。

vanilla 模板 README 是什么

该 README 位于 packages/cli/create-strapi-app/templates/vanilla/README.md，它并不面向 Strapi 仓库的贡献者，而是面向最终用户：当你执行 npx create-strapi-app my-app 创建项目时，脚手架会把 vanilla 模板目录整体复制到你的项目目录，README 随之成为你项目里的入门指南。

模板的选择逻辑可以在 packages/cli/create-strapi-app/src/create-strapi.ts 中确认：

• 未指定 --template 且未使用示例应用（--example）时，模板名默认为 vanilla；
• 若用户选择了 JavaScript（--js/--javascript），则改选 vanilla-js 模板；
• 指定 --example 时使用 example 模板（带示例内容类型的完整博客应用）；
• 指定 --template 时支持官方模板、GitHub 简写（owner/repo）、GitHub 仓库 URL 或本地路径（file:// 或目录），实现见 packages/cli/create-strapi-app/src/utils/template.ts。

vanilla 模板即“空壳”模板：只有 config/、src/、public/、database/ 等目录骨架和配置文件，没有任何内容类型，适合从最干净的状态开始开发。与 example 模板（内置 about/article/author/category/global 等内容类型）形成对照。

四大核心命令：develop / start / build / deploy

原文档的核心内容就是四条命令的用法，这里完整保留并结合 vanilla 模板的 package.json 补充脚本映射关系。

develop：开启热重载的开发模式

npm run develop
# or
yarn develop

以 autoReload 模式启动应用：Strapi 会监听项目文件变化并在变更时自动重启服务，这是日常开发的默认入口。

start：关闭热重载的稳定启动

npm run start
# or
yarn start

以 autoReload 关闭的模式启动，面向不需要监听文件变化的运行场景。

build：构建管理后台

npm run build
# or
yarn build

构建 Strapi 管理后台（admin panel）的产物。

deploy：部署项目

yarn strapi deploy

原文档的部署章节指出 Strapi 提供多种部署选项（包括 Strapi Cloud），并给出 yarn strapi deploy 命令。部署目标的选择应结合你的基础设施与用例自行决定。

模板内置的完整脚本一览

package.json 中实际定义了比 README 更多的脚本，完整清单如下：

npm 脚本	底层命令	作用
develop / dev	strapi develop	热重载开发模式启动
start	strapi start	无热重载启动
build	strapi build	构建管理后台
deploy	strapi deploy	部署项目
console	strapi console	打开 Strapi 交互控制台
strapi	strapi	展示/调用全部 Strapi 命令
upgrade	npx @strapi/upgrade latest	升级到最新版
upgrade:dry	npx @strapi/upgrade latest --dry	升级预演（dry-run）

注意 dev 是 develop 的别名，两者等价；而 console 与 upgrade 虽未在 README 中列出，但同样随模板自动生成。脚手架完成项目创建后打印的“可用命令”提示（develop / start / build / deploy）也出自 packages/cli/create-strapi-app/src/create-strapi.ts 中的 logger 输出，与 README 内容保持一致。

vanilla 模板的项目骨架

模板目录结构（templates/vanilla）如下：

vanilla/
├── config/
│   ├── admin.ts        # 管理后台配置（JWT、加密密钥、功能开关）
│   ├── api.ts          # API 行为配置
│   ├── database.ts     # 数据库连接配置
│   ├── middlewares.ts  # 全局中间件配置
│   ├── plugins.ts      # 插件配置
│   └── server.ts       # 服务地址、端口与密钥
├── database/
│   └── migrations/     # 数据库迁移目录（空）
├── public/
│   ├── uploads/        # 上传文件静态目录（空）
│   └── robots.txt
├── src/
│   ├── admin/          # 后台自定义入口（app.example.tsx 为示例参考）
│   ├── api/            # 内容类型 API（空）
│   ├── extensions/     # 扩展（空）
│   └── index.ts        # register / bootstrap 生命周期钩子
├── favicon.png
├── package.json
├── tsconfig.json
└── README.md           # 即本文档主体

其中 src/index.ts 提供了两个生命周期钩子：register（应用初始化前运行，可用于扩展代码）与 bootstrap（应用启动前运行，可执行数据模型初始化、任务或特殊逻辑），模板默认均为空实现，等待开发者填充。

TypeScript 编译约定

tsconfig.json 采用 CommonJS 模块 + strict: true，outDir 指向 dist/，并显式排除了 src/admin/（后台文件不参与服务端编译）、src/plugins/**、**/*.test.* 以及 node_modules/、dist/、.tmp/ 等目录。vanilla-js 模板则对应使用 jsconfig.json，两者除语言差异外结构一致。

关键配置文件详解

server.ts：监听地址与端口

config/server.ts 内容如下：

const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Server => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS')!,
  },
  webhooks: {
    populateRelations: env.bool('WEBHOOKS_POPULATE_RELATIONS', false),
  },
});

• HOST 默认 0.0.0.0，PORT 默认 1337，均可通过环境变量覆盖；
• APP_KEYS 必须是由逗号分隔的密钥数组（脚手架自动生成的 .env 中已提供 4 个）；
• WEBHOOKS_POPULATE_RELATIONS 控制 webhook 事件是否自动填充关联内容，默认 false。

admin.ts：管理后台安全配置

config/admin.ts 从环境变量读取四类敏感值，并暴露三个后台功能开关：

• ADMIN_JWT_SECRET → 后台登录会话的 JWT 签名密钥；
• API_TOKEN_SALT → API Token 的加盐值；
• TRANSFER_TOKEN_SALT → 数据迁移（transfer）令牌的加盐值；
• ENCRYPTION_KEY → 应用内敏感数据（如插件凭证）的对称加密密钥；
• FLAG_NPS / FLAG_PROMOTE_EE / FLAG_DOC_LINKS 分别控制后台内的满意度调研、企业版推广与文档链接，默认均为 true，可通过环境变量关闭。

database.ts：三种数据库客户端

config/database.ts 是模板中最复杂的配置。它通过 DATABASE_CLIENT 环境变量在 sqlite（默认）、mysql、postgres 三种客户端之间切换，并在客户端非法时抛出错误：

const client = env('DATABASE_CLIENT', 'sqlite');

if (!isDatabaseClientKind(client)) {
  throw new Error(
    `Unsupported DATABASE_CLIENT: ${client}. Use "postgres", "mysql", or "sqlite".`
  );
}

各客户端的关键连接参数与默认值：

环境变量	适用客户端	默认值	说明
DATABASE_HOST	mysql / postgres	localhost	数据库主机
DATABASE_PORT	mysql / postgres	3306（mysql）/ 5432（postgres）	端口
DATABASE_NAME	mysql / postgres	strapi	库名
DATABASE_USERNAME / DATABASE_PASSWORD	mysql / postgres	strapi / strapi	账号口令
DATABASE_SSL	mysql / postgres	false	开启后可配 DATABASE_SSL_KEY/CERT/CA/CAPATH/CIPHER/REJECT_UNAUTHORIZED
DATABASE_SCHEMA	postgres	public	PostgreSQL schema
DATABASE_FILENAME	sqlite	.tmp/data.db	SQLite 数据文件路径（相对项目根目录）
DATABASE_POOL_MIN / DATABASE_POOL_MAX	mysql / postgres	2 / 10	连接池大小
DATABASE_CONNECTION_TIMEOUT	全部	60000（ms）	获取连接的超时时间

SQLite 分支额外设置了 useNullAsDefault: true。从源码结构看，postgres 分支还保留了 connectionString 读取 DATABASE_URL 的写法，与逐字段配置并存。

脚手架自动生成的 .env

模板本身不包含 .env，它由 packages/cli/create-strapi-app/src/utils/dot-env.ts 在项目创建时生成：所有密钥（APP_KEYS 的 4 个随机值、API_TOKEN_SALT、ADMIN_JWT_SECRET、JWT_SECRET、TRANSFER_TOKEN_SALT、ENCRYPTION_KEY）均由 crypto.randomBytes(16) 生成 base64 随机串，同时写入当前选择的数据库客户端与其连接参数。因此 config/ 中各 env(...) 调用的默认值与 .env 中的占位项是一一对应的，开发者只需在切换数据库时修改 .env 中相应的 DATABASE_* 项。

脚手架如何把模板变成项目

create-strapi-app（版本见 package.json，当前为 5.52.2）的入口是 src/index.ts，完整流程如下：

1. 参数校验：--ts/--js 与 --template 互斥、不能同时指定多个包管理器、--non-interactive 必须带目录参数等规则在 run() 中前置检查；
2. 环境检查：checkNodeRequirements() 校验 Node 版本（engines 声明为 >=20.0.0 <=26.x.x）；
3. 依赖组装：默认写入与 @strapi/strapi 相同版本的 @strapi/database、@strapi/plugin-users-permissions、@strapi/plugin-cloud，以及 react@^18、react-dom@^18、react-router-dom@^6.30.3、styled-components@^6；TypeScript 项目额外加入 typescript@^5 与 @types/* 开发依赖（见 index.ts）；
4. 复制模板 / 下载模板：内部模板走 fse.copy，外部模板走 template.ts 的 tarball 下载 + 解压（失败自动重试 3 次），并强制要求模板包含 package.json；
5. 写入生成文件：createPackageJSON() 生成正式 package.json、生成 .env、按需写入 .yarnrc.yml（yarn 3+ 的 nodeLinker: node-modules）与 pnpm workspace 配置（见 create-strapi.ts）；
6. 安装依赖：默认包管理器取自 npm_config_user_agent 探测结果（yarn/pnpm/npm 均可，见 getPkgManager()），可用 --use-npm/--use-yarn/--use-pnpm 显式指定；安装失败时项目文件仍保留，并提示手动执行 <pm> install；
7. 收尾：写 .gitignore、按需 git init、示例模板额外执行 seed:example 灌入演示数据；--quickstart 场景还会直接执行 run develop 启动应用。

包管理器探测与安装参数逻辑另有单元测试佐证，见 get-package-manager-args.test.ts 与 templates-database.test.ts。

典型使用方式与适用前提

结合上述机制，创建并运行一个空 Strapi 项目的最小路径是：

# 交互式创建（默认 TypeScript，模板即 vanilla）
npx create-strapi-app@latest my-app

# 或完全非交互式、显式指定要素
npx create-strapi-app@latest my-app --non-interactive --dbclient sqlite --skip-cloud

# 使用 JavaScript 版本模板（vanilla-js）
npx create-strapi-app@latest my-app --js

# 进入项目并启动
cd my-app
npm install        # 若创建时选择了 --no-install
npm run develop

适用前提与限制（以当前仓库为准）：

• Node 版本需在 >=20.0.0 <=26.x.x 区间内，npm >= 6（见 package.json engines 字段）；
• 模板内所有密钥类配置均为脚手架随机生成，生产环境应在 .env 中替换为受控密钥；
• 模板中 src/api/、src/extensions/ 为空，创建后需通过 Strapi 的内容类型构建器或 CLI 生成 API，example 模板则可直接体验带数据的完整站点；
• 升级项目可复用模板内置脚本：npm run upgrade（正式执行）与 npm run upgrade:dry（预演）。

小结

vanilla 模板的 README 是 Strapi 官方为每个新项目准备的“第一站”：develop/start/build/deploy 四条命令覆盖了开发、运行、构建与部署的完整生命周期，其背后是 create-strapi-app 对模板复制、依赖组装、密钥生成与 .env 写入的自动化编排。理解 vanilla 模板目录 的每个文件如何映射到生成后的项目，再对照 create-strapi.ts 的创建流程，就能把脚手架从“黑盒命令”变成可预期、可定制的工程起点。