Shopware 6中添加自定义Form CMS Block后预览不显示，如何排查？

Hey there! Let's work through why your custom Form CMS Block isn't appearing in the preview. I've debugged similar Shopware CMS issues before, so here are the key steps you might have missed (including the cache-related ones you suspected):

1. Clear All Caches (Non-Negotiable!) #

Shopware aggressively caches CMS configurations, templates, and admin assets. Even if your code is perfect, stale cache will hide your block. Run these commands in your project root:

bin/console cache:clear
bin/console cache:warmup
bin/console theme:compile

Don't stop there — also clear your browser's cache and do a hard refresh (Ctrl+Shift+R) on the admin page. Browser caching often blocks new admin components from loading.

2. Validate Your Block Definition for Forms #

When building a Form block, your BlockDefinition needs to properly reference form-specific slots and components. Double-check:

• Your block's category is set to a value like form or content so it shows up in the correct section of the CMS editor.
• Each slot uses a valid componentType (e.g., form-input, form-textarea, form-submit) that matches Shopware's built-in form elements or your custom form components.
• The block's name and label are correctly defined so you can find it in the editor's block list.

3. Register Block & Components in the Admin #

If you're building this via a plugin, ensure you've registered your block and any custom form components in your admin entry file (usually src/Resources/app/administration/src/main.js):

import './component/cms-block-my-form';
import './block/cms-block-my-form.definition';

// Register the block with the CMS service
Shopware.Service('cmsService').registerBlock('my-form', {
    // Your block config here
});

Without this registration, the admin editor won't recognize your block exists.

4. Check Your Frontend Template #

Make sure you've created the correct Twig template for your block, placed in the right directory (e.g., src/Resources/views/storefront/block/cms-block-my-form.html.twig). The template should render your form slots properly:

{% block block_my_form %}
    <div class="cms-block-my-form">
        {% for slot in block.slots %}
            {% sw_include "@Storefront/storefront/element/cms-element-" ~ slot.type ~ ".html.twig" %}
        {% endfor %}
    </div>
{% endblock %}

A missing or misnamed template will cause the block to not render in the preview.

5. Debug Browser Console Errors #

Open your browser's DevTools (F12) and check the Console tab for JavaScript errors. Common issues here include:

• Missing imports for your block components
• Syntax errors in your admin JavaScript
• Unregistered components referenced in your block definition
  These errors will directly prevent the block from loading in the editor preview.

6. Verify Preview Mode & Permissions #

Sometimes the preview might be stuck in a specific view (mobile/desktop) — try switching between modes to see if the block appears. Also, confirm your admin user has full permissions for CMS management (missing permissions can hide blocks from the editor).

After working through these steps, your Form CMS Block should show up in the preview. If it still doesn't, go back through each step and cross-reference with the official docs to catch any small configuration oversights.

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