到項目生成流程的完整解析)
Strapi create-strapi-app 使用指南從 CLI 參數(shù)到項目生成流程的完整解析【免費下載鏈接】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 及其源碼系統(tǒng)講解如何用create-strapi-appCLI 創(chuàng)建一個全新的 Strapi 項目包括yarn create/npx/ 全局安裝三種啟動方式、全部命令行參數(shù)與默認(rèn)值、模板機(jī)制內(nèi)置 vanilla/example 與外部 GitHub/本地模板、數(shù)據(jù)庫配置邏輯以及 CLI 內(nèi)部的完整項目生成流程與故障恢復(fù)方法。讀完后你可以獨立、可復(fù)現(xiàn)地完成交互式或非交互式CI 場景的 Strapi 項目初始化。前置要求Node.js 與 npm 版本CLI 在運行任何邏輯之前會先做環(huán)境校驗。從 engines 定義 與 package.json 的engines字段可以確認(rèn)當(dāng)前版本5.52.2的要求Node.js20.0.0 26.x.xnpm6.0.0checkNodeRequirements 函數(shù)的具體行為是若當(dāng)前 Node 版本不滿足engines.node范圍直接logger.fatal終止并提示“Strapi requires Node.js 20.0.0 26.x.x”若 Node 大版本小于 26 且為奇數(shù)非 LTS則打印警告提示 Strapi 僅支持 Node.js LTS 版本其他版本可能存在兼容性問題。因此建議始終使用偶數(shù) LTS 版本如 Node 20、22、24運行該 CLI。安裝與快速開始README 給出了三種等價的啟動方式核心都是調(diào)用create-strapi-app的二進(jìn)制入口bin: ./bin/index.js見 package.json并將項目目錄名作為第一個參數(shù)方式一yarn create推薦yarn create strapi-app my-project方式二npxnpx create-strapi-app my-project方式三全局安裝后直接調(diào)用# yarn yarn global add create-strapi-app create-strapi-app my-app # npm npm install -g create-strapi-app create-strapi-app my-app執(zhí)行后 CLI 會依次詢問若干問題見下文“交互式提示”一節(jié)默認(rèn)行為是創(chuàng)建 TypeScript 項目、使用 sqlite 數(shù)據(jù)庫、自動安裝依賴并初始化 git 倉庫。一個典型的非交互自動化調(diào)用示例可參考后文的--non-interactive組合npx create-strapi-app my-project --non-interactive --skip-cloud --no-install交互式提示與默認(rèn)值交互式問題全部集中在 prompts.ts 與 utils/database.ts 中使用inquirer實現(xiàn)。逐項默認(rèn)值如下問題來源默認(rèn)值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其中幾個值得注意的細(xì)節(jié)數(shù)據(jù)庫名輸入若包含.會被校驗函數(shù)直接拒絕“The database name cant contain a .”選擇 sqlite 時只問一個filename默認(rèn).tmp/data.db選擇 postgres/mysql 時問database/host/port/username/password/ssl六項這些選擇最終會被寫入項目根目錄的.env文件見下文“環(huán)境變量”小節(jié)。完整命令行參數(shù)參考所有選項在 src/index.ts 的 commander 定義 中聲明參數(shù)類型為 Options 接口。完整清單如下參數(shù)說明create-strapi-app [directory]位置參數(shù)項目目錄缺省時交互式詢問默認(rèn)my-strapi-project--quickstart快速創(chuàng)建源碼中標(biāo)注 deprecated等價于跳過交互并使用默認(rèn)值--no-run創(chuàng)建后不自動啟動應(yīng)用--ts, --typescript使用 TypeScript 初始化默認(rèn)--js, --javascript使用 JavaScript 初始化--use-npm/--use-yarn/--use-pnpm指定包管理器--install安裝依賴--no-install不安裝依賴--skip-cloud跳過 Cloud 登錄與項目創(chuàng)建--example使用示例應(yīng)用帶內(nèi)容類型與種子數(shù)據(jù)--no-example不使用示例應(yīng)用--git-init初始化 git 倉庫--no-git-init不初始化 git 倉庫--non-interactive跳過所有交互式提示并使用默認(rèn)值自動化場景關(guān)鍵參數(shù)--dbclient dbclient數(shù)據(jù)庫客戶端sqlite/mysql/postgres--dbhost dbhost數(shù)據(jù)庫主機(jī)--dbport dbport數(shù)據(jù)庫端口--dbname dbname數(shù)據(jù)庫名--dbusername dbusername數(shù)據(jù)庫用戶名--dbpassword dbpassword數(shù)據(jù)庫密碼--dbssl dbssl數(shù)據(jù)庫 SSL傳true表示開啟--dbfile dbfilesqlite 數(shù)據(jù)庫文件路徑--skip-db跳過數(shù)據(jù)庫配置直接使用 sqlite 默認(rèn)值--template template指定一個 Strapi 模板官方/本地/GitHub--template-branch branch模板的分支--template-path path模板倉庫內(nèi)的子路徑此外源碼中還注冊了兩個隱藏的參數(shù)--enable-ab-tests/--no-enable-ab-tests注釋明確說明它們是“Legacy no-ops”僅為兼容舊 CI 腳本而存在實際被忽略index.ts L53-L55。參數(shù)沖突與硬性校驗index.ts 的 run 函數(shù) 在進(jìn)入主流程前做了一組互斥校驗任何一條觸發(fā)都會logger.fatal終止--javascript/--typescript不能與--template同時使用--typescript與--javascript不能同時使用--example不能與--template同時使用模板名不能以-開頭--use-npm、--use-pnpm、--use-yarn不能同時指定多個使用--quickstart或--non-interactive時必須顯式提供directory位置參數(shù)。另有一個安裝路徑校驗 checkInstallPath目標(biāo)目錄若已存在必須是一個目錄且最多只能有 1 個文件實際要求接近空目錄否則會報 “You can only create a Strapi app in an empty directory”。項目生成流程從目錄創(chuàng)建到種子數(shù)據(jù)核心編排邏輯在 src/create-strapi.ts 中。createStrapi先ensureDir創(chuàng)建目標(biāo)目錄隨后createApp按以下順序執(zhí)行任一步失敗都會fse.remove(rootPath)清理已生成的目錄后拋錯保證不留半成品拷貝模板未指定--template時按useExample與useTypescript組合選擇內(nèi)置模板example/vanilla/example-js/vanilla-js從包內(nèi)templates/目錄整體復(fù)制到目標(biāo)路徑create-strapi.ts L113-L123指定--template時調(diào)用 copyTemplate 拉取外部模板完成后強(qiáng)制檢查package.json是否存在缺失則報 “Missing package.json in template”。寫 package.jsoncreatePackageJSON 生成項目的package.json并合并 scope 中的依賴聲明。其中 index.ts L168-L179 預(yù)置了核心依賴當(dāng)前版本的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內(nèi)容包含服務(wù)端口HOST0.0.0.0、PORT1337六個隨機(jī)生成的密鑰crypto.randomBytes(16).toString(base64)APP_KEYS4 段拼接、API_TOKEN_SALT、ADMIN_JWT_SECRET、JWT_SECRET、TRANSFER_TOKEN_SALT、ENCRYPTION_KEY數(shù)據(jù)庫段落DATABASE_CLIENT、DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_SSL、DATABASE_FILENAME與前面數(shù)據(jù)庫配置的選擇一一對應(yīng)。包管理器專屬配置yarn ≥ 3 且項目內(nèi)不存在.yarnrc.yml時寫入nodeLinker: node-modulescreate-strapi.ts L160-L165pnpm 時解析其版本并寫入相應(yīng) workspace 配置writePnpmWorkspaceConfig。安裝依賴當(dāng)installDependencies為真runInstall 用execa調(diào)用所選包管理器的 install 命令并注入NODE_ENVdevelopment與包管理器相關(guān)的環(huán)境變量。.gitignore與 git 初始化無論用戶是否啟用 git都會確保寫出.gitignore內(nèi)容來自 gitignore.ts若gitInit為真則 tryGitInit 執(zhí)行g(shù)it init。示例數(shù)據(jù)種子僅當(dāng)useExample installDependencies且存在scripts/seed.js時執(zhí)行packageManager run seed:example失敗只打印 “Failed to seed your database. Skipping”不視為致命錯誤。可選的自動啟動--quickstart且未禁用run且依賴已安裝時會以stdio: inherit直接執(zhí)行packageManager run developcreate-strapi.ts L299-L323。創(chuàng)建結(jié)束后的輸出與推薦命令流程末尾CLI 會打印項目內(nèi)可用的命令create-strapi.ts L255-L297packageManager run develop # 監(jiān)聽模式啟動開發(fā) packageManager run start # 無監(jiān)聽模式啟動 packageManager run build # 構(gòu)建管理后臺 packageManager run deploy # 部署 packageManager run strapi # 查看全部命令若使用了示例應(yīng)用還會額外提示packageManager run seed:example用于灌入示例數(shù)據(jù)。最終給出的啟動指引按依賴是否已安裝分兩種# 已安裝依賴 cd my-project yarn run develop # 或 npm / pnpm run develop # 未安裝依賴--no-install 場景 cd my-project packageManager install packageManager run develop內(nèi)置模板vanilla 與 example 兩種起步方式CLI 包內(nèi)自帶四套模板位于 packages/cli/create-strapi-app/templates模板名觸發(fā)條件特點vanilla默認(rèn)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 基礎(chǔ)上預(yù)置 about/article/author/category/global 等內(nèi)容類型、shared 組件media/quote/rich-text/seo/slider、data/data.json種子數(shù)據(jù)與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 四層結(jié)構(gòu)適合直接上手研究 Strapi 項目組織方式。外部模板機(jī)制--template 的四種解析路徑指定--template后copyTemplate 按以下優(yōu)先級解析模板來源所有網(wǎng)絡(luò)拉取均帶 3 次重試官方模板名純字母字符串/^[a-zA-Z]*$/會先向 GitHub API 發(fā) HEAD 請求確認(rèn)strapi/strapi倉庫templates/name目錄存在然后下載該倉庫對應(yīng)分支的 tarball 并解壓其中templates/name子路徑template.ts L23-L41。倉庫根的 templates 目錄 就是官方模板的存放處例如 templates/website。本地路徑以file://開頭或解析后本地存在的目錄直接fse.copy復(fù)制。GitHub 簡寫形如owner/repo或owner/repo/path的非 URL 字符串isGithubShorthand從對應(yīng)倉庫下載subPath取剩余路徑段或--template-path。GitHub 完整 URL形如https://github.com/owner/repo/tree/branch/path的地址解析出 owner/repo/branch/路徑isGithubRepo同樣下載對應(yīng) tarball 子路徑。--template-branch與--template-path用于覆蓋分支與子路徑。再次強(qiáng)調(diào)約束使用--template時不能再疊加--example、--js、--ts因為模板自身決定了語言與結(jié)構(gòu)。數(shù)據(jù)庫配置從 CLI 參數(shù)到 .env 落地數(shù)據(jù)庫解析邏輯在 getDatabaseInfos 中行為決策樹為--skip-db直接返回默認(rèn)配置sqlite.tmp/data.db--dbclient取值必須是sqlite/mysql/postgres之一否則 fatal“Invalid --dbclient ... expected one of sqlite, postgres, mysql”只要提供了任意--db*參數(shù)dbclient/dbhost/dbport/dbname/dbusername/dbpassword六項之一即視為“參數(shù)模式”非 sqlite 時必須六項齊全缺任何一項都會報 “Required database arguments are missing: ...”sqlite 可只給--dbclient sqlite加可選的--dbfile完全沒給--db*參數(shù)時--quickstart或--non-interactive下直接用 sqlite 默認(rèn)值交互模式下進(jìn)入dbPrompt問答。--dbssl的取值會被解析為布爾true為開僅對 postgres/mysql 有意義。驅(qū)動依賴自動注入addDatabaseDependencies 按客戶端把對應(yīng)驅(qū)動寫入項目依賴當(dāng)前倉庫中鎖定的版本為客戶端驅(qū)動版本mysqlmysql23.20.0postgrespg8.20.0sqlitebetter-sqlite312.8.0生成的.env中DATABASE_CLIENT等變量與上述選擇一一對應(yīng)之后 config/database.ts 這類項目配置文件即可讀取這些環(huán)境變量完成連接無需改動代碼。包管理器選擇與自動檢測getPkgManager 的決策順序顯式參數(shù)優(yōu)先--use-npm→npm--use-pnpm→pnpm--use-yarn→yarn未顯式指定時讀取環(huán)境變量npm_config_user_agent以yarn開頭則用 yarn以pnpm開頭則用 pnpm兜底為npm。這個機(jī)制保證了在 yarn/pnpm 環(huán)境里執(zhí)行yarn create strapi-app或pnpm create ...時后續(xù) install、seed、develop 等子命令會自動沿用你當(dāng)前使用的包管理器無需額外聲明。非交互模式與自動化場景對 CI/CD 或腳本化創(chuàng)建項目推薦用--non-interactive--quickstart已標(biāo)記 deprecated。該模式下所有布爾選項走 resolveOption 的默認(rèn)值分支安裝依賴、git init、TypeScript、sqlite 數(shù)據(jù)庫。一個完整的自動化示例# 非交互創(chuàng)建 TypeScript 空項目跳過 cloud 登錄不自動安裝依賴 npx create-strapi-app my-app --non-interactive --skip-cloud --no-install --no-git-init # 非交互創(chuàng)建并直接指定遠(yuǎn)程 postgres六項參數(shù)需齊全 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*參數(shù)缺一不可想完全不配數(shù)據(jù)庫就用--skip-db。故障排查要點源碼中的錯誤處理給出了明確的自救路徑依賴安裝失敗createApp會捕獲 install 錯誤并提示——“項目已正確創(chuàng)建”手動進(jìn)入目錄補(bǔ)裝即可create-strapi.ts L209-L219cd my-project yarn install # 或 npm install / pnpm install目標(biāo)目錄非空換到空目錄或先清空要求最多只允許 1 個文件存在。外部模板失敗確認(rèn)模板倉庫/分支/路徑存在CLI 會先 HEAD 檢查且模板內(nèi)必須含package.json--template-branch拼寫錯誤是常見原因。seed 失敗使用--example且自動種子失敗時僅跳過可事后手動執(zhí)行packageManager run seed:example重試。版本問題Node 版本不滿足20.0.0 26.x.x時 CLI 會直接終止切換 Node 版本后即可重試。小結(jié)create-strapi-app是 Strapi v5 中開箱創(chuàng)建項目的官方入口三種等價啟動方式y(tǒng)arn create / npx / 全局安裝、一套完整的參數(shù)體系語言、包管理器、數(shù)據(jù)庫、模板、git、非交互以及一套有清理保障的生成流程模板拷貝 → package.json/.env → 依賴安裝 → git 初始化 → 種子數(shù)據(jù)。日常開發(fā)用交互式默認(rèn)值即可在 CI 或批量創(chuàng)建場景中組合--non-interactive --skip-cloud與--db*/--skip-db參數(shù)即可完全腳本化。所有行為均可在 packages/cli/create-strapi-app 的源碼中逐行核對內(nèi)置模板可直接參考 templates/vanilla 與 templates/example 的結(jié)構(gòu)?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Strapi create-strapi-app 使用指南：從 CLI 參數(shù)到項目生成流程的完整解析
Strapi create-strapi-app 使用指南從 CLI 參數(shù)到項目生成流程的完整解析【免費下載鏈接】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 及其源碼系統(tǒng)講解如何用create-strapi-appCLI 創(chuàng)建一個全新的 Strapi 項目包括yarn create/npx/ 全局安裝三種啟動方式、全部命令行參數(shù)與默認(rèn)值、模板機(jī)制內(nèi)置 vanilla/example 與外部 GitHub/本地模板、數(shù)據(jù)庫配置邏輯以及 CLI 內(nèi)部的完整項目生成流程與故障恢復(fù)方法。讀完后你可以獨立、可復(fù)現(xiàn)地完成交互式或非交互式CI 場景的 Strapi 項目初始化。前置要求Node.js 與 npm 版本CLI 在運行任何邏輯之前會先做環(huán)境校驗。從 engines 定義 與 package.json 的engines字段可以確認(rèn)當(dāng)前版本5.52.2的要求Node.js20.0.0 26.x.xnpm6.0.0checkNodeRequirements 函數(shù)的具體行為是若當(dāng)前 Node 版本不滿足engines.node范圍直接logger.fatal終止并提示“Strapi requires Node.js 20.0.0 26.x.x”若 Node 大版本小于 26 且為奇數(shù)非 LTS則打印警告提示 Strapi 僅支持 Node.js LTS 版本其他版本可能存在兼容性問題。因此建議始終使用偶數(shù) LTS 版本如 Node 20、22、24運行該 CLI。安裝與快速開始README 給出了三種等價的啟動方式核心都是調(diào)用create-strapi-app的二進(jìn)制入口bin: ./bin/index.js見 package.json并將項目目錄名作為第一個參數(shù)方式一yarn create推薦yarn create strapi-app my-project方式二npxnpx create-strapi-app my-project方式三全局安裝后直接調(diào)用# yarn yarn global add create-strapi-app create-strapi-app my-app # npm npm install -g create-strapi-app create-strapi-app my-app執(zhí)行后 CLI 會依次詢問若干問題見下文“交互式提示”一節(jié)默認(rèn)行為是創(chuàng)建 TypeScript 項目、使用 sqlite 數(shù)據(jù)庫、自動安裝依賴并初始化 git 倉庫。一個典型的非交互自動化調(diào)用示例可參考后文的--non-interactive組合npx create-strapi-app my-project --non-interactive --skip-cloud --no-install交互式提示與默認(rèn)值交互式問題全部集中在 prompts.ts 與 utils/database.ts 中使用inquirer實現(xiàn)。逐項默認(rèn)值如下問題來源默認(rèn)值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其中幾個值得注意的細(xì)節(jié)數(shù)據(jù)庫名輸入若包含.會被校驗函數(shù)直接拒絕“The database name cant contain a .”選擇 sqlite 時只問一個filename默認(rèn).tmp/data.db選擇 postgres/mysql 時問database/host/port/username/password/ssl六項這些選擇最終會被寫入項目根目錄的.env文件見下文“環(huán)境變量”小節(jié)。完整命令行參數(shù)參考所有選項在 src/index.ts 的 commander 定義 中聲明參數(shù)類型為 Options 接口。完整清單如下參數(shù)說明create-strapi-app [directory]位置參數(shù)項目目錄缺省時交互式詢問默認(rèn)my-strapi-project--quickstart快速創(chuàng)建源碼中標(biāo)注 deprecated等價于跳過交互并使用默認(rèn)值--no-run創(chuàng)建后不自動啟動應(yīng)用--ts, --typescript使用 TypeScript 初始化默認(rèn)--js, --javascript使用 JavaScript 初始化--use-npm/--use-yarn/--use-pnpm指定包管理器--install安裝依賴--no-install不安裝依賴--skip-cloud跳過 Cloud 登錄與項目創(chuàng)建--example使用示例應(yīng)用帶內(nèi)容類型與種子數(shù)據(jù)--no-example不使用示例應(yīng)用--git-init初始化 git 倉庫--no-git-init不初始化 git 倉庫--non-interactive跳過所有交互式提示并使用默認(rèn)值自動化場景關(guān)鍵參數(shù)--dbclient dbclient數(shù)據(jù)庫客戶端sqlite/mysql/postgres--dbhost dbhost數(shù)據(jù)庫主機(jī)--dbport dbport數(shù)據(jù)庫端口--dbname dbname數(shù)據(jù)庫名--dbusername dbusername數(shù)據(jù)庫用戶名--dbpassword dbpassword數(shù)據(jù)庫密碼--dbssl dbssl數(shù)據(jù)庫 SSL傳true表示開啟--dbfile dbfilesqlite 數(shù)據(jù)庫文件路徑--skip-db跳過數(shù)據(jù)庫配置直接使用 sqlite 默認(rèn)值--template template指定一個 Strapi 模板官方/本地/GitHub--template-branch branch模板的分支--template-path path模板倉庫內(nèi)的子路徑此外源碼中還注冊了兩個隱藏的參數(shù)--enable-ab-tests/--no-enable-ab-tests注釋明確說明它們是“Legacy no-ops”僅為兼容舊 CI 腳本而存在實際被忽略index.ts L53-L55。參數(shù)沖突與硬性校驗index.ts 的 run 函數(shù) 在進(jìn)入主流程前做了一組互斥校驗任何一條觸發(fā)都會logger.fatal終止--javascript/--typescript不能與--template同時使用--typescript與--javascript不能同時使用--example不能與--template同時使用模板名不能以-開頭--use-npm、--use-pnpm、--use-yarn不能同時指定多個使用--quickstart或--non-interactive時必須顯式提供directory位置參數(shù)。另有一個安裝路徑校驗 checkInstallPath目標(biāo)目錄若已存在必須是一個目錄且最多只能有 1 個文件實際要求接近空目錄否則會報 “You can only create a Strapi app in an empty directory”。項目生成流程從目錄創(chuàng)建到種子數(shù)據(jù)核心編排邏輯在 src/create-strapi.ts 中。createStrapi先ensureDir創(chuàng)建目標(biāo)目錄隨后createApp按以下順序執(zhí)行任一步失敗都會fse.remove(rootPath)清理已生成的目錄后拋錯保證不留半成品拷貝模板未指定--template時按useExample與useTypescript組合選擇內(nèi)置模板example/vanilla/example-js/vanilla-js從包內(nèi)templates/目錄整體復(fù)制到目標(biāo)路徑create-strapi.ts L113-L123指定--template時調(diào)用 copyTemplate 拉取外部模板完成后強(qiáng)制檢查package.json是否存在缺失則報 “Missing package.json in template”。寫 package.jsoncreatePackageJSON 生成項目的package.json并合并 scope 中的依賴聲明。其中 index.ts L168-L179 預(yù)置了核心依賴當(dāng)前版本的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內(nèi)容包含服務(wù)端口HOST0.0.0.0、PORT1337六個隨機(jī)生成的密鑰crypto.randomBytes(16).toString(base64)APP_KEYS4 段拼接、API_TOKEN_SALT、ADMIN_JWT_SECRET、JWT_SECRET、TRANSFER_TOKEN_SALT、ENCRYPTION_KEY數(shù)據(jù)庫段落DATABASE_CLIENT、DATABASE_HOST、DATABASE_PORT、DATABASE_NAME、DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_SSL、DATABASE_FILENAME與前面數(shù)據(jù)庫配置的選擇一一對應(yīng)。包管理器專屬配置yarn ≥ 3 且項目內(nèi)不存在.yarnrc.yml時寫入nodeLinker: node-modulescreate-strapi.ts L160-L165pnpm 時解析其版本并寫入相應(yīng) workspace 配置writePnpmWorkspaceConfig。安裝依賴當(dāng)installDependencies為真runInstall 用execa調(diào)用所選包管理器的 install 命令并注入NODE_ENVdevelopment與包管理器相關(guān)的環(huán)境變量。.gitignore與 git 初始化無論用戶是否啟用 git都會確保寫出.gitignore內(nèi)容來自 gitignore.ts若gitInit為真則 tryGitInit 執(zhí)行g(shù)it init。示例數(shù)據(jù)種子僅當(dāng)useExample installDependencies且存在scripts/seed.js時執(zhí)行packageManager run seed:example失敗只打印 “Failed to seed your database. Skipping”不視為致命錯誤。可選的自動啟動--quickstart且未禁用run且依賴已安裝時會以stdio: inherit直接執(zhí)行packageManager run developcreate-strapi.ts L299-L323。創(chuàng)建結(jié)束后的輸出與推薦命令流程末尾CLI 會打印項目內(nèi)可用的命令create-strapi.ts L255-L297packageManager run develop # 監(jiān)聽模式啟動開發(fā) packageManager run start # 無監(jiān)聽模式啟動 packageManager run build # 構(gòu)建管理后臺 packageManager run deploy # 部署 packageManager run strapi # 查看全部命令若使用了示例應(yīng)用還會額外提示packageManager run seed:example用于灌入示例數(shù)據(jù)。最終給出的啟動指引按依賴是否已安裝分兩種# 已安裝依賴 cd my-project yarn run develop # 或 npm / pnpm run develop # 未安裝依賴--no-install 場景 cd my-project packageManager install packageManager run develop內(nèi)置模板vanilla 與 example 兩種起步方式CLI 包內(nèi)自帶四套模板位于 packages/cli/create-strapi-app/templates模板名觸發(fā)條件特點vanilla默認(rèn)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 基礎(chǔ)上預(yù)置 about/article/author/category/global 等內(nèi)容類型、shared 組件media/quote/rich-text/seo/slider、data/data.json種子數(shù)據(jù)與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 四層結(jié)構(gòu)適合直接上手研究 Strapi 項目組織方式。外部模板機(jī)制--template 的四種解析路徑指定--template后copyTemplate 按以下優(yōu)先級解析模板來源所有網(wǎng)絡(luò)拉取均帶 3 次重試官方模板名純字母字符串/^[a-zA-Z]*$/會先向 GitHub API 發(fā) HEAD 請求確認(rèn)strapi/strapi倉庫templates/name目錄存在然后下載該倉庫對應(yīng)分支的 tarball 并解壓其中templates/name子路徑template.ts L23-L41。倉庫根的 templates 目錄 就是官方模板的存放處例如 templates/website。本地路徑以file://開頭或解析后本地存在的目錄直接fse.copy復(fù)制。GitHub 簡寫形如owner/repo或owner/repo/path的非 URL 字符串isGithubShorthand從對應(yīng)倉庫下載subPath取剩余路徑段或--template-path。GitHub 完整 URL形如https://github.com/owner/repo/tree/branch/path的地址解析出 owner/repo/branch/路徑isGithubRepo同樣下載對應(yīng) tarball 子路徑。--template-branch與--template-path用于覆蓋分支與子路徑。再次強(qiáng)調(diào)約束使用--template時不能再疊加--example、--js、--ts因為模板自身決定了語言與結(jié)構(gòu)。數(shù)據(jù)庫配置從 CLI 參數(shù)到 .env 落地數(shù)據(jù)庫解析邏輯在 getDatabaseInfos 中行為決策樹為--skip-db直接返回默認(rèn)配置sqlite.tmp/data.db--dbclient取值必須是sqlite/mysql/postgres之一否則 fatal“Invalid --dbclient ... expected one of sqlite, postgres, mysql”只要提供了任意--db*參數(shù)dbclient/dbhost/dbport/dbname/dbusername/dbpassword六項之一即視為“參數(shù)模式”非 sqlite 時必須六項齊全缺任何一項都會報 “Required database arguments are missing: ...”sqlite 可只給--dbclient sqlite加可選的--dbfile完全沒給--db*參數(shù)時--quickstart或--non-interactive下直接用 sqlite 默認(rèn)值交互模式下進(jìn)入dbPrompt問答。--dbssl的取值會被解析為布爾true為開僅對 postgres/mysql 有意義。驅(qū)動依賴自動注入addDatabaseDependencies 按客戶端把對應(yīng)驅(qū)動寫入項目依賴當(dāng)前倉庫中鎖定的版本為客戶端驅(qū)動版本mysqlmysql23.20.0postgrespg8.20.0sqlitebetter-sqlite312.8.0生成的.env中DATABASE_CLIENT等變量與上述選擇一一對應(yīng)之后 config/database.ts 這類項目配置文件即可讀取這些環(huán)境變量完成連接無需改動代碼。包管理器選擇與自動檢測getPkgManager 的決策順序顯式參數(shù)優(yōu)先--use-npm→npm--use-pnpm→pnpm--use-yarn→yarn未顯式指定時讀取環(huán)境變量npm_config_user_agent以yarn開頭則用 yarn以pnpm開頭則用 pnpm兜底為npm。這個機(jī)制保證了在 yarn/pnpm 環(huán)境里執(zhí)行yarn create strapi-app或pnpm create ...時后續(xù) install、seed、develop 等子命令會自動沿用你當(dāng)前使用的包管理器無需額外聲明。非交互模式與自動化場景對 CI/CD 或腳本化創(chuàng)建項目推薦用--non-interactive--quickstart已標(biāo)記 deprecated。該模式下所有布爾選項走 resolveOption 的默認(rèn)值分支安裝依賴、git init、TypeScript、sqlite 數(shù)據(jù)庫。一個完整的自動化示例# 非交互創(chuàng)建 TypeScript 空項目跳過 cloud 登錄不自動安裝依賴 npx create-strapi-app my-app --non-interactive --skip-cloud --no-install --no-git-init # 非交互創(chuàng)建并直接指定遠(yuǎn)程 postgres六項參數(shù)需齊全 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*參數(shù)缺一不可想完全不配數(shù)據(jù)庫就用--skip-db。故障排查要點源碼中的錯誤處理給出了明確的自救路徑依賴安裝失敗createApp會捕獲 install 錯誤并提示——“項目已正確創(chuàng)建”手動進(jìn)入目錄補(bǔ)裝即可create-strapi.ts L209-L219cd my-project yarn install # 或 npm install / pnpm install目標(biāo)目錄非空換到空目錄或先清空要求最多只允許 1 個文件存在。外部模板失敗確認(rèn)模板倉庫/分支/路徑存在CLI 會先 HEAD 檢查且模板內(nèi)必須含package.json--template-branch拼寫錯誤是常見原因。seed 失敗使用--example且自動種子失敗時僅跳過可事后手動執(zhí)行packageManager run seed:example重試。版本問題Node 版本不滿足20.0.0 26.x.x時 CLI 會直接終止切換 Node 版本后即可重試。小結(jié)create-strapi-app是 Strapi v5 中開箱創(chuàng)建項目的官方入口三種等價啟動方式y(tǒng)arn create / npx / 全局安裝、一套完整的參數(shù)體系語言、包管理器、數(shù)據(jù)庫、模板、git、非交互以及一套有清理保障的生成流程模板拷貝 → package.json/.env → 依賴安裝 → git 初始化 → 種子數(shù)據(jù)。日常開發(fā)用交互式默認(rèn)值即可在 CI 或批量創(chuàng)建場景中組合--non-interactive --skip-cloud與--db*/--skip-db參數(shù)即可完全腳本化。所有行為均可在 packages/cli/create-strapi-app 的源碼中逐行核對內(nèi)置模板可直接參考 templates/vanilla 與 templates/example 的結(jié)構(gòu)?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考