Shopware 6插件自定义Admin模块未显示在菜单的问题排查求助

我正在开发Shopware 6插件，尝试添加自定义Admin模块，先后进行两次尝试后模块仍未在后台菜单显示，已执行重建后台、清除Shopware缓存、浏览器缓存，使用隐私窗口访问等操作。

第一次尝试代码 #

模块文件 src/Resources/app/administration/src/module/swag-bundle/index.js #

import './page/swag-bundle-list';
import './page/swag-bundle-detail';
import './page/swag-bundle-create';
import deDE from './snippet/de-DE.json';
import enGB from './snippet/en-GB.json';

const { Module } = Shopware;

Module.register('swag-bundle', {
    type: 'plugin',
    name: 'Bundle',
    title: 'swag-bundle.general.mainMenuItemGeneral',
    description: 'sw-property.general.descriptionTextModule',
    color: '#FFD700',
    icon: 'default-shopping-paper-bag-product',

    snippets: {
        'de-DE': deDE,
        'en-GB': enGB
    },

    routes: {
        list: {
            component: 'swag-bundle-list',
            path: 'list'
        },
        detail: {
            component: 'swag-bundle-detail',
            path: 'detail/:id',
            meta: {
                parentPath: 'swag.bundle.list'
            }
        },
        create: {
            component: 'swag-bundle-create',
            path: 'create',
            meta: {
                parentPath: 'swag.bundle.list'
            }
        }
    },

    navigation: [{
        id: 'swag-bundle-example',
        path: 'swag.bundle.list',
        parent: 'sw-extension',
        label: 'swag-bundle.general.mainMenuItemGeneral',
        icon: 'default-shopping-paper-bag-product',
        position: 100
    }]
});

入口文件 src/Resources/app/administration/src/main.js #

import './module/swag-bundle';

第二次尝试代码 #

入口文件 custom/plugins/my-plugin/src/Resources/app/administration/src/main.js #

import './module/blog-post';

模块文件 custom/plugins/my-plugin/src/Resources/app/administration/src/module/blog-post/index.js #

Module.register('blog-post', {
    type: 'plugin',
    title: 'blog-post.general.title',
    description: 'blog-post.general.descriptionTextModule',
    color: '#ff68b4',
    icon: 'regular-content',
    snippets: {
        'en-GB': enGB,
        'de-DE': deDE
    },

    routes: {
        create: {
            component: 'blog-post-create',
            path: 'create',
            meta: {
                privilege: 'blog_post.creator',
                parentPath: 'blog.post.index',
            },
        }
    },

    navigation: [{
        id: 'blog.post.index',
        label: 'blog-post.general.mainMenuItemList',
        color: '#ff68b4',
        path: 'blog.post.index',
        icon: 'regular-content',
        position: 10,
        parent: 'sw-content'
    }],
});

组件文件 custom/plugins/my-plugin/src/Resources/app/administration/src/module/blog-post/page/blog-post-create/index.js #

import template from './blog-post-create.html.twig';

const { Component } = Shopware;

Component.extend('blog-post-create', {
    template
    
});

模板文件 custom/plugins/my-plugin/src/Resources/app/administration/src/module/blog-post/page/blog-post-create/blog-post-create.html.twig #

{% block blog_post_create %}
    <h1> Hola </h1>
{% endblock %}

可能的原因与解决办法 #

• 路由缺失对应入口页面：第二次尝试中，导航项的path是blog.post.index，但模块routes里仅定义了create路由，无index路由。Shopware无法匹配路径，导致菜单不渲染。解决：添加index路由并绑定对应组件，或修改导航path为blog.post.create。
• 片段（snippets）未正确导入：第二次尝试的模块文件未导入enGB、deDE对应的JSON文件，会触发JS报错导致模块注册失败。解决：在模块文件顶部添加片段导入代码，并确保JSON文件格式无误。
• 权限配置问题：第二次尝试的create路由设置了privilege: 'blog_post.creator'，若当前用户无该权限或插件未注册权限，菜单会被隐藏。解决：暂时移除privilege测试显示，若需权限则在src/Resources/config/packages/acl.xml中定义权限并分配给用户角色。
• 插件未正确激活或编译：确保插件已在后台启用，执行对应环境的编译命令：开发环境用./bin/build-administration.sh或插件目录下npm run dev，生产环境加--production参数，编译后执行./bin/console cache:clear。
• 导航父节点ID错误：检查导航parent值是否为Shopware默认节点（如sw-extension、sw-content），拼写错误会导致菜单找不到父节点。
• 组件未正确注册：第一次尝试导入的swag-bundle-list等组件需确保文件存在，且按Shopware规范注册Component。

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