Strapi create-strapi-app 使用指南从 CLI 参数到项目生成流程的完整解析【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi本文基于 Strapi 仓库中 create-strapi-app 包的 README 及其源码系统讲解如何用create-strapi-appCLI 创建一个全新的 Strapi 项目包括yarn create/npx/ 全局安装三种启动方式、全部命令行参数与默认值、模板机制内置 vanilla/example 与外部 GitHub/本地模板、数据库配置逻辑以及 CLI 内部的完整项目生成流程与故障恢复方法。读完后你可以独立、可复现地完成交互式或非交互式CI 场景的 Strapi 项目初始化。前置要求Node.js 与 npm 版本CLI 在运行任何逻辑之前会先做环境校验。从 engines 定义 与 package.json 的engines字段可以确认当前版本5.52.2的要求Node.js20.0.0 26.x.xnpm6.0.0checkNodeRequirements 函数的具体行为是若当前 Node 版本不满足engines.node范围直接logger.fatal终止并提示“Strapi requires Node.js 20.0.0 26.x.x”若 Node 大版本小于 26 且为奇数非 LTS则打印警告提示 Strapi 仅支持 Node.js LTS 版本其他版本可能存在兼容性问题。因此建议始终使用偶数 LTS 版本如 Node 20、22、24运行该 CLI。安装与快速开始README 给出了三种等价的启动方式核心都是调用create-strapi-app的二进制入口bin: ./bin/index.js见 package.json并将项目目录名作为第一个参数方式一yarn create推荐yarn create strapi-app my-project方式二npxnpx create-strapi-app my-project方式三全局安装后直接调用# yarn yarn global add create-strapi-app create-strapi-app my-app # npm npm install -g create-strapi-app create-strapi-app my-app执行后 CLI 会依次询问若干问题见下文“交互式提示”一节默认行为是创建 TypeScript 项目、使用 sqlite 数据库、自动安装依赖并初始化 git 仓库。一个典型的非交互自动化调用示例可参考后文的--non-interactive组合npx create-strapi-app my-project --non-interactive --skip-cloud --no-install交互式提示与默认值交互式问题全部集中在 prompts.ts 与 utils/database.ts 中使用inquirer实现。逐项默认值如下问题来源默认值What is the name of your project?prompts.directorymy-strapi-projectStart with Typescript?prompts.typescripttrueStart with an example structure data?prompts.examplefalseInstall dependencies with packageManager?prompts.installDependenciestrueInitialize a git repository?prompts.gitInittrueDo you want to use the default database (sqlite)?database.ts 中的 dbPrompttrueChoose your default database client同上sqliteDatabase name: / Host: / Port: / Username: / Password: / SSL同上库名strapi、host127.0.0.1、postgres 端口5432、mysql 端口3306、SSLfalseFilename:sqlite 专用同上.tmp/data.db其中几个值得注意的细节数据库名输入若包含.会被校验函数直接拒绝“The database name cant contain a .”选择 sqlite 时只问一个filename默认.tmp/data.db选择 postgres/mysql 时问database/host/port/username/password/ssl六项这些选择最终会被写入项目根目录的.env文件见下文“环境变量”小节。完整命令行参数参考所有选项在 src/index.ts 的 commander 定义 中声明参数类型为 Options 接口。完整清单如下参数说明create-strapi-app [directory]位置参数项目目录缺省时交互式询问默认my-strapi-project--quickstart快速创建源码中标注 deprecated等价于跳过交互并使用默认值--no-run创建后不自动启动应用--ts, --typescript使用 TypeScript 初始化默认--js, --javascript使用 JavaScript 初始化--use-npm/--use-yarn/--use-pnpm指定包管理器--install安装依赖--no-install不安装依赖--skip-cloud跳过 Cloud 登录与项目创建--example使用示例应用带内容类型与种子数据--no-example不使用示例应用--git-init初始化 git 仓库--no-git-init不初始化 git 仓库--non-interactive跳过所有交互式提示并使用默认值自动化场景关键参数--dbclient dbclient数据库客户端sqlite/mysql/postgres--dbhost dbhost数据库主机--dbport dbport数据库端口--dbname dbname数据库名--dbusername dbusername数据库用户名--dbpassword dbpassword数据库密码--dbssl dbssl数据库 SSL传true表示开启--dbfile dbfilesqlite 数据库文件路径--skip-db跳过数据库配置直接使用 sqlite 默认值--template template指定一个 Strapi 模板官方/本地/GitHub--template-branch branch模板的分支--template-path path模板仓库内的子路径此外源码中还注册了两个隐藏的参数--enable-ab-tests/--no-enable-ab-tests注释明确说明它们是“Legacy no-ops”仅为兼容旧 CI 脚本而存在实际被忽略index.ts L53-L55。参数冲突与硬性校验index.ts 的 run 函数 在进入主流程前做了一组互斥校验任何一条触发都会logger.fatal终止--javascript/--typescript不能与--template同时使用--typescript与--javascript不能同时使用--example不能与--template同时使用模板名不能以-开头--use-npm、--use-pnpm、--use-yarn不能同时指定多个使用--quickstart或--non-interactive时必须显式提供directory位置参数。另有一个安装路径校验 checkInstallPath目标目录若已存在必须是一个目录且最多只能有 1 个文件实际要求接近空目录否则会报 “You can only create a Strapi app in an empty directory”。项目生成流程从目录创建到种子数据核心编排逻辑在 src/create-strapi.ts 中。createStrapi先ensureDir创建目标目录随后createApp按以下顺序执行任一步失败都会fse.remove(rootPath)清理已生成的目录后抛错保证不留半成品拷贝模板未指定--template时按useExample与useTypescript组合选择内置模板example/vanilla/example-js/vanilla-js从包内templates/目录整体复制到目标路径create-strapi.ts L113-L123指定--template时调用 copyTemplate 拉取外部模板完成后强制检查package.json是否存在缺失则报 “Missing package.json in template”。写 package.jsoncreatePackageJSON 生成项目的package.json并合并 scope 中的依赖声明。其中 index.ts L168-L179 预置了核心依赖当前版本的strapi/strapi、strapi/database、strapi/plugin-users-permissions、strapi/plugin-cloud以及react^18.0.0、react-dom^18.0.0、react-router-dom^6.30.3、styled-components^6.0.0若为 TypeScript 项目还会加入typescript^5、types/node^20、types/react^18、types/react-dom^18index.ts L205-L213。写.envgenerateDotEnv 用 lodash template 生成.env内容包含服务端口HOST0.0.0.0、PORT1337六个随机生成的密钥crypto.randomBytes(16).toString(base64)APP_KEYS4 段拼接、API_TOKEN_SALT、ADMIN_JWT_SECRET、JWT_SECRET、TRANSFER_TOKEN_SALT、ENCRYPTION_KEY数据库段落DATABASE_CLIENT、DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_SSL、DATABASE_FILENAME与前面数据库配置的选择一一对应。包管理器专属配置yarn ≥ 3 且项目内不存在.yarnrc.yml时写入nodeLinker: node-modulescreate-strapi.ts L160-L165pnpm 时解析其版本并写入相应 workspace 配置writePnpmWorkspaceConfig。安装依赖当installDependencies为真runInstall 用execa调用所选包管理器的 install 命令并注入NODE_ENVdevelopment与包管理器相关的环境变量。.gitignore与 git 初始化无论用户是否启用 git都会确保写出.gitignore内容来自 gitignore.ts若gitInit为真则 tryGitInit 执行git init。示例数据种子仅当useExample installDependencies且存在scripts/seed.js时执行packageManager run seed:example失败只打印 “Failed to seed your database. Skipping”不视为致命错误。可选的自动启动--quickstart且未禁用run且依赖已安装时会以stdio: inherit直接执行packageManager run developcreate-strapi.ts L299-L323。创建结束后的输出与推荐命令流程末尾CLI 会打印项目内可用的命令create-strapi.ts L255-L297packageManager run develop # 监听模式启动开发 packageManager run start # 无监听模式启动 packageManager run build # 构建管理后台 packageManager run deploy # 部署 packageManager run strapi # 查看全部命令若使用了示例应用还会额外提示packageManager run seed:example用于灌入示例数据。最终给出的启动指引按依赖是否已安装分两种# 已安装依赖 cd my-project yarn run develop # 或 npm / pnpm run develop # 未安装依赖--no-install 场景 cd my-project packageManager install packageManager run develop内置模板vanilla 与 example 两种起步方式CLI 包内自带四套模板位于 packages/cli/create-strapi-app/templates模板名触发条件特点vanilla默认TypeScript空项目骨架config/admin/api/database/middlewares/plugins/server 六份配置、src/admin、src/api、src/extensions、src/index.ts、tsconfig.jsonvanilla-js--js同上JavaScript 版jsconfig.jsonexample--exampleTypeScript在 vanilla 基础上预置 about/article/author/category/global 等内容类型、shared 组件media/quote/rich-text/seo/slider、data/data.json种子数据与scripts/seed.jsexample-js--example --js同上JavaScript 版以 templates/vanilla 为例其config/目录包含admin.ts、api.ts、database.ts、middlewares.ts、plugins.ts、server.ts六个配置文件templates/example 的src/api/下则已有完整的 content-types/services/controllers/routes 四层结构适合直接上手研究 Strapi 项目组织方式。外部模板机制--template 的四种解析路径指定--template后copyTemplate 按以下优先级解析模板来源所有网络拉取均带 3 次重试官方模板名纯字母字符串/^[a-zA-Z]*$/会先向 GitHub API 发 HEAD 请求确认strapi/strapi仓库templates/name目录存在然后下载该仓库对应分支的 tarball 并解压其中templates/name子路径template.ts L23-L41。仓库根的 templates 目录 就是官方模板的存放处例如 templates/website。本地路径以file://开头或解析后本地存在的目录直接fse.copy复制。GitHub 简写形如owner/repo或owner/repo/path的非 URL 字符串isGithubShorthand从对应仓库下载subPath取剩余路径段或--template-path。GitHub 完整 URL形如https://github.com/owner/repo/tree/branch/path的地址解析出 owner/repo/branch/路径isGithubRepo同样下载对应 tarball 子路径。--template-branch与--template-path用于覆盖分支与子路径。再次强调约束使用--template时不能再叠加--example、--js、--ts因为模板自身决定了语言与结构。数据库配置从 CLI 参数到 .env 落地数据库解析逻辑在 getDatabaseInfos 中行为决策树为--skip-db直接返回默认配置sqlite.tmp/data.db--dbclient取值必须是sqlite/mysql/postgres之一否则 fatal“Invalid --dbclient ... expected one of sqlite, postgres, mysql”只要提供了任意--db*参数dbclient/dbhost/dbport/dbname/dbusername/dbpassword六项之一即视为“参数模式”非 sqlite 时必须六项齐全缺任何一项都会报 “Required database arguments are missing: ...”sqlite 可只给--dbclient sqlite加可选的--dbfile完全没给--db*参数时--quickstart或--non-interactive下直接用 sqlite 默认值交互模式下进入dbPrompt问答。--dbssl的取值会被解析为布尔true为开仅对 postgres/mysql 有意义。驱动依赖自动注入addDatabaseDependencies 按客户端把对应驱动写入项目依赖当前仓库中锁定的版本为客户端驱动版本mysqlmysql23.20.0postgrespg8.20.0sqlitebetter-sqlite312.8.0生成的.env中DATABASE_CLIENT等变量与上述选择一一对应之后 config/database.ts 这类项目配置文件即可读取这些环境变量完成连接无需改动代码。包管理器选择与自动检测getPkgManager 的决策顺序显式参数优先--use-npm→npm--use-pnpm→pnpm--use-yarn→yarn未显式指定时读取环境变量npm_config_user_agent以yarn开头则用 yarn以pnpm开头则用 pnpm兜底为npm。这个机制保证了在 yarn/pnpm 环境里执行yarn create strapi-app或pnpm create ...时后续 install、seed、develop 等子命令会自动沿用你当前使用的包管理器无需额外声明。非交互模式与自动化场景对 CI/CD 或脚本化创建项目推荐用--non-interactive--quickstart已标记 deprecated。该模式下所有布尔选项走 resolveOption 的默认值分支安装依赖、git init、TypeScript、sqlite 数据库。一个完整的自动化示例# 非交互创建 TypeScript 空项目跳过 cloud 登录不自动安装依赖 npx create-strapi-app my-app --non-interactive --skip-cloud --no-install --no-git-init # 非交互创建并直接指定远程 postgres六项参数需齐全 npx create-strapi-app my-app --non-interactive --skip-cloud \ --dbclient postgres --dbhost db.example.com --dbport 5432 \ --dbname strapi --dbusername strapi --dbpassword secret --dbssl true需要牢记的自动化约束非交互模式必须提供directory--dbclient为 mysql/postgres 时六个--db*参数缺一不可想完全不配数据库就用--skip-db。故障排查要点源码中的错误处理给出了明确的自救路径依赖安装失败createApp会捕获 install 错误并提示——“项目已正确创建”手动进入目录补装即可create-strapi.ts L209-L219cd my-project yarn install # 或 npm install / pnpm install目标目录非空换到空目录或先清空要求最多只允许 1 个文件存在。外部模板失败确认模板仓库/分支/路径存在CLI 会先 HEAD 检查且模板内必须含package.json--template-branch拼写错误是常见原因。seed 失败使用--example且自动种子失败时仅跳过可事后手动执行packageManager run seed:example重试。版本问题Node 版本不满足20.0.0 26.x.x时 CLI 会直接终止切换 Node 版本后即可重试。小结create-strapi-app是 Strapi v5 中开箱创建项目的官方入口三种等价启动方式yarn create / npx / 全局安装、一套完整的参数体系语言、包管理器、数据库、模板、git、非交互以及一套有清理保障的生成流程模板拷贝 → package.json/.env → 依赖安装 → git 初始化 → 种子数据。日常开发用交互式默认值即可在 CI 或批量创建场景中组合--non-interactive --skip-cloud与--db*/--skip-db参数即可完全脚本化。所有行为均可在 packages/cli/create-strapi-app 的源码中逐行核对内置模板可直接参考 templates/vanilla 与 templates/example 的结构。【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考