Magento二次开发教程如何快速上手？-建站教程-锦华智联科技

Magento 2 二次开发终极指南

Magento 2 是一个功能强大但结构复杂的平台，二次开发不仅仅是修改代码，更是要理解其背后的设计哲学（如依赖注入、插件化、模块化等）。

（图片来源网络，侵删）

第一部分：基础准备与环境搭建

在开始编码之前，必须准备好你的“工欲”。

理解核心概念

这是 Magento 2 开发的基石，不理解这些,代码会写得非常痛苦。

模块化: Magento 2 的所有功能都封装在模块中，无论是核心功能还是你自己的功能，都是一个模块,开发就是创建和修改模块。
依赖注入: Magento 2 使用 PHP-DI 来管理对象，你不需要手动 new 一个对象，而是通过构造函数或方法参数来声明你需要什么，Magento 2 会自动“注入”给你,这使得代码更易于测试和维护。
插件: 这是 Magento 2 最核心、最推荐的扩展方式，你可以拦截一个公共方法（如 save(), getPrice()）的执行，在其之前、之后或替换它来添加新功能，而无需修改原类的代码。
覆盖/重写: 不推荐使用，它会完全替换掉原始类，可能导致与其他模块的冲突，并且在 Magento 升级时容易出问题,仅在极少数万不得已的情况下使用。
配置: Magento 2 的行为（如路由、布局、块等）几乎完全由 XML 配置文件驱动，你需要学会如何通过 di.xml, routes.xml, layout.xml 等文件来定义你的模块。
缓存: Magento 2 性能强大的一大原因就是其多层缓存机制，你的任何配置或代码变更，都需要清除缓存才能生效。bin/magento cache:clean 是你最常用的命令之一。

开发环境

本地服务器: 推荐使用 Docker + Magento DDEV 或 Magerun 来快速搭建一个与生产环境隔离的本地开发环境。
代码编辑器: Visual Studio Code 是首选，配合官方的 Magento 2 插件提供语法高亮、代码提示、模块生成等功能。
版本控制: Git 是必须的，强烈建议使用 Magento 2 的官方 .gitignore 文件来忽略不需要提交的文件（如 var/, pub/, generated/）。

目录结构

你需要熟悉 Magento 2 的主要目录：

app/: 最重要的目录，所有自定义模块的代码都在这里。
- code/: 你的模块代码所在地。
- design/: 前端主题和模板文件。
- etc/: 全局配置文件。
pub/: 公共访问目录,只有这里的文件才能被外部访问。
vendor/: Composer 依赖库，由 Magento 2 核心和第三方模块组成。不要直接修改这里的代码！
bin/: 包含命令行工具 magento。

第二部分：实战开发流程

我们将以一个最经典的例子——“创建一个简单的 'Hello World' 页面”来走一遍完整的开发流程。

步骤 1：创建一个模块

所有功能都必须在模块中,我们使用命令行工具来创建模块骨架。

# 进入你的 Magento 项目根目录
cd /path/to/your/magento2
# 创建模块
# VendorName: 你的公司或个人标识，通常是小写
# ModuleName: 你的模块名，通常是大写开头
bin/magento setup:module:create --vendor="MyVendor" --module="HelloWorld"

执行后，app/code/MyVendor/HelloWorld 目录会被创建,并包含基本结构。

步骤 2：配置路由

要让 Magento 知道如何访问你的页面,你需要定义一个路由。

创建路由配置文件: app/code/MyVendor/HelloWorld/etc/frontend/routes.xml (如果是后端管理页面，则创建 adminhtml/routes.xml)

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="standard">
        <route id="helloworld" frontName="helloworld">
            <module name="MyVendor_HelloWorld"/>
        </route>
    </router>
</config>

frontName: 这是 URL 的一部分，www.yourstore.com/helloworld。
module name: 必须与你的模块名 MyVendor_HelloWorld 完全一致。

清除缓存:
```
bin/magento cache:clean
```

步骤 3：创建控制器

控制器是处理 URL 请求并返回响应的 PHP 类。

创建控制器目录和文件: app/code/MyVendor/HelloWorld/view/frontend/templates/page/hello.phtml (我们先把模板文件建好)
```
<h1>Hello World from Magento 2!</h1>
<p>This is my first custom page.</p>
```

创建控制器类: app/code/MyVendor/HelloWorld/Controller/Index/Index.php

<?php
namespace MyVendor\HelloWorld\Controller\Index;
use Magento\Framework\Controller\ResultFactory;
class Index extends \Magento\Framework\App\Action\Action
{
    public function execute()
    {
        // 1. 获取响应对象
        $resultPage = $this->resultFactory->create(ResultFactory::PAGE_LAYOUT);
        // 2. (可选) 设置页面标题
        $resultPage->getConfig()->getTitle()->set("My Custom Page Title");
        return $resultPage;
    }
}

namespace: 必须与模块路径对应。
Controller\Index: Index 是文件夹名，代表一个路由组。Index.php 是控制器名。
execute(): 这是每个控制器的默认执行方法。
ResultFactory::PAGE_LAYOUT: 告诉 Magento 我们想返回一个完整的页面布局。

步骤 4：配置布局

布局文件负责将你的内容块放到页面的正确位置。

创建布局文件: app/code/MyVendor/HelloWorld/view/frontend/layout/helloworld_index_index.xml

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <!-- (可选) 添加自定义 CSS 或 JS -->
        <title>Hello World Page</title>
    </head>
    <body>
        <referenceContainer name="content">
            <!-- 引用你的块 -->
            <block class="MyVendor\HelloWorld\Block\Hello" name="hello.block" template="MyVendor_HelloWorld::page/hello.phtml" />
        </referenceContainer>
    </body>
</page>

helloworld_index_index.xml: 布局文件名由 frontName_controllerName_actionName 组成。
<page>: 根节点,定义页面布局。
<referenceContainer name="content">: 引用页面主内容区。
<block>: 定义一个块。
- class: 块的 PHP 类（我们下一步创建）。
- name: 块的唯一标识符。
- template: 指向模板文件的路径，格式为 Vendor_Module::/path/to/template.phtml。

步骤 5：创建块

块是 PHP 类,负责准备数据并将其传递给模板。

创建块类: app/code/MyVendor/HelloWorld/Block/Hello.php

<?php
namespace MyVendor\HelloWorld\Block;
class Hello extends \Magento\Framework\View\Element\Template
{
    // 你可以在这里添加方法来准备数据
    public function getWelcomeMessage()
    {
        return "Welcome to my awesome module!";
    }
}

这个类非常简单，它继承自 Template，这个父类已经帮我们处理了 template 属性和将数据传递给模板的逻辑。

步骤 6：更新模板以使用块的数据

修改你的模板文件,让它调用块的方法。

app/code/MyVendor/HelloWorld/view/frontend/templates/page/hello.phtml

<h1><?= $block->escapeHtml($block->getWelcomeMessage()) ?></h1>
<p>This is my first custom page.</p>

$block: 在模板中,这个变量代表你定义的块类实例。
escapeHtml(): 非常重要的安全函数，用于转义输出内容，防止 XSS 攻击,所有来自数据库或用户输入的内容都应该转义。

步骤 7：访问页面

清空所有缓存,然后访问你的页面：

www.yourstore.com/helloworld/index/index

或者更简单的（因为 index/index 是默认的）：

www.yourstore.com/helloworld

你应该能看到你的 "Hello World" 页面了！

第三部分：进阶主题

掌握了基础页面创建后,你可以探索更高级的功能。

使用插件

假设你想修改 Magento\Catalog\Model\Product 的 getName() 方法。

创建插件类: app/code/MyVendor/HelloWorld/Plugin/ProductNamePlugin.php

<?php
namespace MyVendor\HelloWorld\Plugin;
class ProductNamePlugin
{
    // 在 getName 方法执行后运行
    public function afterGetName(\Magento\Catalog\Model\Product $subject, $result)
    {
        // $result 是 getName() 方法的原始返回值
        return $result . ' - Awesome Product!';
    }
}

afterGetName: 插件方法名，after + 原方法名。
$subject: 被拦截的原始对象。
$result: 原方法的返回值。

配置插件: app/code/MyVendor/HelloWorld/etc/di.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Catalog\Model\Product">
        <plugin name="myvendor_helloworld_product_name" type="MyVendor\HelloWorld\Plugin\ProductNamePlugin" sortOrder="10" disabled="false"/>
    </type>
</config>

<type name="...">: 指定你要拦截的类。
<plugin>: 定义插件。
- name: 插件的唯一名称。
- type: 插件类的完整路径。
- sortOrder: 当多个插件作用于同一个方法时,决定执行顺序。

创建自定义配置

在后台系统设置中添加自定义选项。

创建系统配置文件: app/code/MyVendor/HelloWorld/etc/adminhtml/system.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/system.xsd">
    <system>
        <tab id="myvendor" translate="label" sortOrder="100">
            <label>My Vendor</label>
        </tab>
        <section id="helloworld" translate="label" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Hello World</label>
            <tab>myvendor</tab>
            <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>General Settings</label>
                <field id="enabled" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Enable Module</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
                <field id="message" translate="label" type="textarea" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Message</label>
                    <depends>
                        <field id="enabled">1</field>
                    </depends>
                </field>
            </group>
        </section>
    </system>
</config>

在代码中获取配置值: 在你的块或控制器中,你可以这样获取配置：

protected $_scopeConfig;
public function __construct(
    \Magento\Framework\App\Config\ScopeConfigInterface $scopeConfig,
    array $data = []
) {
    $this->_scopeConfig = $scopeConfig;
    parent::__construct($data);
}
public function getConfigValue()
{
    return $this->_scopeConfig->getValue(
        'helloworld/general/enabled',
        \Magento\Store\Model\ScopeInterface::SCOPE_STORE
    );
}

创建数据模型

与数据库交互。

创建模型文件: app/code/MyVendor/HelloWorld/Model/Example.php

<?php
namespace MyVendor\HelloWorld\Model;
class Example extends \Magento\Framework\Model\AbstractModel
{
    protected function _construct()
    {
        $this->_init(\MyVendor\HelloWorld\Model\ResourceModel\Example::class);
    }
}

创建资源模型文件: app/code/MyVendor/HelloWorld/Model/ResourceModel/Example.php

<?php
namespace MyVendor\HelloWorld\Model\ResourceModel;
class Example extends \Magento\Framework\Model\ResourceModel\Db\AbstractDb
{
    protected function _construct()
    {
        $this->_init('helloworld_example_table', 'example_id'); // table name, primary key
    }
}

创建数据库安装/升级脚本: app/code/MyVendor/HelloWorld/Setup/InstallSchema.php

<?php
namespace MyVendor\HelloWorld\Setup;
use Magento\Framework\Setup\InstallSchemaInterface;
use Magento\Framework\Setup\ModuleContextInterface;
use Magento\Framework\Setup\SchemaSetupInterface;
class InstallSchema implements InstallSchemaInterface
{
    public function install(SchemaSetupInterface $setup, ModuleContextInterface $context)
    {
        $installer = $setup;
        $installer->startSetup();
        $table = $installer->getConnection()->newTable(
            $installer->getTable('helloworld_example_table')
        )->addColumn(
            'example_id',
            \Magento\Framework\DB\Ddl\Table::TYPE_INTEGER,
            null,
            ['identity' => true, 'unsigned' => true, 'nullable' => false, 'primary' => true],
            'Example ID'
        )->addColumn(
            'name',
            \Magento\Framework\DB\Ddl\Table::TYPE_TEXT,
            255,
            ['nullable' => false],
            'Example Name'
        )->setComment(
            'Hello World Example Table'
        );
        $installer->getConnection()->createTable($table);
        $installer->endSetup();
    }
}

运行 bin/magento setup:upgrade 来执行这个脚本,创建数据库表。

第四部分：最佳实践与调试

最佳实践

始终使用插件: 除非万不得已,不要覆盖类。
遵循命名规范: 命名空间、类名、文件名必须严格遵循 PSR-4 标准。
依赖注入: 在构造函数中声明你的依赖，不要在类内部 new 一个对象。
使用依赖注入代理: 对于重量级的对象（如 Repository, Factory），在构造函数中注入它们的代理版本,以避免循环依赖。
转义所有输出: 在模板中，永远不要直接输出变量，始终使用 escapeHtml(), escapeUrl() 等函数。
使用静态代码分析: 在提交代码前，运行 bin/magento dev:tests:static 来检查代码质量和潜在问题。
编写单元测试: Magento 2 有强大的测试框架，为你的核心逻辑编写单元测试,确保代码质量。

调试技巧

日志: 最简单直接的调试方法。
```
$this->_logger->info('My debug message: ' . $someVariable);
```
确保你的模块有 logger.xml 配置，或者使用 Magento 核心的日志系统。
Xdebug: 设置 Xdebug 是 PHP 开发的必备技能，你可以通过 IDE（如 VS Code, PhpStorm）在代码中设置断点,一步步调试代码执行流程。
布局调试: 在 URL 后面添加 ?showLayout=page 或 ?showLayout=blocks，可以可视化地查看页面的布局结构,非常有助于理解布局是如何加载的。
依赖注入调试: 在构造函数中 die() 或 print_r(func_get_args())，看看 Magento 2 到底给你注入了哪些对象。

第五部分：学习资源

官方文档: Magento 2 Developer Documentation (英文，最权威,但有时比较晦涩)
官方 GitHub: magento/magento2 (阅读核心代码是学习的最好方式)
Mage-Plaza Blog: Mage-Plaza Blog (有大量高质量的中文和英文教程)
Alan Storm: alanstorm.com (Magento 2 的传奇人物，他的文章和教程深入浅出,强烈推荐)
Stack Overflow: magento2 (遇到问题,先搜索这里)

Magento 2 二次开发是一个学习曲线较陡峭但回报丰厚的技能,关键在于：

打好基础: 深入理解 DI, 插件, 模块化。
动手实践: 从创建一个简单页面开始，逐步尝试插件、配置、模型等功能。
善用工具: 熟练使用命令行、IDE、调试工具。
阅读源码: Magento 2 本身就是最好的教科书。
遵循最佳实践: 写出健壮、可维护、可扩展的代码。

祝你开发顺利！