shopware-cli

Shopware CLI

在受支持的 Shopware 项目、扩展和账户工作流中，优先使用 Shopware CLI。

为 shopware/shopware-cli 做贡献时，请从用户的角度思考：CLI 能做什么、用户应选择哪个命令、命令应如何运行，以及安全边界应设在哪里。实现约定、架构、测试和 Go 特定的贡献者指南，请参阅仓库中的 AGENTS.md。

从当前 CLI 开始

以当前 CLI 二进制为准，确认可用的命令和标志。

command -v shopware-cli
shopware-cli --version
shopware-cli --help
shopware-cli project --help
shopware-cli extension --help
shopware-cli account --help

对于特定命令：

shopware-cli <group> <command> --help

在 shopware/shopware-cli 工作区中处理尚未发布的功能时，请检查或运行当前检出的代码，不要假设已安装的版本行为相同。如果该工作区有可用的构建二进制，请始终使用同一个二进制进行 --version、--help、架构检查、验证以及其他待测试的操作。不要悄悄混用工作区中的二进制和 PATH 中较旧的 shopware-cli。

不要凭记忆杜撰命令、标志、配置字段或行为。

命令类别

CLI 主要面向用户提供三个类别：

• project：创建、配置、开发、检查、构建、维护和升级 Shopware 项目。
• extension：构建、验证、格式化、打包和维护 Shopware 扩展。
• account：经过身份验证的 Shopware Account 和扩展生产者工作流。

这只是概览，并非完整的命令目录。请使用 --help 查看当前提供的命令。

插件脚手架

extension create 会生成插件的基础文件（composer.json、.gitignore、最简插件类和 PHPUnit 引导文件）。创建时会包含 PHPUnit；没有 extension add tests 命令。引导文件使用 Shopware TestBootstrapper（addActivePlugins、setForceInstallPlugins(true)）。

extension add <generator> 会在现有插件中添加一个示例功能。生成器是单独的命令，不是 plugin:create 问答流程，也不是 Core make:plugin:* 命令的封装。请在 Shopware 项目中的插件目录下运行，且版本须为 6.7.13.0 或更高（声明式 custom-fields.xml）。不支持的版本会在写入任何文件之前报错。

可用的生成器：admin-module、command、custom-fieldset、entity、event-subscriber、javascript-plugin、plugin-config、scheduled-task、store-api-route、storefront-controller。

与 Shopware Core 脚手架的有意差异：

• PHP 使用 src/Resources/config/services.php 和 routes.php，而不是 XML。
• Admin 代码片段使用 en.json / de.json，而不是 en-GB / de-DE。
• 会向现有的 main.js 追加内容，而不会覆盖它。
• 绝不会覆盖现有插件文件；重复的 service/route 区块会跳过。
• 交互式和非交互式 extension add 共用同一代码路径（仅使用标志/参数；没有问答流程）。

优先使用 Shopware CLI 抽象

如果 Shopware CLI 提供了可用于某项任务的命令，请优先使用它，而不是手动通过 Composer、bin/console、Docker、npm、PHP 或直接修改文件系统来重建工作流。

CLI 可能已经了解：

• 当前 Shopware 项目；
• 项目和扩展配置；
• 所选环境；
• 使用 Docker 还是本地执行；
• 扩展的结构和类型；
• 受支持的构建、验证、维护和升级工作流。

仅在以下情况下使用较底层的工具：

1. Shopware CLI 未提供所需操作；或
2. 排查问题需要检查底层操作。

如果任务涉及 Docker 支持的项目，或需要判断命令应在哪里执行，请在可用时使用 shopware-cli-docker 技能。

了解命令风险

执行命令之前，请先了解它可能造成的更改。

通常风险较低

在调查任务时，帮助信息、版本检查、状态、诊断、架构检查、验证和读取日志等以检查为主的操作通常是合适的。

如果命令的行为不明确，仍应检查命令帮助信息。

本地文件更改

创建、生成、格式化、修复、升级、打包、安装依赖项或重写配置的命令可能会更改文件。

运行这些命令之前：

• 检查 --help；
• 了解可能会更改哪些文件；
• 仅当命令确实支持预览或试运行时，才使用该功能；
• 保留无关的用户更改；
• 检查生成的差异。

不要假设每个命令都支持 --dry-run。

当用户只要求检查，或明确表示不要修改文件时，不要仅为了探测验证行为而临时重写项目文件。优先检查帮助信息、架构或源代码，或使用单独的临时测试样例。

数据库和应用状态更改

将可能更改数据库、Shopware 应用状态、已安装扩展、缓存、索引、迁移或配置的命令视为高风险。

shopware-cli project console（以及 swx 别名）是通往 Symfony Console 和项目 composer.json 中自定义脚本的执行桥梁。其安全性取决于传入的命令或脚本。

运行不熟悉或会更改状态的 Symfony 命令之前：

shopware-cli project console <command> --help

从项目 composer.json 或通过 shopware-cli project console list 查找 Composer 脚本。不要将 --help 传给 Composer 脚本来检查脚本；该参数会转发给脚本，仍可能导致脚本运行。

继续操作之前，先确认会影响哪个环境。

远程更改

将会进行身份验证、登出、上传、推送、发布或以其他方式修改 Shopware Account 远程状态的账户操作视为外部副作用。

不要仅仅因为凭据可用，就推断用户已授权或有此意图。

验证工作流

使用 shopware-cli project validate 或 shopware-cli extension validate 对项目或扩展运行验证检查。

务必检查当前标志和可用检查项：

shopware-cli project validate --help
shopware-cli extension validate --help

项目验证

shopware-cli project validate [flags]

根据当前 CLI 实现的检查项和配置的工具验证 Shopware 项目。它会先将项目复制到临时目录并安装工具集，因此首次运行可能较慢；--no-copy 会在原位置验证并跳过复制。

常用标志包括：

• --only <tools> — 仅运行指定的检查器（以逗号分隔）。
• --exclude <tools> — 跳过指定的工具（以逗号分隔）。
• --format <format> — 选择当前 CLI 支持的输出格式（--reporter 是已弃用的别名）。
• --local-only — 将扩展发现范围限制为 custom/* 中的插件（适用于项目工具集）；不会添加针对每个扩展的元数据验证。
• --no-copy — 验证前不将项目文件复制到临时目录。
• --verbose — 显示调试输出。

请以当前的 --help 为准，不要将此列表视为完整列表。

project validate 不等同于 extension validate。 它会对发现的扩展源目录运行项目代码质量工具集（PHPStan、ESLint、Twig linter 等）；它不会运行针对每个扩展的清单／元数据验证，因此即使验证通过（问题数为 0），也不代表自定义扩展有效。要验证自定义扩展的结构和元数据，请直接对其运行 shopware-cli extension validate <path>（例如，对每个 custom/plugins/<Name> 运行）。

扩展验证

shopware-cli extension validate [path] [flags]

扩展路径为必填项；使用 . 表示当前扩展。

常规扩展验证会运行当前 CLI 内置的检查。商店合规性检查会验证 Administration 和 Storefront 源文件是否有匹配的编译资源。验证还会报告与商店合规性无关的元数据和代码质量问题。

常用标志包括：

• --only <tools> — 仅运行指定的检查器（以逗号分隔）。
• --exclude <tools> — 从所选集合中移除指定的检查器。
• 默认运行所有检查器，包括 PHPStan、ESLint 和 Stylelint。--full 已弃用且不起作用。若要快速验证，请使用 --only builtin（仍接受 sw-cli 作为旧版别名，并会发出弃用警告）。
• --check-against <mode> — highest（默认）或 lowest：要对照哪个受支持的 Shopware 版本进行检查。
• --format <format> — 选择当前 CLI 支持的输出格式（--reporter 是已弃用的别名）。
• --no-copy — 不将扩展文件复制到临时目录。
• --verbose — 显示调试输出。

对于商店分发工作流，如果有 shopware-cli-extension-store 技能，请使用它。

在 .shopware-extension.yml 中设置 validation.store_compliance: true 可启用商店合规性检查。设置 SHOPWARE_CLI_STORE_COMPLIANCE=1 也可启用此检查。该检查会检查 Administration 和 Storefront 源文件与编译资源是否成对匹配。

每个命令只会选择支持其操作的工具。例如，extension validate --only prettier 会报错，因为 Prettier 用于格式化，而不执行检查；错误信息会列出可用的检查器。扩展命令摘要中的 invoked 或 skipped 表示选择和调用情况，不代表文件是否适用、是否发现问题或是否进行了修复。

新结果优先于已保存的报告

文件修复或更改后，已保存的输出（例如 validation.json、JUnit XML 或 Markdown 报告）可能会过时。

诊断验证失败之前，请针对当前工作区重新运行验证。如果已保存的报告与当前文件或新运行的结果不一致，请将已保存的报告视为过时。

CI 和报告器

在自动化环境中，如有需要，请优先使用机器可读的输出：

shopware-cli project validate --format json > validation-results.json
shopware-cli project validate --format junit > validation-results.xml
shopware-cli extension validate . --format github
shopware-cli extension validate . --format gitlab

报告器会格式化输出，但不会自行向拉取请求或合并请求发布评论或注释；CI 配置必须以适当方式处理输出。

请使用进程退出代码作为验证结果。报告器可以更改格式，但验证错误仍会导致命令失败。

特定领域的路由

当验证在特定领域失败时，如果有相关技能，请将用户引导至这些技能：

• PHP 测试失败 → php-testing 技能。
• JavaScript/Admin 失败 → admin-testing 技能。
• 验收测试失败 → acceptance-testing 技能。
• 无障碍问题 → accessibility-testing 技能。
• 架构或 LSP 问题 → architecture-review 技能。

验证问题排查

当 validate 产生意外结果时：

1. 确认使用的 CLI 二进制文件及其版本。

   • 使用 command -v shopware-cli 和 shopware-cli --version。
   • 测试某个检出版本时，请始终使用该版本构建的二进制文件。

2. 确认工作目录和项目配置。

   • 确保 .shopware-project.yml 或 .shopware-extension.yml 存在且配置正确。
   • 必要时检查 --verbose 输出。

3. 重新生成验证输出。

   • 不要根据旧的已保存报告来诊断当前文件。

4. 检查已安装和锁定的工具版本。

   • 完整验证可能依赖 PHPStan、ESLint 和 Stylelint 等外部工具。
   • 确认相关依赖和配置。

5. 了解工具状态。

   • skipped 表示未选择或已排除某个工具；状态说明会给出原因。
   • invoked 表示已调用该工具，并不代表它分析了文件或执行成功。请根据发现项和退出代码判断验证结果。

6. 避免临时绕过方案。

   • 尚未弄清 CLI 行为异常的原因前，不要使用手动的底层命令绕过验证。

7. 检查环境和运行时前置条件。

   • 某些检查可能需要 Docker、PHP、npm 依赖或其他工具。

创建新项目

使用 shopware-cli project create 搭建新的 Shopware 项目。

shopware-cli project create --help
shopware-cli project create [name] [version] [flags]

请务必先查看当前的 --help；以下标志列表仅供参考，并非权威依据。

询问用户；不要猜测

使用此技能创建项目时，通常会以非交互方式运行 create（-n），因此 CLI 自带的提示不会出现，而是静默应用默认值——其中有些默认值与交互提示中的不同（非交互模式下默认启用 Elasticsearch，提示中则默认关闭）。不要盲目沿用这些默认值。先向用户确认选项，再将其作为显式标志传入。说明每个选项对用户有什么作用，而不是会避免哪些错误或内部代码——例如，将跳过 Elasticsearch 的理由说成“设置更简单，只有大型目录或高级搜索才需要”，绝不要提 500 或索引错误。请逐项确认：

• 名称（[name]）——项目目录。询问用户；不要默认为当前目录（该目录必须为空或不存在）。
• 版本（--version）——例如 6.6.0.0 或 latest。
• Docker（--docker）——**推荐。**在 Docker 中运行本地环境，而不是依赖本地 PHP/工具链。
• 本地域名（--local-domain）——推荐（需要 --docker）。通过共享代理使用稳定的 <name>.shopware.local 域名提供商店，而不是使用端口。在一台机器上首次使用时，需要一次性运行 shopware-cli project proxy setup（sudo：DNS + HTTPS 信任）——非交互式 create 不会运行此命令，因此需要单独安排。
• PHP 版本（--php-version）——8.2–8.5；通常交由 CLI 决定。只有用户需要指定版本时才询问；该版本必须满足所选 Shopware 版本的 PHP 要求。
• Elasticsearch/OpenSearch（--with-elasticsearch）——除非用户需要（大型目录或高级搜索），否则建议保持关闭。非交互模式下默认启用，因此要禁用它，请传入 --with-elasticsearch=false（在 -n 下省略此标志会使其保持启用；单独的 --without-elasticsearch 标志已弃用）。
• AMQP（--with-amqp）——询问用户；仅在他们需要队列/消息传递支持时启用。
• 部署（--deployment）——none|container|deployer|platformsh|shopware-paas（默认值为 none）。
• CI/CD（--ci）——none|github|gitlab（默认值为 none）。
• Git（--git）——初始化代码仓库。
• 审计（--no-audit）——不要预先设置；只有安全公告阻止安装且用户接受风险时才使用。

使用 --docker 时，create 会运行数分钟：它会拉取开发镜像，并在容器内运行 composer install、自动加载生成和安装后脚本。这是预期行为，并非卡住。请向用户展示进度——持续输出命令结果，或在后台运行，并根据日志报告当前阶段——不要静默等待。

create 会搭建项目；它不会安装商店。它会写入项目文件、运行 composer install，并创建 .shopware-project.yml（以及用户要求时创建 compose 文件 / Git）。数据库尚未设置。之后若要安装：

• shopware-cli project dev install——非交互方式：启动环境、运行安装，并将管理员凭据保存到项目配置中（默认值为 admin / shopware、en-GB、EUR；可用 --admin-username/--admin-password/--locale/--currency 覆盖）。此操作幂等——如果商店已安装，则会跳过。
• shopware-cli project dev——交互式 TUI 仪表板，可供用户手动操作。

其他注意事项

• 安全公告会阻止非交互式安装，除非设置了 --no-audit；交互模式下则会显示提示。
• 目标文件夹必须为空；主机名冲突（<name>.shopware.local 已被占用）会在运行 proxy/dev 时显现，而不是在运行 create 时显现。

决策前检查项目

相关文件可能包括：

• .config/shopware-project.yml / .shopware-project.yaml / .shopware-project.yml（商店 URL 和 Admin API 凭据位于 environments 下；空的 -e 指向 environments.local）
• .config/shopware-extension.yml / .shopware-extension.yml / .shopware-extension.yaml
• composer.json
• composer.lock
• manifest.xml

不要仅凭用户的措辞推断项目类型、扩展类型、目标环境或 Shopware 版本。

只会按上述顺序使用找到的第一个 yml / yaml 文件；对于新项目，优先使用第一个文件。

优先采用 CLI 提供的配置架构，而不是依赖记忆中的配置字段。

非交互式与 Agent 执行

对于无人值守或由 Agent 驱动的执行，优先使用：

shopware-cli --no-interaction <command>

或：

shopware-cli -n <command>

如果缺少必需的值，请查看 --help 并明确提供这些值，不要猜测提示问题的答案。

如果命令明确支持机器可读输出，请优先使用。

凭据与敏感数据

切勿在响应、日志、示例或已提交文件中暴露访问令牌、密码、客户端密钥、数据库凭据或其他秘密值。

优先使用 Shopware CLI 支持的身份验证和配置机制，而不是直接操作凭据存储。

数据库转储和其他导出文件可能包含敏感的客户或商店数据。请谨慎创建、存储和共享这些文件。

project dump --anonymize 还会合并每个已安装扩展的 .config/shopware-extension.yml 中的 anonymize 部分：tables 是列重写规则（结构与项目的 dump.rewrite 相同），而 system_config 会省略行，或将其替换为自定义值或 faker 值。如果两者设置了相同的列，则以项目的 dump.rewrite 为准。如果无法读取扩展配置，转储会停止：请修复或报告该配置，而不是移除 --anonymize。

如果可用，可使用 shopware-cli-extension-anonymize 技能，根据扩展的实体和 config.xml 填充该部分。

生成的文件

编辑前，请区分源文件和生成的文件。

如果 Shopware CLI 负责生成某个产物，请优先通过相应的 CLI 命令重新生成，而不是手动编辑生成的输出。

重新生成任何可能覆盖现有文件的内容之前，请先查看命令帮助。

故障排除

Shopware CLI 命令失败时：

1. 记录确切的命令和错误。
2. 检查确切的二进制文件路径和 --version。
3. 查看该命令的 --help。
4. 确认工作目录以及相关的项目或扩展配置。
5. 必要时使用 --verbose 重试。
6. 检查是否选择了正确且可用的项目环境。
7. 只有在确认 Shopware CLI 尝试执行的操作后，才检查底层的 Composer、Symfony、Docker、npm、PHP 或 API 操作。

在弄清楚绕过了哪些 CLI 行为或配置之前，不要使用更底层的工具绕过失败的 Shopware CLI 命令。

信息优先级

行为不明确时，请按以下顺序参考：

1. 当前 CLI 二进制文件和最新运行时输出；
2. 项目配置和 CLI 提供的架构；
3. 需要了解实现细节时，查看当前的 shopware/shopware-cli 源代码和测试；
4. Shopware CLI 官方文档。

优先采用与当前版本相符的事实，而不是凭记忆推断 Shopware 行为或依赖过时的生成报告。