Solidus CHANGELOG 深度解析:从 v1.0 到 v4.8 的版本演进、破坏性变更与升级实战指南
Solidus CHANGELOG 深度解析:从 v1.0 到 v4.8 的版本演进、破坏性变更与升级实战指南
Solidus 的开源电商框架在 CHANGELOG.md 中完整记录了从 2015 年 v1.0.0 到 2026 年 v4.8.0 的全部版本历程,涵盖 Core、Admin、Backend、API、Promotions 等所有组件的功能演进、破坏性变更、安全修复与升级指引。本文以该文档为主线,结合仓库源码,为你梳理 Solidus 各版本的核心变化脉络,并给出可直接落地的升级操作步骤与配置示例,帮助你在升级 Solidus 时做出准确判断、规避踩坑。
一、CHANGELOG 的组织结构:读懂 Solidus 的多组件发布体系
Solidus 以 meta-gem 的形式将多个独立引擎捆绑发布,因此 CHANGELOG 不是单一维度的变更列表,而是按组件分节组织的。从 v4.8.0 的最新版本(2026-10-09)可以看出当前包含以下组件节:
- Solidus:meta 包层面的变更(安装流程、README、CI/CD、许可协议等);
- Solidus Core:
core/目录,订单、库存、支付、税、地址、用户等核心领域逻辑; - Solidus Admin:
admin/目录,基于 ViewComponent + Tailwind CSS 的新一代后台; - Solidus Backend:
backend/目录,传统 Rails ERB 后台; - Solidus API:
api/目录,REST API 与 OpenAPI 文档; - Solidus Sample:
sample/目录,示例数据; - Solidus Promotions:
promotions/目录,新一代促销引擎; - Solidus Legacy Promotions:
legacy_promotions/目录,从 Core 中抽取出的传统促销系统; - Solidus Storefront:
storefront/目录,v4.7 起并入的 starter frontend; - Solidus I18n:
i18n/目录,多语言翻译。
这种组织方式意味着升级时不能只看 "Solidus" 节的条目,而要根据你实际使用的组件(尤其是 solidus_promotions 与 solidus_legacy_promotions 的取舍)逐节核对。每个版本末尾的 Full Changelog 链接指向两个 tag 之间的完整 PR 列表,是回溯具体改动细节的入口。
二、v4.8 / v4.7 / v4.6:近期版本的关键走向
2.1 v4.8.0(2026-10-09):storefront 并入与 admin 编辑器补全
v4.8.0 最值得关注的结构性变化是 Merge solidus_starter_frontend in as "storefront"——starter frontend 正式并入主仓库成为 storefront/ 组件,并配套 "Use storefront pricing" 与 "Drive storefront system specs with headless Firefox" 等改动,说明官方前台已纳入主仓的持续集成体系。
Core 方面集中出现了一批订单重算领域的重构:Only fire order recalculated events after save、Don't "persist_amounts" in order recalculation、Avoid redundant queries when recalculating payment totals,以及多处 N+1 消除(预加载 variants、product、tax 关联)。这类改动直接影响订单金额计算的时机与 SQL 查询次数,升级后应重点回归测试购物车金额变动、税收计算与库存分配流程。
Admin 方面新增了 stores editor、tax rates editor、payment methods editor、product taxon management、option types/values editor,标志着新后台对核心配置资源的覆盖趋于完整;同时 Eager load associations in admin and API collection endpoints 将预加载策略推广到了所有集合端点。
v4.8.0 还包含一条值得注意的安全相关工程改动:fix(core): permit Symbol and HashWithIndifferentAccess in log entries 与 feat(log_entry): write details unparsed and validate on read,将 Spree::LogEntry 的 YAML 序列化策略从"写入时解析"调整为"原样写入、读取时校验",这是对 log_entry.rb 序列化安全模型的进一步加固(详见本文第六节)。
2.2 v4.7.0(2026-04-15):运行环境基线整体上移
v4.7.0 的核心信息非常明确:
- Require Ruby 3.2:最低 Ruby 版本提升到 3.2;
- Allow Rails 8.1、Require Rails 7.2:Rails 支持范围变为 7.2 与 8.x;
- Switch to standardrb:代码规范从 RuboCop 切换到 standardrb。
Core 引入了多项可配置扩展点:Configurable stock quantifier(库存量化器可替换)、Configurable Order Mergeable Scope、Make state change tracker a configurable class、Allow to recalculate cart prices、In-memory order updater。Promotions 侧则完成了一次大型重构:Create single-responsibility conditions for products, taxons, and option values、Allow promotion calculators to set dynamic adjustment labels、Allow strikethrough prices to be calculated for variants、Change promotion condition configuration to be flat,并为 PercentWithCap、TieredFlatRate、DistributedAmount 等计算器补充了 YARD 文档——新促销系统的条件模型从"多功能混合"走向"单一职责"。
2.3 v4.6.0(2025-09-09):事件订阅与地址簿字段
v4.6.0 继续推进事件驱动的邮件架构:Configurable Solidus event subscribers、Move OrderMailerSubscriber#send_confirmation_email、Move carton shipped emails to subscriber,邮件发送逐步从模型回调迁移到可配置的订阅者体系。同时新增了面向欧盟税务场景的字段:Add reverse charge status to stores、Add reverse charge fields to address,对应 core/db/migrate/20250225051308_add_vat_id_email_and_reverse_charge_status_to_addresses.rb 等迁移文件。
三、v4.x 系列:现代化与去旧化的主旋律
3.1 v4.4.0(2024-11-12):促销系统分家
v4.4.0 是促销架构的分水岭:Add Legacy promotions gem 将传统促销系统整体抽取为 solidus_legacy_promotions,随后 Move promotion backend controllers and views to legacy_promotions、Move Legacy Promotions Service Objects、Extract Legacy Promotion System: Move ActiveRecord Models and Factories、Move eligible column to legacy promotions 等一系列 PR 把促销相关的模型、控制器、服务对象、迁移逐项搬离 Core。Core 则通过 配置对象(Promotion configuration) 与 Null Promotion Configuration 保持对促销的松耦合——即使不加载任何促销 gem,Core 依然能正常启动(对应仓库中的 core/lib/spree/app_configuration.rb 与 legacy_promotions/、promotions/ 目录结构)。
这一版本同时引入了 SimpleOrderContents 作为默认订单内容操作实现,并把 Spree::Config.promotions.promotion_adjuster_class 等配置名重命名,任何依赖旧配置名的扩展都需同步调整。
3.2 v4.3.0(2023-12-22)与 v4.2.0(2023-09-29):生态底座更新
v4.3.0 将最低 Ruby 提升至 3.1,v4.2.0 允许 Rails 7.1;v4.3.0 起 solidus_admin 作为独立 gem 以 >= 0.2 版本捆绑进安装器。v4.3.0 还引入 Configurable promotion adjustment sources 与 Add extension point: Promotion finder,让促销调整来源与促销查找逻辑均可替换。
3.3 v4.0.0(2023-05-04):删繁就简的大版本
v4.0.0 兑现了 v3.x 期间的全部弃用承诺,是升级工作量最大的一个版本:
- 移除 meta gem 中的
solidus_frontend(前台需显式添加); - 移除旧事件系统(
Remove support for legacy event system),只保留 Omnes 事件总线; - 移除
allow_promotions_any_match_policy相关支持(Remove support for deprecated promo rules matching policy); - 移除大量已弃用的 Preferences(
Remove Deprecated Preferences); - 仅支持 Ruby 3 与 Rails 7;
- 移除
spree_taxons.position、spree_shipments.deprecated_address_id等历史列。
升级到 v4.0.0 前,应先在 v3.x 上清理所有弃用警告(Spree::Deprecation),否则应用将直接报错。
四、v3.x 系列:升级机制从无到有的奠基时代
v3.x 是 Solidus 建立"可平滑升级"工程文化的关键阶段,CHANGELOG 中保留了大量可直接照做的配置示例,是本文实战价值最高的部分。
4.1 v3.2.0(2022-08-18):新事件总线与装饰器加载变革
v3.2.0 的 Major changes 包含三项核心内容:
(1)新事件总线(New Event Bus) 基于独立的 Omnes gem 实现全新事件总线,提供异步订阅、可测试性、可观测性。旧事件系统仍受支持但将在 v4 移除。仓库中的订阅者示例集中在 core/app/subscribers/spree/,例如订单邮件、库存取消邮件等订阅者,正是这一架构的落点。
(2)新 starter frontend 推荐
新项目推荐使用 solidus_starter_frontend;solidus_frontend 将从 meta-gem 移除并独立成仓库。安装器允许二选一。
(3)装饰器自动加载的终止
新应用不再自动加载 app/**/*_decorator*.rb 模式的文件。CHANGELOG 给出了完整的迁移示例——从旧的 require_dependency 写法:
config.to_prepare do
Dir.glob(Rails.root.join('app/**/*_decorator*.rb')) do |path|
require_dependency(path)
end
end
迁移到基于 app/overrides 目录的新写法:
overrides = "#{Rails.root}/app/overrides" # use your actual directory here
Rails.autoloaders.main.ignore(overrides)
config.to_prepare do
Dir.glob("#{overrides}/**/*_decorator*.rb").each do |override|
load override
end
end
并附带重要警告:若依赖 deface gem,app/overrides 会与其加载目录冲突,应改用 app/monkey_patches 等目录。
(4)促销 match_policy 的弃用
any 匹配策略的促销被弃用,可通过 rake 任务拆分:
bin/rake solidus:split_promotions_with_any_match_policy
如仍需创建,可在 config/initializers/spree.rb 中临时开启:
# Allow creating new promotions with an `any` match policy. Unsupported in the future.
config.allow_promotions_any_match_policy = true
(5)静态偏好源迁移到 to_prepare 块
由于 Rails 7 不再支持在 initializer 中引用可自动加载类,静态模型偏好(static preference sources)必须从 Spree.config 块迁移到 Rails.application.config.to_prepare 块:
# config/initializers/spree.rb
Rails.application.config.to_prepare do
Spree::Config.static_model_preferences.add(
AmazingStore::AmazingPaymentMethod,
'amazing_payment_method_credentials',
credentials: ENV['AMAZING_PAYMENT_METHOD_CREDENTIALS'],
server: Rails.env.production? ? 'production' : 'test',
test_mode: !Rails.env.production?
)
end
4.2 v3.1.0(2021-09-10):load_defaults 与版本化默认值机制
v3.1.0 引入了 Solidus 最重要的升级基础设施:Spree.load_defaults——偏好默认值按 Solidus 版本锁定。CHANGELOG 明确要求升级到 3.1 后,在 spree.rb 初始化器最顶部添加:
Spree.load_defaults('3.1')
该机制在源码中的实现位于 core/lib/spree/core.rb:Spree.load_defaults(version) 会依次对 Spree::Config、Spree::Frontend::Config、Spree::Backend::Config、Spree::Api::Config 调用 load_defaults(version),为所有可用组件加载同一版本的默认值。这样当 Solidus 调整某个推荐的偏好默认值时,你的应用不会因升级而静默改变行为,而是保持锁定的版本默认值,直到你主动采纳新默认。
配合的新升级流程是运行:
bin/rails g solidus:update
该生成器会创建一个名为 new_solidus_defaults.rb 的初始化器,逐行以注释形式预览两个版本之间所有发生变化的默认值。你可以逐个取消注释激活新默认、增量适配应用,全部完成后将 Spree.load_defaults 中的版本号上调并删除 new_solidus_defaults.rb。
v3.1.0 还要求 Spree::Price#amount 不再允许为 nil,升级前需执行数据清理任务:
bin/rails solidus:delete_prices_with_nil_amount
bin/rails railties:install:migrations
bin/rails db:migrate
该任务在仓库中的实现位于 core/lib/tasks/solidus/delete_prices_with_nil_amount.rake,其核心一行是 Spree::Price.with_discarded.where(amount: nil).delete_all——注意它连已软删除(discarded)的价格记录一并清理。CHANGELOG 还特别提醒:若在部署时自动跑迁移,应在发布新代码前先检查是否存在受影响记录:
Spree::Price.where(amount: nil).any?
4.3 v3.0.0(2021-04-20):大规模破坏性变更清单
v3.0.0 移除了 2.x 系列期间所有弃用的代码,CHANGELOG 列出了最容易导致应用崩溃的变更:
- Paranoia 被 Discard 取代:
paranoia_destroy、paranoia_delete、with_deleted、only_deleted、really_destroy!、after_real_destroy等 Paranoia 方法全部抛NoMethodError,需改用 Discard 的discard/kept等 API; Spree::Address只保留name字段:first_name/last_name的核心支持被移除,升级前需通过 v2.11 提供的 rake 任务把存量数据合并进name;- 一批无警告移除的类与偏好:
Spree::LineItem::CurrencyMismatch、Spree::Order::Checkout、Spree::TaxCalculator#ShippingRate等被删除;raise_with_invalid_currency、redirect_back_on_unauthorized、use_legacy_order_state_machine、use_combined_first_and_last_name_in_address等偏好已无任何效果,若不从初始化器中移除应用将无法启动; - 默认不加载整个 Rails 框架:如遇到问题,在
config/application.rb中显式require 'rails/all'; - Active Storage 成为默认附件适配器,Paperclip 切换到维护中的 fork(
kt-paperclip),旧商店可继续使用。
升级到 v3.0.0 的实操路径,就是逐一处理应用日志中的弃用警告,再对照上述清单清理代码与初始化器。
五、v2.x 系列:功能扩展与迁移铺垫
v2.x 为 v3.0 的破坏性变更做了大量铺垫,理解它们能解释"为什么 v3.0 会这样改"。
- v2.11.0(2020-10-23):引入
billing_address_required偏好控制账单地址校验;为Spree::Store增加 BCC email;Spree::Refund#perform!不再作为 after_create 回调自动执行,代码需从Spree::Refund.create(attrs)改为Spree::Refund.create(attrs, perform_after_creation: false).perform!;guest_token_cookie_options允许配置 cookie 跨子域;事件订阅者自动加载(app/subscribers/*_subscriber.rb);引入encrypted_string偏好类型加密敏感配置;为产品增加discontinue_on时间属性,与available_on一起构成"基于时间的可用性";开始用 Discard 逐步替换 Paranoia。 - v2.10.0(2020-01-15):完整支持 Rails 6(要求 Ruby 2.5+);状态机抽取为可替换模块(
Extract the state machines into replaceable modules);默认图片尺寸从small: '100x100>'提升到small: '400x400>'、product: '680x680>'、large: '1200x1200>'。 - v2.8.0 / v2.7.0 / v2.6.0 / v2.5.0(2018-2019):v2.8.0 支持 Rails 5.2;v2.7.0 引入存储信用(Store Credits)等功能完善;v2.5.0 期间后台迁移到 Bootstrap 4 并对设置菜单进行标签页化重构。
- v2.0.0(2016-09-26):升级到 Rails 5.0。
- v1.4.0(2016-09-26):OrderUpdater 全面改用内存对象,CHANGELOG 专门给出警告——若绕过 ActiveRecord 直接
update_all修改 line_items 会导致订单计算错误;创建调整项必须走关联关系:
# 推荐:通过 adjustable 关联创建
line_item.adjustments.create!(source: tax_rate, ...)
# 不推荐:绕过内存关联(可能产生错误结果)
Spree::Adjustment.create!(adjustable: line_item, source: tax_rate, ...)
同时 Order#persist_user_credit_card 更名为 Order#add_payment_sources_to_wallet,并新增 add_payment_sources_to_wallet_class、default_payment_builder_class 两个钱包扩展点。
- v1.2.0(2016-01-26):后台导航从顶部移到左侧;
Spree::Shipment#address列更名为deprecated_address_id并委托给Order#ship_address。
六、安全公告与配置加固:升级中不可跳过的部分
CHANGELOG 在 v3.1.x、v3.0.x、v2.11.x 系列中集中记录了多条安全修复,升级时务必确认所在版本已包含:
- GHSA-5629-8855-gf4g:solidus_auth_devise 的 CSRF 弱点认证绕过,通过 monkey patch 修复(v3.1.3 / v3.0.3 / v2.11.12);
- GHSA-qxmr-qxh6-2cc9:
Spree::EmailValidator::EMAIL_REGEXP的正则 DoS(ReDoS),通过收紧正则修复(v3.1.4 / v3.0.4 / v2.11.13); - GHSA-h3fg-h5v3-vf8m:
Spree::OrdersController#populate的 CSRF 伪造保护绕过(v3.1.5 / v3.0.5 / v2.11.14); - CVE-2022-32224:Rails 安全更新,v3.2.0 / v3.1.7 / v3.0.7 / v2.11.17 均有 backport。
其中 CVE-2022-32224 的 backport 引入了 Spree::LogEntry 的 YAML.safe_load 切换,属于包含破坏性变更的安全修复。源码层面,core/app/models/spree/log_entry.rb 定义了允许反序列化的核心白名单 CORE_PERMITTED_CLASSES(包含 ActiveMerchant::Billing::Response、ActiveSupport::TimeWithZone、ActiveSupport::HashWithIndifferentAccess、Time、ActiveSupport::TimeZone、Symbol),并提供了两个配置点(定义于 core/lib/spree/app_configuration.rb):
Spree.config do |config|
# 追加允许从序列化 YAML 反序列化的自定义类
config.log_entry_permitted_classes = ['MyClass']
# 是否允许 YAML 别名(默认 true;视数据来源可关闭以防实体膨胀攻击)
config.log_entry_allow_aliases = true
end
若你的应用或扩展会在支付日志(LogEntry)中序列化自定义对象,升级到对应版本后必须将相关类加入 log_entry_permitted_classes,否则读取历史日志时会抛出 DisallowedClass 异常。这一点正是 CHANGELOG 在 v2.11.17 的 Breaking changes 中特别标注的注意事项。
七、促销系统的双轨演进:Promotions vs Legacy Promotions
CHANGELOG 清晰地展现了促销架构从"单一系统"到"双轨并行"的演进:
- v4.4.0 之前:促销代码全部位于 Core,
Spree::Promotion与规则、动作耦合紧密; - v4.4.0:抽取为
solidus_legacy_promotions,Core 通过配置对象与 Null 配置保持解耦; - v4.5.0 - v4.8.0:新一代
solidus_promotions持续独立演进。
新促销系统的演进方向在近期版本中尤为清晰:
- 条件(Conditions)单一职责化:v4.7.0 的
Create single-responsibility conditions for products, taxons, and option values将原本混在一个类中的多个条件拆分为独立类; - 计算器(Calculators)能力增强:新增
PercentWithCap计算器(v4.6.0)、支持分数百分比(v4.7.0)、支持动态调整标签(v4.7.0)、TieredFlatRate/DistributedAmount/FlexiRate等计算器获得完整 YARD 文档与共享测试用例; - 配置扁平化:
Change promotion condition configuration to be flat(v4.7.0)、Deprecate promotion "level"(v4.7.0); - 内存化与性能:
Allow promotion conditions to work with in-memory line items(v4.7.0)、Preload adjustments in promotion recalculation to avoid an N+1(v4.8.0); - 行为修正:
Remove adjustments from cart orders when promotion is discarded(v4.8.0)、Only mark zero-amount promotion adjustments for destruction(v4.8.0)、Fix eligibility calculation in dry runs(v4.7.0)、First Order condition must not fail on canceled orders(v4.7.0)。
新促销引擎的核心模型位于 promotions/app/models/solidus_promotions/(Promotion、Benefit、Condition 等 70+ 文件),旧系统则在 legacy_promotions/app/models/spree/。若你的项目同时依赖两者,需注意 v4.8.0 中 Add privilege and category to legacy_promotions and promotion permission sets 这类权限集层面的对齐改动。
八、贯穿各版本的性能主题:N+1 消除与订单重算优化
从 v1.4.0 的内存化 OrderUpdater,到 v4.8.0 的大量预加载改动,CHANGELOG 始终把"订单重算正确性"与"查询性能"作为核心工程议题。近期具有代表性的条目包括:
Preload variants when building inventory units to avoid an N+1(v4.8.0);Preload variant and product when calculating taxes to avoid an N+1(v4.8.0);Eager load line item details on the admin order page to avoid N+1s(v4.8.0);Eager load associations in admin and API collection endpoints(v4.8.0);Avoid an N+1 loading stock on the admin products index(v4.8.0);Eager load variant stock on the products API index to avoid an N+1(v4.8.0);Improve Solidus Admin Orders Loading Performance/Improve Products loading performance(v4.8.0,Admin 端)。
升级到包含这些改动的版本后,建议用 Bullet 或数据库查询日志对比订单页、产品列表页与 API 索引端点的 SQL 数量,同时重点回归订单金额、税、促销折扣的计算结果——因为"减少查询"与"内存对象复用"类改动最容易在自定义扩展中暴露关联状态未同步的问题(正如 v1.4.0 的警告所提示)。
九、实践建议:如何围绕 CHANGELOG 制定升级路线
基于本文梳理,面向 Solidus 应用的升级决策可遵循以下路径:
- 定位当前版本与目标版本区间:在 CHANGELOG.md 中确认两个版本之间所有
## Solidus vX.Y.Z节与对应的Full Changelog; - 逐组件核对:按 Core / Admin / Backend / API / Promotions / Legacy Promotions / I18n 分节过滤,找出影响你所用功能的条目,特别关注标有 Major changes、Breaking changes、Removal 的段落;
- 先跑 v3.1+ 的官方升级流程:在 spree.rb 顶部设置
Spree.load_defaults('当前版本'),运行bin/rails g solidus:update预览默认值变化,逐个采纳新默认值(对应仓库实现见 core/lib/spree/core.rb); - 处理数据迁移任务:如
solidus:delete_prices_with_nil_amount(core/lib/tasks/solidus/delete_prices_with_nil_amount.rake),按 CHANGELOG 指示在迁移前执行; - 检查安全修复:确认目标版本已包含对应的 GHSA / CVE 修复,并按需配置
log_entry_permitted_classes与log_entry_allow_aliases; - 跟踪弃用警告:升级到 major 版本前,应用日志中的弃用警告必须清零(v3.0.0、v4.0.0 的破坏性变更均源于此);
- 重点回归:订单金额重算、促销 eligibility、库存分配、后台列表页与 API 端点查询性能、LogEntry 历史数据读取。
CHANGELOG 是 Solidus 升级过程中最可靠的"变更契约":它既记录了每个版本的"是什么",也通过 Major changes 章节回答了"为什么",更在关键位置给出了可直接复制的配置与命令。结合仓库源码(core/、promotions/、legacy_promotions/、admin/、storefront/)交叉验证,你就能在每次升级中做到心中有数、平滑过渡。