Sylius 电商系统安装完整指南

用户307459698207
1 阅读4分钟

Sylius 是一个基于 Symfony 框架的开源无头电商平台。本文记录在 Windows + phpStudy 环境下安装 Sylius 2.2 的完整过程，以及踩坑经验。

环境要求

  • PHP 8.2+ （本文使用 PHP 8.3）
  • MySQL 8.0+ （或 PostgreSQL）
  • Composer 2.x
  • Node.js + npm（用于前端资源编译）
  • phpStudy（集成环境）

一、创建项目

composer create-project sylius/sylius-standard acme

注意：如果遇到 process timeout 错误（300 秒超时），先设置：

composer config process-timeout 0

二、配置数据库

编辑 .env 文件，修改 DATABASE_URL：

DATABASE_URL=mysql://root:你的密码@127.0.0.1/sylius_%kernel.environment%?serverVersion=8&charset=utf8mb4

关于 %kernel.environment% 参数：

APP_ENV 值实际数据库名
devsylius_dev
prodsylius_prod
testsylius_test

这是 Symfony 的环境变量占位符，让你在不同环境下自动使用不同的数据库，避免开发数据污染生产数据。

三、运行安装向导

php bin/console sylius:install

重要：如果加载 sample data 时遇到内存溢出错误（Allowed memory size exhausted），增加内存限制：

php -d memory_limit=1G bin/console sylius:install

安装向导分 7 步：

  1. 检查系统需求 — 确保 PHP 扩展和环境满足要求
  2. 设置数据库 — 自动创建数据库和表结构，加载示例数据
  3. 商店配置 — 选择货币（如 CNY）、语言（如 zh_CN）
  4. 创建管理员 — 设置后台管理员邮箱、用户名、密码
  5. 生成 JWT 密钥 — 用于 API 认证
  6. 安装前端资源 — 复制 assets 到 public 目录
  7. 清除缓存

四、编译前端资源

npm install
npm run build

这会编译 SCSS、JavaScript 等前端资源到 public/build/ 目录。

五、常见问题与解决

1. 500 Internal Server Error

可能的原因和解决方案：

a) JWT 密钥缺失

.env 中配置的 JWT 密钥文件（config/jwt/private.pem、public.pem）不存在。解决办法：

php bin/console lexik:jwt:generate-keypair

如果 OpenSSL 报错（error:80000003:system library::No such process），可能是 PHP 的 OpenSSL 扩展问题。临时方案：修改 .env 指向已存在的测试密钥：

JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private-test.pem
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public-test.pem
JWT_PASSPHRASE=ALL_THAT_IS_GOLD_DOES_NOT_GLITTER_NOT_ALL_THOSE_WHO_WANDER_ARE_LOST

b) Channel 未找到

错误信息：Channel could not be found!

Sylius 是多渠道电商系统，通过请求的 hostname（域名）匹配 Channel。如果访问的域名与数据库中 sylius_channel 表的 hostname 字段不一致，就会报错。

解决办法：将 Channel 的 hostname 改为你的访问域名：

UPDATE sylius_channel SET hostname = '你的域名.com' WHERE code = 'FASHION_WEB';

或者删除多余的 Channel，让 SingleChannelContext 兜底生效（只保留一个 Channel 时，Sylius 会自动匹配）。

2. 数据库连接被拒

Access denied for user 'root'@'localhost' (using password: NO)

说明 .env 中数据库密码没写。检查 DATABASE_URL：

# 错误：没有密码
DATABASE_URL=mysql://root@127.0.0.1/sylius_dev?...

# 正确：
DATABASE_URL=mysql://root:root@127.0.0.1/sylius_dev?...

3. 内存溢出

Allowed memory size of 536870912 bytes exhausted

增加 PHP 内存限制：

php -d memory_limit=1G bin/console sylius:install

或者在 php.ini 中永久修改：

memory_limit = 1G

六、Sylius 核心概念

Channel（渠道）

Sylius 支持多商店架构。每个 Channel 对应一个独立的前端商店，可以有各自的：

  • 域名（hostname）
  • 货币
  • 语言
  • 主题
  • 商品价格

Channel 的匹配机制：

  1. 优先通过请求的 hostname 精确匹配
  2. 如果只有 1 个 Channel，自动作为默认
  3. 开发环境下可通过 Web Debug Toolbar 手动切换

Context（上下文解析器）

Sylius 使用复合责任链模式解析当前 Channel：

CompositeChannelContext
├── CachedPerRequestChannelContext（缓存装饰器）
├── FakeChannelContext（调试模式，通过 cookie 切换）
├── RequestBased\ChannelContext（基于请求域名）
│   └── HostnameBasedRequestResolver
└── SingleChannelContext（兜底，仅1个Channel时生效）

七、开发环境 vs 生产环境

开发环境

APP_ENV=dev
APP_DEBUG=1
  • 详细错误页面
  • Web Debug Toolbar
  • 自动生成代理类

生产环境

创建 .env.local 覆盖配置：

APP_ENV=prod
APP_DEBUG=0
DATABASE_URL=mysql://用户:密码@正式IP/正式库名?serverVersion=8&charset=utf8mb4

.env.local 优先级高于 .env，且不会提交到 Git，适合存放敏感配置。

八、访问地址

安装成功后，可以访问：

  • 前台商店：http://你的域名/
  • 后台管理：http://你的域名/admin/
  • API 文档：http://你的域名/api/v2/docs

总结

Sylius 是一个功能强大的开源电商系统，安装过程整体比较顺畅。主要踩坑点：

  1. 数据库配置 — 确保密码正确，理解 %kernel.environment% 参数
  2. JWT 密钥 — OpenSSL 问题可以用测试密钥临时解决
  3. Channel 匹配 — hostname 必须和访问域名一致
  4. 内存限制 — 加载 fixtures 数据需要较大内存
avatar
文章
阅读
粉丝