系统要求

Magento 2.4.8 系统架构与依赖组件

组件	版本要求	备注
PHP	8.3 或 8.4	推荐 8.4；8.2 仅升级过渡必须
MySQL	8.4 LTS	utf8mb4 排序规则
MariaDB	11.4 LTS	MySQL 替代方案
OpenSearch	3.x	ES 已移除必须
Composer	2.9.3+	1.x 不支持必须
Redis	7.2	或 Valkey 8 推荐
RabbitMQ	4.1	异步队列必须
RAM	≥8 GB	生产推荐 16-32 GB

必需 PHP 扩展

bcmath, ctype, curl, dom, gd, hash, iconv, intl, mbstring,
openssl, pdo_mysql, simplexml, soap, spl, xsl, zip, sodium

🔴 Magento 2 不支持共享主机，需 VPS 或独立服务器。2.4.8 必须使用 OpenSearch 3，Elasticsearch 已完全移除。

选择安装方式

通过 Composer 安装 Magento 2

Composer 是官方推荐的生产环境安装方式，通过依赖管理创建项目，确保版本兼容、便于升级维护。

✅ 优势：支持第三方库而不修改核心、降低代码冲突、精确控制版本、遵循 PSR 标准。

Composer 安装完整流程与前置条件

0 验证服务器环境

$ php -v
# 确认 PHP 8.3 或 8.4
$ php -m
# 检查必需扩展：bcmath, ctype, curl, dom, gd...
$ mysql -V
$ curl -X GET "localhost:9200"
# 确认 OpenSearch 运行中

1 安装 Composer

$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer
$ composer --version
Composer version 2.9.3 ...

⚠️ Composer 版本必须 ≥ 2.9.3，1.x 不支持 Magento 2.4.x。

2 获取 Adobe Marketplace 认证密钥

Marketplace 认证密钥获取流程

访问 marketplace.magento.com 并登录
进入 My Profile → Access Keys → Magento 2
点击 Create a New Access Key
复制 Public Key（用户名）和 Private Key（密码）

auth.json

{
  "http-basic": {
    "repo.magento.com": {
      "username": "<YOUR_PUBLIC_KEY>",
      "password": "<YOUR_PRIVATE_KEY>"
    }
  }
}

3 创建数据库

$ mysql -u root -p
mysql> CREATE DATABASE magento2;
mysql> CREATE USER 'magento'@'localhost' IDENTIFIED BY 'YOUR_SECURE_PASSWORD';
mysql> GRANT ALL PRIVILEGES ON magento2.* TO 'magento'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> EXIT;

4 创建 Magento 项目

$ composer create-project \
--repository-url=https://repo.magento.com/ \
magento/project-community-edition=2.4.8 \
/var/www/magento2

💡 project-community-edition = 开源版(免费)；project-enterprise-edition = Adobe Commerce(付费)。可用 ~2.4.8 获取最新补丁版。

⚠️ 内存不足时：COMPOSER_MEMORY_LIMIT=-1 composer create-project ...

Composer 创建的项目目录结构

5 设置文件权限

$ cd /var/www/magento2
$ find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
$ find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +
$ chown -R magento:www-data .
$ chmod u+x bin/magento

⚠️ 不要使用 chmod 777！g+w 组写权限是安全做法。

6 运行安装命令

$ bin/magento setup:install \
--base-url="https://your-domain.com/" \
--db-host="localhost" \
--db-name="magento2" \
--db-user="magento" \
--db-password="YOUR_DB_PASSWORD" \
--admin-firstname="Admin" \
--admin-lastname="User" \
--admin-email="admin@your-domain.com" \
--admin-user="admin" \
--admin-password="YOUR_ADMIN_PASSWORD" \
--language="zh_CN" \
--currency="CNY" \
--timezone="Asia/Shanghai" \
--search-engine="opensearch" \
--opensearch-host="localhost" \
--opensearch-port="9200" \
--use-rewrites=1

🔴 关键参数：--search-engine="opensearch" 必须使用 opensearch；旧 elasticsearch7 不再支持。管理员密码至少 7 字符+字母数字。

常见问题

错误	原因	解决方案
Killed / 内存不足	Composer 解析内存不够	`COMPOSER_MEMORY_LIMIT=-1` 或添加 2GB swap
OpenSearch 连接失败	OpenSearch 未运行	`systemctl status opensearch`，检查端口 9200
目录不可写	权限配置错误	重新执行 Step 5 权限命令
依赖冲突	Composer 缓存问题	`composer clear-cache && composer update`

💬 遇到问题？在中文社区论坛提问获取帮助。

Docker 安装

Docker 容器化安装适合团队开发，一键搭建完整环境，服务隔离、可复现。

Docker 容器化 Magento 架构

方案 A：docker-magento（Mark Shust）

最受欢迎的 Magento Docker 方案，一键安装，自动配置所有服务。

$ curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onboards \| bash
$ cd magento
$ bin/setup # 自动创建项目 + 安装 + 配置

方案 B：DDEV

DDEV 是通用 PHP 开发环境工具，配置简单，支持多项目。

$ ddev config --project-type=magento2 --php-version=8.3
$ ddev composer create magento/project-community-edition=2.4.8
$ ddev magento setup:install --base-url="..." ...
$ ddev start

对比维度	docker-magento	DDEV	Warden
定位	Magento 专属	通用 PHP 环境	Magento 专属
一键安装	✅ bin/setup	需手动安装	✅ 自动
多项目	❌ 单项目	✅ 支持多项目	✅ 支持多项目
SSL	✅ 自动	✅ 自动	✅ 自动
难度	中级	初级	高级

Git/GitHub 安装

直接克隆源码仓库，适合参与开源贡献的开发者。

$ git clone https://github.com/magento/magento2.git
$ cd magento2
$ composer install
$ bin/magento setup:install --...
# 后续步骤与 Composer 安装相同

💡 克隆的仓库是开发版本，可能不稳定。生产环境推荐 Composer 安装。

归档包安装

下载 ZIP/TAR.GZ 手动部署，适合离线/受限环境，后续升级困难。

$ wget https://github.com/magento/magento2/archive/refs/tags/2.4.8.tar.gz
$ tar -xzf 2.4.8.tar.gz -C /var/www/magento2
$ cd /var/www/magento2
$ composer install
$ bin/magento setup:install --...

⚠️ 归档包安装后升级较困难，建议仅在无法使用 Composer 的场景下使用。

本地开发环境

学习、测试、本地开发的三种方案：

方案	适用	说明
DDEV	所有平台	推荐方案，跨平台、配置简单、支持多项目
XAMPP/MAMP	Windows/Mac	传统图形化工具，需手动配置服务
WSL2	Windows	Windows Subsystem for Linux，原生 Linux 环境

安装后验证

$ bin/magento info:adminuri
Admin URI: /admin_xxxxx # 记录此地址
$ bin/magento setup:di:compile
$ bin/magento setup:static-content:deploy -f
$ bin/magento cache:flush
$ bin/magento deploy:mode:set production
Successfully switched to production mode.

安装验证步骤

🔴 上线前必须切换到 production 模式！禁止在 developer 模式运行生产店铺。

升级指南

Magento 定期发布安全补丁和功能更新。升级前务必做好备份。

⚠️ 升级前必做：备份数据库 + 代码 + 媒体文件，在测试环境先验证升级。

$ # 1. 备份数据库和代码
$ bin/magento setup:backup --code --db --media
$ # 2. 切换到维护模式
$ bin/magento maintenance:enable
$ # 3. 更新 Composer 依赖
$ composer require magento/product-community-edition=2.4.8 --no-update
$ composer update
$ # 4. 运行升级
$ bin/magento setup:upgrade
$ bin/magento setup:di:compile
$ bin/magento setup:static-content:deploy -f
$ bin/magento cache:flush
$ # 5. 关闭维护模式
$ bin/magento maintenance:disable

💡 升级详细说明请参考社区文档参考。

商店基本设置

安装完成后，需要配置以下核心设置：

配置项	位置	说明
商店名称与描述	Stores → Settings → Configuration → General	设置商店名称、联系方式、地区
货币与税率	Stores → Currency & Tax	设置货币显示、税率规则
支付方式	Stores → Payment Methods	启用/配置支付网关
物流方式	Stores → Shipping Methods	配置运费计算和配送方式
邮件发送	Stores → Email	SMTP 配置、订单确认邮件模板

商品管理

Magento 支持 6 种商品类型，覆盖几乎所有电商场景：

商品类型	适用场景	说明
Simple Product	单件商品	最基本类型，一个 SKU 一个价格，如一本书
Configurable Product	多规格商品	有颜色/尺码等选项，每个选项对应一个 Simple Product
Grouped Product	组合商品	多个 Simple Product 组合展示，如一套家具
Bundled Product	捆绑定制	客户自选组合，如电脑配置（CPU+内存+硬盘）
Virtual Product	虚拟商品	无需物流，如服务、会员、保险
Downloadable Product	下载商品	电子书、软件、音乐文件等可下载内容

💡 批量操作：后台 Catalog → Products 支持批量编辑价格、状态、属性，也可通过 CSV 导入导出商品数据。

订单处理

Magento 提供完整的订单生命周期管理：

操作	后台位置	说明
查看订单	Sales → Orders	查看所有订单详情、客户信息、商品明细
创建发票	Order → Invoice	确认收款后创建发票，部分或全额
发货	Order → Ship	添加物流单号和备注，支持分批发货
退款	Order → Credit Memo	全额或部分退款，退款到原支付方式
取消订单	Order → Cancel	未付款订单可取消
订单状态	自动流转	Pending → Processing → Complete / Canceled

营销与促销

Magento 内置完整的促销系统，无需额外插件即可创建多种营销活动：

促销类型	配置位置	典型用法
Catalog Price Rule	Marketing → Catalog Rules	全场打折、分类打折、会员专属价
Cart Price Rule	Marketing → Cart Rules	购物车满减、优惠券码、买N免1
Coupon Code	Cart Rule → Coupon	自动生成/手动指定优惠券码
Related/Up-sell/Cross-sell	Product → Related Products	关联推荐、升级推荐、交叉推荐
Bundled Discount	Bundled Product	搭配组合优惠价
Loyalty Points	需第三方扩展	积分系统（开源版需扩展）

SEO 设置

Magento 内置强大的 SEO 功能，帮助您的商店获得更多自然搜索流量：

SEO 功能	配置位置	说明
URL 重写	Marketing → URL Rewrites	自定义商品/分类 URL，去除冗余参数
元数据模板	Stores → SEO	批量设置商品/分类的 title、description、keywords 模板
站点地图	Marketing → Sitemap	自动生成 sitemap.xml，提交到搜索引擎
Alt 标签	Product → Images	商品图片自动生成 alt 标签
Canonical URL	Stores → SEO	防止重复内容，指定规范 URL
Robots Meta	Stores → SEO	控制搜索引擎爬取特定页面

多店铺管理

Magento 的多店铺系统是其核心优势之一，一个后台可以管理多个完全独立的商店：

概念	说明	典型用法
Website	独立站点，可有独立域名	品牌A (brand-a.com) + 品牌B (brand-b.com)
Store	一个 Website 下的子商店	英文店 + 中文店（同一品牌不同语言）
Store View	同一 Store 的不同展示版本	CNY 人民币视图 + USD 美元视图

✅ 所有店铺共享同一数据库和后台，但各自有独立的商品分类、定价、主题和客户体验。共享库存，独立定价。

缓存管理

$ bin/magento cache:status
$ bin/magento cache:enable
$ bin/magento cache:flush
$ bin/magento cache:clean

Cron 任务

Magento 依赖 Cron 执行定时任务（索引更新、邮件发送、报表生成等）。

$ bin/magento cron:install
# 安装 Magento Cron 到系统
$ bin/magento cron:run
# 手动运行一次 Cron

架构概览

Magento 2 采用模块化架构，核心功能被拆分为独立模块，通过 Service Contracts 和 DI 实现松耦合。

Magento 2 四层架构模型

模块架构

模块是 Magento 2 的核心构建单元，每个模块封装独立功能。模块之间通过 Service Contracts 通信，而非直接调用。

目录结构

模块目录结构

app/code/Vendor/Module/
├── Api/              # 服务契约接口
│   └── Data/         # 数据接口
├── Block/            # 视图 Block 类
├── Controller/       # 控制器（Admin + Frontend）
├── Model/            # 业务模型 + Resource Model
├── Observer/         # 事件观察者
├── Plugin/           # 插件（拦截器）
├── Setup/            # 数据库安装/升级脚本
├── etc/              # 配置 XML 文件
│   ├── module.xml    # 模块注册
│   ├── di.xml        # 依赖注入配置
│   ├── events.xml    # 事件观察者配置
│   ├── acl.xml       # 权限控制
│   ├── config.xml    # 系统配置
│   └── webapi.xml    # Web API 路由
├── view/             # 前端视图
│   ├── frontend/     # 前台模板布局
│   ├── adminhtml/    # 后台模板布局
│   └── base/         # 共用视图
├── registration.php  # 模块注册入口
└── composer.json     # Composer 包定义

模块开发入门

创建自定义模块是扩展 Magento 功能的核心方式。每个模块需要 registration.php 和 etc/module.xml 两个必要文件。

registration.php

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
  \Magento\Framework\Component\ComponentRegistrar::MODULE,
  'Vendor_Module',
  __DIR__
);

💡 模块命名遵循 Vendor_Module 格式，目录对应 app/code/Vendor/Module/。

依赖注入 (DI)

Magento 2 使用 di.xml 配置依赖注入，替代直接 new 对象。

di.xml 示例

<config>
  <type name="Magento\Catalog\Model\Product">
    <arguments>
      <argument name="helper" xsi:type="object">
        Vendor\Module\Helper\Data
      </argument>
    </arguments>
  </type>
</config>

插件 (Plugins / Interceptors)

插件用于修改类的公共方法行为，不修改原始代码。

类型	方法前缀	作用
Before	`beforeMethodName()`	在原方法前执行，可修改参数
After	`afterMethodName()`	在原方法后执行，可修改返回值
Around	`aroundMethodName()`	完全包裹原方法，可控制是否调用

di.xml 插件配置

<config>
  <type name="Magento\Catalog\Model\Product">
    <plugin name="custom_product_plugin"
            type="Vendor\Module\Plugin\ProductPlugin"
            sortOrder="10"
            disabled="false"/>
  </type>
</config>

观察者 (Observers)

观察者监听系统事件，执行自定义逻辑。

events.xml

<config>
  <event name="catalog_product_save_after">
    <observer name="vendor_product_save"
              instance="Vendor\Module\Observer\ProductSaveAfter"/>
  </event>
</config>

服务契约

服务契约定义模块的公共 API 接口，确保稳定性。

💡 最佳实践：所有模块对外通信必须通过 Service Contracts（接口），而非直接调用实现类。接口定义在 Api/ 目录。

主题开发

主题目录结构

app/design/frontend/Vendor/customtheme/
├── etc/
│   └── view.xml          # 图片尺寸等配置
│   └── theme.xml         # 主题元信息
├── registration.php      # 注册入口
├── web/
│   ├── css/              # 样式文件
│   ├── js/               # JavaScript
│   ├── images/           # 图片资源
│   └── fonts/            # 字体
├── Magento_Theme/        # 覆写核心模块模板
│   └── layouts/          # 布局 XML
│   └── templates/        # 模板 PHTML

布局、区块与模板

Magento 页面由三层构建：Layout XML（定义结构）→ Block（提供数据）→ Template (.phtml)（渲染 HTML）。

Layout XML 示例

<page xmlns:xsi="...">
  <body>
    <referenceContainer name="content">
      <block class="Vendor\Module\Block\Product\View"
             name="custom.product.view"
             template="Vendor_Module::product/view.phtml"/>
    </referenceContainer>
  </body>
</page>

UI 组件

Magento 2 使用 UI Component 系统构建后台表单、列表和网格。UI 组件通过 XML 定义，自动绑定 KnockoutJS 数据。

CLI 命令参考

命令	说明	示例
`setup:install`	安装 Magento	`bin/magento setup:install --...`
`setup:upgrade`	升级模块/数据库	`bin/magento setup:upgrade`
`setup:di:compile`	编译 DI 代理类	`bin/magento setup:di:compile`
`setup:static-content:deploy`	生成静态资源	`bin/magento setup:static-content:deploy -f`
`cache:flush`	清空所有缓存	`bin/magento cache:flush`
`cache:clean`	清理过期缓存	`bin/magento cache:clean`
`cache:enable/disable`	启用/禁用缓存类型	`bin/magento cache:enable layout`
`indexer:reindex`	重建所有索引	`bin/magento indexer:reindex`
`deploy:mode:set`	切换运行模式	`bin/magento deploy:mode:set production`
`module:status`	查看模块状态	`bin/magento module:status`
`module:enable/disable`	启用/禁用模块	`bin/magento module:enable Vendor_Module`
`cron:run`	执行 Cron 任务	`bin/magento cron:run`
`info:adminuri`	获取 Admin URL	`bin/magento info:adminuri`
`maintenance:enable/disable`	维护模式开关	`bin/magento maintenance:enable`

💡 查看所有可用命令：bin/magento list

REST API

Magento 2 提供完整的 REST API，覆盖商品、订单、客户、购物车等所有核心功能。

端点	方法	说明
`/rest/V1/products`	GET/POST	商品列表/创建
`/rest/V1/products/:sku`	GET/PUT/DELETE	商品详情/更新/删除
`/rest/V1/orders`	GET	订单列表
`/rest/V1/customers`	GET/POST	客户管理
`/rest/V1/cart/:cartId`	GET/POST	购物车操作
`/rest/V1/categories`	GET/POST	分类管理

GraphQL API

GraphQL API 是前端（Headless）开发的首选，支持灵活查询和按需取数据。

GraphQL 查询示例

query {
  products(search: "bag", pageSize: 10) {
    items {
      sku
      name
      price {
        regularPrice {
          amount { value currency }
        }
      }
      image { url label }
    }
  }
}

Web API 认证

认证方式	适用场景	说明
Token	第三方集成	通过 `/rest/V1/integration/admin/token` 获取
OAuth	第三方应用	OAuth 1.0a 认证流程
Session	前端/后台用户	登录后自动附带

安全功能

安全功能	说明
自定义 Admin URL	修改管理后台路径，降低攻击面
双因素认证 (2FA)	强制后台管理员使用 2FA 登录
CAPTCHA	防止自动注册、登录暴力攻击
加密密钥管理	保护敏感数据（密码、支付信息）
PCI 合规	支付数据处理符合 PCI DSS 标准
XSS/CSRF 防护	内置输入过滤和请求验证
安全补丁	定期发布安全更新，及时修补漏洞

性能最佳实践

✅ 生产环境性能要点：

启用 production 模式（禁止 developer 模式上线）
配置 Varnish 全页缓存（不使用 Built-in Cache）
启用 Redis 作为缓存和 Session 存储
合并和压缩 CSS/JS：bin/magento setup:static-content:deploy -f
运行 DI 编译：bin/magento setup:di:compile
配置 OpenSearch 作为搜索引擎
设置 Cron 确保索引定时更新

🔗 本站文档源码开源，欢迎贡献：GitHub 仓库 · 交流提问：中文社区论坛

Magento 2 技术文档

安装文档

系统要求

选择安装方式

通过 Composer 安装 Magento 2

0 验证服务器环境

1 安装 Composer

2 获取 Adobe Marketplace 认证密钥

3 创建数据库

4 创建 Magento 项目

5 设置文件权限

6 运行安装命令

常见问题

Docker 安装

方案 A：docker-magento（Mark Shust）

方案 B：DDEV

Git/GitHub 安装

归档包安装

本地开发环境

安装后验证

升级指南

使用文档

商店基本设置

商品管理

订单处理

营销与促销

SEO 设置

多店铺管理

缓存管理

Cron 任务

开发文档

架构概览

模块架构

目录结构

模块开发入门

依赖注入 (DI)

插件 (Plugins / Interceptors)

观察者 (Observers)

服务契约

主题开发

布局、区块与模板

UI 组件

CLI 命令参考

API 文档

REST API

GraphQL API

Web API 认证

安全功能

性能最佳实践