Strapi vanilla JavaScript 模板详解：create-strapi-app 脚手架结构、develop / start / build / deploy 命令与配置解析

当使用 create-strapi-app 创建一个不启用 TypeScript 的 Strapi 应用时，脚手架会自动套用仓库中的 vanilla-js 模板，生成的项目自带一套开箱即用的 npm scripts（develop、start、build、deploy 等）与默认配置文件。本文以 vanilla-js 模板 README 为主线，完整覆盖其中讲解的三个核心运行命令与部署流程，并结合 模板目录结构、package.json 脚本定义 以及 create-strapi-app CLI 源码，说明这个 JavaScript 版模板是如何被选中、复制并运行起来的，帮助读者在拿到新项目后准确理解每个脚本的作用、每个配置项的默认值与修改位置。

模板的定位与触发条件

vanilla-js 模板是 Strapi 官方脚手架 @strapi/create-strapi-app 内置的四种本地模板之一，对应"原生 JavaScript（非 TypeScript）+ 空项目（非示例数据）"这一组合。从 create-strapi.ts 的模板选择逻辑可以看到，CLI 在未指定 --template 时按如下规则确定模板名：

// packages/cli/create-strapi-app/src/create-strapi.ts (L113-L123)
if (!template) {
  let templateName = useExample ? 'example' : 'vanilla';

  if (!useTypescript) {
    templateName = `${templateName}-js`;
  }

  const internalTemplatePath = join(__dirname, '../templates', templateName);
  if (await fse.exists(internalTemplatePath)) {
    await fse.copy(internalTemplatePath, rootPath);
  }
}

也就是说，四个内置模板的映射关系为：

交互选项	模板目录
TypeScript + 空项目	vanilla
JavaScript + 空项目	vanilla-js
TypeScript + 示例数据	example
JavaScript + 示例数据	example-js

vanilla-js 模板与 vanilla 模板的差异体现在文件后缀与类型配置上：前者使用 src/index.js、config/*.js 并附带 jsconfig.json，后者使用 src/index.ts、config/*.ts 并附带 tsconfig.json。

如果用户显式传入 --template 参数（本地路径、GitHub 仓库短写法或仓库地址），CLI 则不会使用内置模板，而是走 template.ts 中的 copyTemplate 流程：先通过 isOfficialTemplate（template.ts#L213-L224）向 GitHub API 发 HEAD 请求确认该路径是否为 Strapi 官方仓库中的模板，官方模板则通过 downloadGithubRepo（template.ts#L126-L174）下载仓库 tarball 并用 tar.x 解压出 templates/<模板名> 子目录，且带 3 次重试机制。自定义模板目录中必须存在 package.json，否则 CLI 会直接报错终止（见 create-strapi.ts#L139-L141）。

模板的完整目录结构

vanilla-js 模板复制落地后，新项目的基础目录如下：

my-strapi-app/
├── config/
│   ├── admin.js        # 管理后台配置（认证、拖拽上传等）
│   ├── api.js         # REST API 配置（响应格式化、REST 策略等）
│   ├── database.js     # 数据库连接配置
│   ├── middlewares.js  # 全局中间件配置
│   ├── plugins.js      # 内置插件配置
│   └── server.js       # 服务器监听配置
├── database/
│   └── migrations/     # 数据库迁移脚本目录
├── public/
│   ├── uploads/        # 静态上传文件目录
│   └── robots.txt
├── src/
│   ├── admin/          # 管理后台定制入口（app.example.js / vite.config.example.js）
│   ├── api/            # 自定义 API（控制器、路由、服务）
│   ├── extensions/     # 插件扩展点
│   └── index.js        # 应用生命周期入口
├── favicon.png
├── jsconfig.json
└── package.json

其中 config/ 下六个配置文件一一对应 Strapi 的各项核心配置，均以 CommonJS 方式导出一个接收 { env } 的工厂函数；src/ 目录则承载应用生命周期入口与业务代码。此外 CLI 在复制模板后还会生成若干脚手架辅助文件：.env（由 generateDotEnv 写入，见 create-strapi.ts#L158）、.gitignore（create-strapi.ts#L226-L228），使用 Yarn 3+ 或 pnpm 时还会分别写入 .yarnrc.yml / pnpm workspace 配置。

package.json 中的脚本清单

模板自带的 package.json 只包含 scripts 段，所有脚本最终都委托给 strapi CLI 执行：

{
  "scripts": {
    "build": "strapi build",
    "deploy": "strapi deploy",
    "develop": "strapi develop",
    "dev": "strapi develop",
    "console": "strapi console",
    "start": "strapi start",
    "strapi": "strapi",
    "upgrade": "npx @strapi/upgrade latest",
    "upgrade:dry": "npx @strapi/upgrade latest --dry"
  }
}

各脚本作用：

脚本	等价命令	说明
develop / dev	strapi develop	开发模式启动，开启 autoReload（watch）
start	strapi start	生产模式启动，关闭 autoReload
build	strapi build	构建管理后台静态资源
deploy	strapi deploy	部署到 Strapi Cloud
console	strapi console	打开交互式调试控制台
strapi	strapi	透传 CLI，可用 npm run strapi -- <命令> 查看全部命令
upgrade / upgrade:dry	npx @strapi/upgrade latest	执行版本升级迁移；--dry 为演练模式，只做检查不落盘。对应实现位于仓库 packages/utils/upgrade

CLI 创建完成后打印的提示语（create-strapi.ts#L255-L280）也正是围绕 develop、start、build、deploy 四条命令展开，与模板 README 中的说明一致。

三个核心运行命令：develop、start、build

vanilla-js 模板 README 的核心内容是对这三个脚本的说明，它们分别覆盖开发、生产启动与管理后台构建三种场景。

develop：开启 autoReload 的开发模式

npm run develop
# or
yarn develop

develop 以 watch 模式启动应用：Strapi 项目文件发生变化时会触发服务器重启，适合日常开发。注意 package.json 中的 dev 是 develop 的别名，两者等价。

start：关闭 autoReload 的生产模式

npm run start
# or
yarn start

start 关闭 autoReload，用于生产环境启动。生产部署前通常先执行一次 build，再用 start 拉起服务。

build：构建管理后台

npm run build
# or
yarn build

build 会编译并打包 Strapi 管理后台的前端资源，产出可供 start 直接静态托管的 admin 构建产物。

三条命令在 npm 与 yarn 下均可运行（模板 README 对每条命令同时给出了两种包管理器的写法）。pnpm 场景下可类推为 pnpm run develop 等。

应用生命周期入口：src/index.js

vanilla-js 模板的 src/index.js 定义了 Strapi 应用的两个生命周期钩子，完整内容如下：

'use strict';

module.exports = {
  /**
   * An asynchronous register function that runs before
   * your application is initialized.
   *
   * This gives you an opportunity to extend code.
   */
  register(/*{ strapi }*/) {},

  /**
   * An asynchronous bootstrap function that runs before
   * your application gets started.
   *
   * This gives you an opportunity to set up your data model,
   * run jobs, or perform some special logic.
   */
  bootstrap(/*{ strapi }*/) {},
};

• register({ strapi })：在应用初始化之前执行，适合做能力扩展（如向 strapi 实例注入方法、注册全局逻辑）。
• bootstrap({ strapi })：在应用启动之前执行，适合初始化数据模型、运行一次性任务等。

新建的模板中两者均为空实现，业务代码在此处按需填充。

默认配置解析：database.js 与 server.js

模板的 config/ 目录预置了 Strapi 全部核心配置，其中数据库与服务器两项决定了应用能否跑起来。

config/database.js：支持 sqlite / postgres / mysql 三种客户端

config/database.js 通过环境变量 DATABASE_CLIENT 在三种数据库客户端间切换，默认值为 sqlite（无需额外安装数据库服务即可开发），并对非法取值直接抛错：

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

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

三种客户端的关键参数与默认值（均读取脚手架生成的 .env 环境变量）：

配置项	默认值	说明
DATABASE_CLIENT	sqlite	客户端类型，仅接受 sqlite / postgres / mysql
DATABASE_HOST	localhost	主机地址（mysql / postgres）
DATABASE_PORT	mysql 3306 / postgres 5432	端口
DATABASE_NAME	strapi	数据库名
DATABASE_USERNAME / DATABASE_PASSWORD	strapi / strapi	账号密码
DATABASE_SSL	false	启用后读取 DATABASE_SSL_KEY、DATABASE_SSL_CERT、DATABASE_SSL_CA、DATABASE_SSL_CAPATH、DATABASE_SSL_CIPHER、DATABASE_SSL_REJECT_UNAUTHORIZED（默认 true）
DATABASE_SCHEMA	public	仅 postgres 使用
DATABASE_FILENAME	.tmp/data.db	sqlite 数据文件，实际路径为 path.join(__dirname, '..', <值>)，即项目根目录下的 .tmp/data.db
DATABASE_POOL_MIN / DATABASE_POOL_MAX	2 / 10	mysql / postgres 连接池上下限
DATABASE_CONNECTION_TIMEOUT	60000	获取连接的超时（毫秒），通过 acquireConnectionTimeout 生效

另外 sqlite 分支设置了 useNullAsDefault: true，postgres 分支同时支持 DATABASE_URL 连接串。切换数据库时只需修改 .env 中的 DATABASE_CLIENT 及对应变量，无需改动代码——这是该模板把配置全部参数化为环境变量的意义所在。

config/server.js：监听地址与关键开关

config/server.js 内容简短但覆盖了最常用的服务器级配置：

module.exports = ({ env }) => ({
  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：Strapi 默认端口 1337，应用启动后管理后台即位于 http://localhost:1337/admin；
• APP_KEYS：应用密钥数组，由脚手架在生成 .env 时一并写入，用于签名与加密相关功能，是必填项；
• WEBHOOKS_POPULATE_RELATIONS：默认 false，开启后 Webhook 事件负载会自动展开关联字段。

其余配置文件 admin.js、api.js、middlewares.js、plugins.js 同样以 ({ env }) => ({ ... }) 的形式导出，分别管理后台行为、REST API 行为、全局中间件与内置插件，可按需查阅 vanilla-js 模板 config 目录。

部署：strapi deploy

模板 README 的 Deployment 一节指出 Strapi 提供多种部署路径（其中包括 Strapi Cloud），并给出了一键部署命令：

yarn strapi deploy

该命令对应 package.json 中的 deploy: strapi deploy 脚本，即 strapi deploy CLI 命令，用于将项目部署到 Strapi Cloud。仓库内 CLI 侧的部署与云相关工具位于 packages/cli/cloud，其中 cloud.ts 封装了创建 Growth SSO 试用许可证等部署前置流程——例如创建应用时若启用了试用，CLI 会调用 createGrowthSsoTrial 并把 license 写入项目根目录（见 create-strapi.ts#L176-L187）。

创建后的典型工作流

综合模板 README 与 CLI 的收尾提示（create-strapi.ts#L282-L297），拿到 vanilla-js 项目后的标准流程为：

1. cd 进入项目目录；若创建时跳过了依赖安装，先执行 <包管理器> install；
2. npm run develop（或 yarn develop）启动开发模式，浏览器访问管理后台完成初始化；
3. 生产环境先 npm run build 构建管理后台，再 npm run start 启动；
4. 需要上云时执行 yarn strapi deploy；
5. 升级 Strapi 大版本时使用 npm run upgrade（或先 npm run upgrade:dry 演练），迁移逻辑由 packages/utils/upgrade 提供；
6. 需要更多内置命令时，运行 npm run strapi 列出全部 CLI 命令。

小结与延伸阅读

vanilla-js 模板是 Strapi 面向 JavaScript 用户的最小可用脚手架：它以 config/ 六个环境变量驱动的核心配置（默认 sqlite、端口 1337）+ src/index.js 双生命周期钩子 + 一组委托 strapi CLI 的 npm scripts，覆盖了从开发到部署的完整链路。模板 README 中 develop / start / build / deploy 四条命令的语义，可以在 create-strapi.ts 的收尾提示与 package.json 的脚本定义中相互印证。

如需继续深入当前仓库，建议按以下路径阅读：

• 模板本体：packages/cli/create-strapi-app/templates/vanilla-js
• 脚手架主流程：packages/cli/create-strapi-app/src/create-strapi.ts
• 模板下载与校验：packages/cli/create-strapi-app/src/utils/template.ts
• 服务器端 API 文档：docs/docs/api/Strapi.mdx
• Strapi 核心概念文档：docs/docs/00-intro.md