Shopware 6应用脚本：自定义实体缓存失效不生效问题排查

背景与已实现内容 #

已基于Shopware 6的custom entities功能创建专属数据结构，实现前端CRUD操作：

1. 通过product-page-loaded钩子的Twig宏加载数据，脚本路径：custom/apps/MyApp/Resources/scripts/include/my-script.twig

{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% macro load(salesChannelId, header) %}
    {% set criteria = {
        'filter': [
            { 'type': 'equals', 'field': 'salesChannelId', 'value': salesChannelId },
        ]
    } %}

    {% set myEntity = services.repository.search('ce_atl_my_entity', criteria) %}

    {% if myEntity.first is not empty %}
        {% do header.addExtension('atlMyExtension', myEntity.first) %}
    {% endif %}
{% endmacro %}

2. 前端更新端点脚本，路径：custom/apps/MyApp/Resources/scripts/storefront-my-script/my-script.twig

{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% do services.writer.upsert('ce_atl_my_entity', [
    {
        'id': hook.request['id'],
        'rating': hook.request['rating'],
        'url': hook.request['url'],
        'userRatingsTotal': hook.request['user_ratings_total'],
        'salesChannelId': hook.request['sales_channel_id']
    }
]) %}

{% set response = services.response.json({}) %}
{% do response.cache.tag('my-entity-' ~ hook.request['id']) %}

{% do hook.setResponse(response) %}

问题 #

数据更新后产品页面仍加载陈旧缓存数据，编写的缓存失效脚本未生效，脚本路径：custom/apps/MyApp/Resources/scripts/cache-invalidation/my-invalidation-script.twig

{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set ids = hook.event.getIds('ce_atl_my_entity') %}

{% if ids.empty %}
    {% return %}
{% endif %}

{% set tags = [] %}
{% for id in ids %}
    {% set tags = tags|merge(['my-entity-' ~ id]) %}
{% endfor %}

{% do services.cache.invalidate(tags) %}

请问遗漏了什么关键配置或步骤？

排查方向与解决方案 #

1. 确认脚本钩子绑定配置 #

缓存失效脚本需要绑定到entity.written事件（实体写入后的触发事件），必须在应用的manifest.xml中正确注册：

<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/Framework/App/Manifest/Schema/manifest-1.0.xsd">
    <!-- 其他配置 -->
    <scripts>
        <script name="my-entity-cache-invalidation" hook="entity.written">
            <path>Resources/scripts/cache-invalidation/my-invalidation-script.twig</path>
        </script>
    </scripts>
</manifest>

未正确绑定钩子是脚本不执行最常见的原因。

2. 验证实体名称与事件ID匹配 #

检查脚本中使用的实体名称ce_atl_my_entity是否与自定义实体的实际技术名称完全一致（注意大小写、前缀），否则hook.event.getIds()无法获取到正确的实体ID集合。

3. 检查缓存标签一致性 #

确认更新脚本中设置的标签my-entity-{{ hook.request['id'] }}与失效脚本生成的my-entity-{{ id }}完全匹配，比如ID的格式（UUID是否带破折号、大小写）是否统一。

4. 扩展缓存失效范围（关联产品缓存） #

产品页面的缓存通常关联产品自身的缓存标签，仅失效自定义实体标签可能不足以刷新产品页面。若自定义实体关联了产品ID，需额外失效对应产品的缓存：

{# 修改后的缓存失效脚本 #}
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set ids = hook.event.getIds('ce_atl_my_entity') %}

{% if ids.empty %}
    {% return %}
{% endif %}

{% set tags = [] %}
{% set productTags = [] %}

{% for id in ids %}
    {% set tags = tags|merge(['my-entity-' ~ id]) %}
    {# 查询自定义实体，获取关联的productId #}
    {% set entity = services.repository.search('ce_atl_my_entity', {
        'filter': [{'type': 'equals', 'field': 'id', 'value': id}]
    }).first %}
    {% if entity.productId is not empty %}
        {% set productTags = productTags|merge(['product-' ~ entity.productId]) %}
    {% endif %}
{% endfor %}

{# 同时失效自定义实体标签和关联产品标签 #}
{% do services.cache.invalidate(tags|merge(productTags)) %}

5. 查看日志排查执行错误 #

检查Shopware日志文件（var/log/prod.log或var/log/dev.log），确认缓存失效脚本是否有执行报错，比如权限不足、API调用失败等问题。

内容的提问来源于stack exchange，提问作者lucamario