Shopware 6.8 升级指南：核心变更与技术适配要点

概述

Shopware 6.8 作为一次重要的版本升级，带来了多项架构优化和功能改进。本文将从技术角度深入解析升级过程中的核心变更点，帮助开发者和系统管理员顺利完成版本迁移。

核心架构变更

1. EntityDefinition 构造函数移除

Shopware 6.8 移除了 EntityDefinition 基类的构造函数，所有子类需要相应调整：

<?php declare(strict_types=1);

namespace MyCustomEntity\Content\Entity;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;

class MyCustomEntity extends EntityDefinition
{
    public function __construct(private readonly array $meta = [])
    {
        // 移除 parent::__construct() 调用
        // ...
    }
}

2. 主订单交付和交易实体

引入 primaryOrderDelivery 和 primaryOrderTransaction 概念，优化订单数据结构：

// 替换前
$delivery = $order->getDeliveries()->first();
$transaction = $order->getTransactions()->last();

// 替换后  
$delivery = $order->getPrimaryOrderDelivery();
$transaction = $order->getPrimaryOrderTransaction();

数据访问层（DAL）优化

外键异常处理机制重构

移除了多个专用的异常处理器，统一由 DAL 处理外键约束：

移除的异常处理器	对应的异常类
OrderExceptionHandler	LanguageOfOrderDeleteException
NewsletterExceptionHandler	LanguageOfNewsletterDeleteException
LanguageExceptionHandler	LanguageForeignKeyDeleteException
SalesChannelExceptionHandler	SalesChannelException::salesChannelDomainInUse
ThemeExceptionHandler	ThemeException::themeMediaStillInUse

SEO 解析器数据获取方式变更

// 替换前 - 只获取第一个实体
$entity = $data->get($definition, $url->getForeignKey());

// 替换后 - 获取所有匹配实体
$entities = $data->getAll($definition, $url->getForeignKey());
foreach ($entities as $entity) {
    $seoUrls = $entity->getSeoUrls();
    $seoUrls->add($url);
}

主题系统重大重构

配置加载机制优化

graph TD
    A[主题配置请求] --> B{缓存检查}
    B -->|命中| C[返回缓存配置]
    B -->|未命中| D[数据库查询]
    D --> E[theme_runtime_config 表]
    E --> F[返回配置数据]
    F --> G[更新缓存]

主题标签系统迁移

废弃 theme.json 中的 label 和 helpText 属性，全面转向代码片段系统：

配置元素	代码片段键格式	示例
标签页	sw-theme.<technicalName>.<tabName>.label	sw-theme.swag-theme.colorTab.label
区块	sw-theme.<technicalName>.<tabName>.<blockName>.label	sw-theme.swag-theme.colorTab.primaryColorsBlock.label
字段标签	sw-theme.<technicalName>.<tabName>.<blockName>.<sectionName>.<fieldName>.label	sw-theme.swag-theme.colorTab.primaryColorsBlock.homeSection.sw-color.label
字段帮助文本	sw-theme.<technicalName>.<tabName>.<blockName>.<sectionName>.<fieldName>.helpText	sw-theme.swag-theme.colorTab.primaryColorsBlock.homeSection.sw-color.helpText

前端技术栈升级

DOM 访问助手废弃

// 替换前 - 使用 DomAccess 助手
const attribute = DomAccess.getAttribute(element, 'data-test');

// 替换后 - 使用原生 DOM API
const attribute = element.getAttribute('data-test');

Twig 函数变更

{# 替换前 #}
<a href="{{ category_url(item) }}" 
   {% if category_linknewtab(item) %}target="_blank"{% endif %}>

{# 替换后 #}
<a href="{{ item.seoUrl }}" 
   {% if item.shouldOpenInNewTab %}target="_blank"{% endif %}>

支付和配送系统调整

支付方法移除

DebitPayment 支付方式已被移除，系统会自动处理相关迁移：

• 未使用的支付方式：直接移除
• 已使用的支付方式：禁用处理

配送方法规则过滤

// 替换前
$filteredMethods = $shippingMethods->filterByActiveRules($context);

// 替换后
use Shopware\Core\Framework\Rule\RuleIdMatcher;
$matcher = new RuleIdMatcher();
$filteredMethods = $matcher->match($shippingMethods, $context->getRuleIds());

API 客户端配置变更

机密标志强制要求

// 替换前
$client = new ApiClient($clientId, $secret);

// 替换后  
$client = new ApiClient($clientId, $secret, true, 'client-name');

缓存系统优化

Store-API 路由缓存移除

移除了以下缓存配置选项：

# 已移除的配置项
shopware.cache.invalidation:
  product_listing_route: true
  product_detail_route: true
  payment_method_route: true
  shipping_method_route: true
  # ... 其他路由配置

文件系统配置变更

可见性配置位置调整

# 替换前
filesystems:
  my_filesystem:
    type: local
    config:
      visibility: public

# 替换后
filesystems:
  my_filesystem:
    type: local
    visibility: public

应用系统脚本升级

Twig 宏函数返回值处理

{# 替换前 - 传统 macro #}
{% macro getById(mediaId) %}
    {% set criteria = { 'ids': [ mediaId ] } %}
    {% return services.repository.search('media', criteria).first %}
{% endmacro %}

{# 替换后 - 使用 sw_macro_function #}
{% sw_macro_function getById(mediaId) %}
    {% set criteria = { 'ids': [ mediaId ] } %}
    {% return services.repository.search('media', criteria).first %}
{% end_sw_macro_function %}

升级检查清单

预升级准备

1. 备份策略

   • 数据库完整备份
   • 文件系统备份（特别是 var/ 和 public/ 目录）
   • 自定义代码和配置备份

2. 环境验证

   # 检查 PHP 版本兼容性
   php -v
   
   # 验证扩展依赖
   php -m | grep -E '(pdo|json|xml|zip|gd|intl)'
   

3. 依赖检查

   # 检查当前版本
   composer show shopware/core
   
   # 预览升级变更
   composer update --dry-run
   

升级执行流程

flowchart TD
    A[开始升级] --> B[禁用维护模式]
    B --> C[执行 composer update]
    C --> D[运行数据库迁移]
    D --> E[清理缓存]
    E --> F[重建管理界面]
    F --> G[验证功能]
    G --> H[启用维护模式]
    H --> I[升级完成]

常见问题处理

问题类型	解决方案	相关文档
主题配置错误	检查代码片段键格式	Theme Configuration Migration
API 客户端异常	更新机密标志参数	ApiClient Configuration
支付方式缺失	检查支付配置迁移	Payment Method Removal
缓存不一致	清理并重建缓存	Cache Invalidation

性能优化建议

数据库索引优化

-- 为主题运行时配置表添加索引
CREATE INDEX idx_theme_runtime_config_theme_id ON theme_runtime_config (theme_id);
CREATE INDEX idx_theme_runtime_config_sales_channel_id ON theme_runtime_config (sales_channel_id);

缓存策略调整

# config/packages/cache.yaml
framework:
    cache:
        pools:
            theme.config:
                adapter: cache.adapter.redis
                default_lifetime: 3600

监控与日志

升级后监控指标

# 监控系统性能
php bin/console system:monitor

# 检查迁移状态
php bin/console doctrine:migrations:status

# 查看系统日志
tail -f var/log/prod.log

总结

Shopware 6.8 升级涉及多个核心组件的架构优化，主要集中在数据访问层、主题系统、缓存机制和API客户端等方面。通过本文的详细指南，您可以系统性地完成升级过程，确保业务平稳过渡。

关键收获：

• 掌握 EntityDefinition 构造函数移除的适配方法
• 理解主订单交付和交易实体的新概念
• 熟悉主题配置向代码片段系统的迁移
• 了解缓存和文件系统配置的最佳实践

遵循本指南的步骤和建议，您将能够顺利完成 Shopware 6.8 升级，并充分利用新版本带来的性能改进和功能增强。