版本演进与升级
Spring Cloud Alibaba 版本号跟随 Spring Cloud Release Train，不等同于 Nacos、Sentinel 或 Seata 服务端版本。升级时必须把应用框架与所有中间件作为一组依赖检查。
当前版本线
截至 2026 年 8 月，官方 2025.x 文档给出的主要组合为：
| Spring Cloud Alibaba | Spring Cloud | Spring Boot | Nacos | Sentinel | Seata |
|---|---|---|---|---|---|
| 2025.1.0.0 | 2025.1.0 | 4.0.0 | 3.1.1 | 1.8.9 | 2.5.0 |
| 2025.0.0.0 | 2025.0.0 | 3.5.0 | 3.0.3 | 1.8.9 | 2.5.0 |
表格用于识别版本关系，不表示所有项目都应立即选择最新主线。Spring Boot 4 涉及 Java、Jakarta API 和三方库兼容性；既有项目通常先选择其依赖生态完整支持的版本线。
旧写法迁移
| 旧写法 | 现代方案 |
|---|---|
Ribbon、NFLoadBalancerRuleClassName | Spring Cloud LoadBalancer；需要时启用 Nacos LoadBalancer 集成 |
bootstrap.yml 接入 Nacos Config | application.yml 中使用 spring.config.import=nacos: |
隐式加载 ${spring.application.name}-${profile} | 显式声明每个 Nacos Config Import |
shared-configs、extension-configs | 多条 spring.config.import |
| 手工排除旧 Seata Starter 再强制指定 1.4.x | 使用兼容矩阵和 BOM 管理的 Starter |
feign.sentinel.enabled | 新版通常使用 spring.cloud.openfeign.sentinel.enabled，以目标版本元数据为准 |
| 默认账号和内网裸奔 | 启用认证、访问控制、Secret 注入和审计 |
升级步骤
- 盘点 JDK、Spring Boot、Spring Cloud、Spring Cloud Alibaba、Nacos Client/Server、Sentinel、Seata 和数据库驱动。
- 选择官方明确列出的版本组合，不在 BOM 之外单独覆盖传递依赖，除非已验证兼容性与安全修复。
- 使用
mvn dependency:tree检查 Spring、Netty、gRPC、Jackson、Nacos Client 和 Seata Client 冲突。 - 先升级基础设施测试集群，再验证旧客户端兼容窗口。
- 把 Nacos Bootstrap 配置迁移到 Config Data Import，逐项验证配置来源、刷新和失败策略。
- 把 Ribbon 规则迁移到 Spring Cloud LoadBalancer，验证实例筛选、权重、Cluster 和 IPv4/IPv6。
- 回归 Sentinel Resource 名称、OpenFeign Fallback、规则数据源、Dashboard 与熔断指标。
- 回归 Seata 全局事务、Undo Log、SQL 支持、TC Session Store、超时、重试和故障恢复。
- 做灰度发布，监控注册实例、配置监听、限流、熔断、事务回滚和端到端业务指标。
Spring Boot 4 边界
进入 Spring Cloud Alibaba 2025.1.x 意味着同时进入 Spring Boot 4 与 Spring Cloud 2025.1.x。升级前至少检查：
- 项目要求的 JDK 基线以及构建、运行镜像是否一致。
- Jakarta 包名、Servlet 容器和 Spring Security 配置变化。
- Spring Cloud Gateway、OpenFeign、LoadBalancer 和 Actuator 端点变化。
- 数据库驱动、连接池、序列化、Tracing Agent 和测试框架兼容性。
- 自研 Starter 是否依赖已经移除或改变的 Spring Boot 自动配置 SPI。
不应只把 BOM 版本改成 2025.1.0.0 后直接上线。