vendure-cli

Vendure CLI

Vendure CLI（@vendure/cli，二进制文件 vendure）负责管理 Vendure 项目的整个生命周期。请使用它，而不要手动编写样板代码或猜测构建和迁移命令。

检测 Vendure 项目

请在 Vendure 服务包的根目录中，或在包含 packages/、apps/、libs/、services/ 或 modules/ 下 Vendure 包的 monorepo 根目录中运行 CLI 命令。

如果当前工作目录包含 @vendure/core，dev、build 和 start 会从该目录解析项目目录；否则会扫描这些 monorepo 包目录。add、migrate、schema 和依赖配置的 doctor 检查会从 process.cwd() 分析 TypeScript 项目，并要求该目录中存在 tsconfig*.json，因此不要假定它们能在任意嵌套子目录中运行。

运行 CLI

@vendure/cli 通常是项目依赖，因此请通过项目的包管理器运行它——不要假定可以使用 npx。根据项目根目录或工作区根目录中的锁文件检测包管理器，并使用相应的运行命令：

项目根目录中的锁文件	包管理器	运行 CLI 的方式
bun.lock / bun.lockb	bun	bunx vendure <command>
pnpm-lock.yaml	pnpm	pnpm exec vendure <command>
yarn.lock	yarn	yarn vendure <command>
package-lock.json	npm	npx vendure <command>
未找到	npm（回退）	npx vendure <command>

如果全局安装了 @vendure/cli，请直接调用 vendure <command>。 使用 vendure --help 列出所有命令。

commands/*.md 参考文件中的示例使用不带前缀的 vendure …——请为每个示例加上检测到的包管理器对应的运行命令。

注意：目前，安装包的 CLI 脚手架会在内部检测 yarn.lock、package-lock.json 和 pnpm-lock.yaml，然后回退到 npm。生成依赖项安装时不会使用 Bun。

命令

命令	用途…	参考
dev	以开发模式运行服务端、工作进程和仪表板	commands/dev.md
build	为生产环境编译项目	commands/build.md
start	运行已构建的项目	commands/start.md
add	脚手架生成插件、实体、服务、API 扩展等	commands/add.md
migrate	生成、运行或回退数据库迁移	commands/migrate.md
schema	根据 Admin/Shop API 生成 GraphQL schema 文件	commands/schema.md
doctor	诊断项目、依赖项、配置、schema 和数据库的健康状况	commands/doctor.md
codemod	运行自动化代码转换（例如 UI 迁移）	commands/codemod.md
plugins	列出、启用或禁用项目的 CLI 插件	commands/plugins.md

若要诊断故障项目，请使用 vendure-troubleshooting 技能（skills/vendure-troubleshooting/）。

已安装的 CLI 插件（声明了 vendure.cliPlugin 的包）可以添加命令，或替换 dev 等内置命令。建议在项目中使用 vendure --help 查看实际生效的命令集。请参阅开发者 CLI 指南中的“扩展 CLI”部分。

面向 Agent 的关键规则

1. 绝不要硬编码 npx。 根据项目的 lockfile 解析运行器——参见上文“运行 CLI”（bunx、pnpm exec、yarn、npx）。
2. 支持提示词的命令（add、migrate、schema、codemod、plugins）需要 Agent 提供明确的标志或参数。 使用明确的输入运行这些命令，以便它们采用非交互式路径；否则，进程会在非交互环境中拒绝仅提示式调用。从 Agent 调用 CLI 时，设置 VENDURE_CLI_NON_INTERACTIVE=true，这样仅提示式调用会快速失败并显示示例，而不是等待终端提示。每个命令的参考文件中都列出了具体的非交互式标志。对于 CLI 插件，请使用 vendure plugins --json / vendure plugins add <pkg> / vendure plugins remove <pkg>——没有一键批准标志。
3. dev、start 和 build --watch 是长时间运行的进程。 不要只是为了“检查”某些内容而运行它们。只有在用户提出要求时才运行，并优先在后台运行。
4. 仅安装生产依赖时可能不包含 @vendure/cli。 生成的应用会将 CLI 作为开发依赖，因此，在移除开发依赖后，请使用 node ./dist/... 启动已编译的服务器／工作进程入口，或显式将 CLI 设为生产依赖。
5. 构建命令前，请先阅读相关的 commands/*.md 文件。 各命令支持的目标和标志有所不同（例如，start 没有 dashboard 目标；--inspect 仅适用于 dev）。