如何在Magento 2.4.3后台通过编程方式新增配置目录

Magento 2的后台系统配置菜单采用声明式XML注册机制，不需要编写独立运行的PHP脚本操作数据库，按照模块规范创建对应配置文件，即可在Stores > Settings > Configuration路径下新增自定义配置目录，所有配置会在模块升级时自动注册，兼容后续版本升级，具体实现步骤如下：

1. 准备自定义模块基础结构 #

不要修改Magento核心代码或第三方厂商模块代码，先创建本地自定义模块，基础目录结构如下：

app/code/[你的供应商名]/[你的模块名]/
├── etc/
│   ├── module.xml
│   └── acl.xml
├── registration.php
└── composer.json

各基础文件代码参考：

• 模块注册文件 registration.php

<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'YourVendor_YourModule', // 替换成你的模块名 格式为 供应商_模块名
    __DIR__
);

• 模块定义文件 etc/module.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="YourVendor_YourModule" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Config"/>
        </sequence>
    </module>
</config>

2. 定义配置访问权限 #

后台配置目录的访问权限靠ACL规则控制，创建etc/acl.xml文件定义对应权限资源：

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Magento_Backend::stores">
                    <resource id="Magento_Backend::stores_settings">
                        <resource id="Magento_Config::config">
                            <!-- 自定义配置目录的权限ID，后续配置文件需要对应 -->
                            <resource id="YourVendor_YourModule::custom_config" title="自定义配置板块" sortOrder="100"/>
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

3. 声明配置目录结构 #

创建etc/adminhtml/system.xml文件，这是定义配置目录的核心文件，你可以自定义顶级分组（Tab）和配置目录（Section）：

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <!-- 自定义左侧顶级大分组，不需要可以直接复用现有Tab -->
        <tab id="your_custom_tab" translate="label" sortOrder="200">
            <label>自定义业务配置</label>
        </tab>
        <!-- 这里的Section就是你要新增的独立配置目录 -->
        <section id="your_custom_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>你的自定义配置目录</label>
            <tab>your_custom_tab</tab>
            <!-- 绑定第二步定义的ACL权限 -->
            <resource>YourVendor_YourModule::custom_config</resource>
            <!-- 目录下可继续添加配置分组、具体配置项 -->
            <group id="general_setting" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>基础设置</label>
                <field id="enable_module" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>启用自定义功能</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
            </group>
        </section>
    </system>
</config>

如果不需要新建顶级分组，可以把<tab>节点的值替换为Magento自带的Tab ID，比如general对应通用配置分组、catalog对应商品目录分组，你的配置目录就会显示在现有分组下。

4. 执行命令生效 #

所有文件创建完成后，在Magento根目录执行以下命令，注册模块并清理缓存：

bin/magento module:enable YourVendor_YourModule
bin/magento setup:upgrade
bin/magento cache:clean config
bin/magento cache:flush adminhtml

执行完成后重新登录后台，即可在Stores > Settings > Configuration下看到新增的配置目录。

注意事项 #

• 不要编写独立PHP脚本直接修改数据库新增配置项，Magento的配置菜单是动态渲染的，直接改库不会生成菜单项，还会导致权限异常、配置无法保存的问题
• system.xml必须放在etc/adminhtml目录下，放在全局etc目录会导致前台访问报错
• ACL资源ID必须和system.xml中绑定的ID完全一致，否则会出现访问配置页提示权限不足的问题
• showInDefault/showInWebsite/showInStore三个属性分别控制配置项是否在全局、站点、店铺层级显示，不需要对应层级显示设为0即可
• sortOrder数值越小，对应分组、目录、配置项的排序越靠前

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