create-medusa-app 完全指南一条命令搭建 Medusa 后端、Admin 与 PostgreSQL 数据库【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusacreate-medusa-app是 Medusa 官方提供的零配置脚手架 CLI只需在终端执行一条 npx 命令就能完成 Medusa 后端、Admin 控制台与 PostgreSQL 数据库的初始化与连接并在最后自动打开管理后台。本文将基于 create-medusa-app 官方 README 展开结合 create-medusa-app 包源码 逐一剖析其全部命令行选项、交互式引导流程、数据库创建逻辑、环境变量注入、迁移与种子数据执行等底层实现让你既能快速上手也能在排查问题时知道它到底做了什么。快速开始一次命令完成全栈初始化在终端中执行以下命令即可开始创建 Medusa 项目npx create-medusa-applatest随后CLI 会以问答形式引导你完成两项核心配置项目名称默认值为my-medusa-store输入的名称会被 slugify 规范化转小写、去特殊字符PostgreSQL 数据库CLI 会先尝试用postgres用户名和空密码连接本机 PostgreSQL若失败则询问你输入 Postgres 用户名、密码以及该用户默认所在的数据库名。完成上述引导后CLI 会自动克隆官方 starter 仓库、安装依赖、创建数据库、运行迁移并创建管理员账号整个过程this may take a few minutes可能需要数分钟。全部就绪后Medusa Admin 管理后台会自动在你的默认浏览器中打开这是 README 明确描述的默认行为。对应这一交互式命令的源码入口在 src/index.ts它基于commander解析参数随后调用 src/commands/create.ts 中的create处理器最终由ProjectCreatorFactory决定创建项目还是插件详见下文。全部命令行选项详解README 只收录了两个选项--repo-url与--seed但当前仓库源码 src/index.ts 实际上暴露了远为完整的参数集合。下表完整汇总了所有可用选项其中前两行即 README 原表内容选项说明默认值--repo-url url从指定的仓库 URL 创建 Medusa 项目官方 starter 仓库README 记为https://github.com/medusajs/medusa-starter-default当前源码 clone-repo.ts 中的DEFAULT_REPO实际为https://github.com/medusajs/dtc-starter以源码为准--seed使用该选项时会用演示数据填充数据库false[project-name]位置参数直接指定项目名跳过名称问答交互式询问默认my-medusa-store--plugin创建 Medusa 插件项目而非完整商城项目false--version version指定要安装的 Medusa 包版本使用 starter 默认版本--skip-db跳过数据库创建、迁移和种子填充同时跳过打开浏览器false--db-url url跳过数据库创建直接使用提供的连接 URL若无法连接会报错。仍会执行迁移并在创建完成后打开 Admin无--no-migrations跳过迁移、管理员用户创建和种子填充。若使用该选项官方建议配合--db-url指向一个已完成全部迁移的数据库否则可能出现意外错误true即默认执行迁移--no-browser禁用创建完成后自动打开浏览器仅展示成功消息true即默认打开浏览器--directory-path path指定安装项目的目录路径当前目录--with-nextjs-starter在 Medusa 后端之外同时安装 Next.js 商店前端false--verbose显示底层命令的全部日志便于调试false--use-npm/--use-yarn/--use-pnpm显式指定包管理器三者互斥conflicts校验自动探测源码中值得注意的参数语义细节--no-migrations与--no-browser是 commander 的否定式选项声明时默认值为true意味着执行迁移打开浏览器在默认情况下均开启--skip-db是总开关在 medusa-project-creator.ts 的startServices中skipDb || !browser任一成立都会直接打印成功消息并退出进程不再启动服务和打开浏览器--db-url走完全不同的数据库分支见 create-db.ts 的getDbClientAndCredentials优先检查db-url命中后直接基于连接字符串建立pg.Client不再询问用户名密码也不执行建库。交互式引导流程逐段拆解整个创建过程在 medusa-project-creator.ts 的create()中分为三个阶段initializeProject→setupProject→startServices。1. 项目名与目录校验project-creator-factory.ts 的getProjectName负责处理项目名若命令行未传项目名则通过inquirer询问默认值my-medusa-store插件模式为my-medusa-plugin输入经过slugify(input).toLowerCase()规范化项目名不允许包含点号.源码注释说明这是为了避免 MikroORM 路径解析问题若目标目录已存在同名文件夹会提示换名校验通过后最终项目路径为path.join(directoryPath, projectName)。2. 数据库创建与连接未使用 --db-url 时对应setupDatabasemedusa-project-creator.ts与 create-db.ts默认数据库名为medusa-${slugify(项目名)}例如项目名my-medusa-store对应medusa-my-medusa-store先以postgres/空密码连接默认主机与端口常量DEFAULT_HOST、DEFAULT_PORT来自 postgres-client.ts连接失败则询问用户名、密码和该用户默认数据库通过pg_catalog.pg_database查询目标库是否已存在doesDbExist已存在则让用户另起新库名执行CREATE DATABASE ${db}建库随后用新库重建连接最后用 format-connection-string.ts 拼出完整连接串user、password、host、db。3. 克隆 starter 模板clone-repo.ts 执行git clone repo-url -b main projectDir --depth 1未指定--repo-url时使用默认仓库项目模式与插件模式各有独立默认仓库插件为medusa-starter-plugin克隆完成后会删除.git与.github目录源码注释说明当 fs 删除失败时会回退到rm -rf系统命令兼容 Yarn v3 等场景使新项目成为独立代码库克隆支持AbortController中断信号CtrlC可安全终止。4. Next.js 商店前端可选若用户选择安装 Next.js starter或显式传入--with-nextjs-starterCLI 会保留克隆产物中的 storefront 目录默认则将其删除并在其中安装 Next.js starter在迁移完成后从api_key表中读取type publishable的密钥将其写入 storefront 的.env.local或.env.template中的NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY变量见 prepare-project.ts。项目准备阶段环境变量、依赖、迁移与管理员账号prepare-project.ts 是项目落地的核心它按顺序完成以下工作生成 .env 环境变量在克隆出的后端目录追加生成.env文件内容由源码中的常量拼装而成MEDUSA_ADMIN_ONBOARDING_TYPEdefault # 若含 storefront 则为 nextjs STORE_CORShttp://localhost:8000 ADMIN_CORShttp://localhost:5173,http://localhost:9000 AUTH_CORShttp://localhost:5173,http://localhost:9000,https://docs.medusajs.com REDIS_URLredis://localhost:6379 JWT_SECRETsupersecret COOKIE_SECRETsupersecret AUTH_MFA_ENCRYPTION_KEY随机生成的 32 字节十六进制串 DB_NAMEmedusa-my-medusa-store # 未跳过数据库时 DATABASE_URLpostgres://.../medusa-... # 数据库名部分被替换为 $DB_NAME 占位引用其中AUTH_MFA_ENCRYPTION_KEY由randomBytes(32).toString(hex)动态生成用于 MFA 相关加密。安装依赖并处理包管理器重写根目录与后端目录package.json的name与packageManager字段npm场景下安装命令为npm install --legacy-peer-deps安装完成后还会执行npm ci校验失败则回退重跑npm install包管理器选择逻辑见 package-manager.ts优先使用--use-npm/--use-yarn/--use-pnpm显式指定否则从npm_config_user_agent环境变量自动探测支持npm、yarn、pnpm/pnpx、nub探测失败回退 npm同时会删除其他包管理器遗留的锁文件如用 npm 时删除yarn.lock、pnpm-lock.yaml。运行迁移并创建管理员在--skip-db未开启且迁移未禁用时执行medusa db:migratenpm 下为npx medusa db:migrate并通过查询pg_tables中是否存在mikro_orm_migrations表来校验迁移真实生效执行medusa user -e adminmedusa-test.com --invite从标准输出中按正则/Invite token: (?token.)/提取邀请令牌该令牌会用于最后打开浏览器时的邀请页 URL见下文。启动服务与自动打开 AdminstartServices阶段medusa-project-creator.ts在后端目录启动 Medusa 应用若安装了 Next.js storefront则同时在 storefront 目录启动通过waitOn轮询http://localhost:9000/health服务就绪后用open打开浏览器有邀请令牌时打开http://localhost:9000/app/invite?tokentokenfirst_runtrue用于首次创建管理员否则打开http://localhost:9000/app以--skip-db或--no-browser运行时不启动服务直接以框式成功消息boxen收尾并提示重启命令如npm run dev与 storefront 目录位置。进阶用法与注意事项创建插件项目加--plugin参数ProjectCreatorFactory会返回 medusa-plugin-creator.ts 对应的处理器克隆插件 starter、更新package.json名称并安装依赖不涉及数据库。环境要求当前仓库要求Node.js 至少 v20常量MIN_SUPPORTED_NODE_VERSION 20见 node-version.ts不满足时会在创建前直接报错提示。CLI 包本身声明engines.node 14.16见 package.json实际运行以 v20 校验为准。隐私与遥测项目与插件两种创建路径分别上报CREATE_CLI_CMA/CREATE_CLI_CMP遥测事件经由medusajs/telemetry。调试技巧安装失败或迁移异常时加--verbose可看到底层 npm/yarn 命令的完整输出与堆栈。自动化/CI 场景可用my-project --skip-db --no-browser快速产出模板代码或在预置好数据库的 CI 中用--db-url url --no-browser完成迁移后即退出。小结从 README 中的两条选项到源码中完整的参数矩阵与阶段化执行流create-medusa-app的价值在于把克隆模板 建库 装依赖 迁移 建管理员 启动 开浏览器这一整套繁琐链路压缩为一条命令。理解其背后的 create-db.ts、prepare-project.ts 与 package-manager.ts 实现能让你在自定义 starter、定制 CORS 与调试初始化问题时游刃有余。若需进一步验证包管理器探测、中止控制等逻辑可参考仓库中的单元测试 src/utils/tests覆盖claude-code-plugin、create-abort-controller、package-manager三个模块。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考