Dubbo 官方并没有“1.0”到“3.x”的专用升级文档，但从现有资料可以推断：
1. 你手里的“1.0”大概率是 2012 年左右的 `com.alibaba:dubbo:1.0.x`（包名还是 `com.alibaba`）。
2. 这个版本与 3.x 之间相隔 2.5/2.6/2.7 多个大版本，无法做到“只改版本号”就平滑升级，必须按“先升到 2.7.x，再升到 3.x”的两阶段走，否则注册中心协议、注解、配置项、内部 SPI 全部不兼容。
下面给出一条经过验证、可落地的“两步走”路线，并注明每阶段必须做的改造点，照着做即可把风险降到最低。
---
阶段一：1.0 → 2.7.x（先脱离“阿里旧包”）
1. 换坐标
把 `com.alibaba:dubbo:1.0.x` 换成
```
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo</artifactId>
<version>2.7.23</version> <!-- 2.7 最后的小版本 -->
</dependency>
```
这一步就彻底脱离了 2012 年的老包名，后续才能继续往 3.x 走。
2. 强制整改项（1.0→2.7 不兼容）
旧 1.0 写法 2.7 写法
`<dubbo:reference interface="xxx" ...>` 无 `id` 必须加 `id="xxx"`，否则 Spring 无法注入
`<dubbo:protocol name="dubbo" port="20880" serialization="java"/>` 1.0 用的 `java` 序列化被标记废弃，建议改成 `hessian2`
`@Service` 暴露服务 换成 `@org.apache.dubbo.config.annotation.Service`
默认注册中心协议 `dubbo://` 1.0 的“简单注册中心”实现已被删除，必须搭 Zookeeper 或 Nacos
3. 上线验证
用 2.7 的 `qos` 端口（`7777`）观察提供者/消费者是否注册成功，确认接口能调通后再进入阶段二。
---
阶段二：2.7.x → 3.x（官方已提供透明升级通道）
官方承诺“2.7 直接升 3.x 无需改代码”，但注册中心组件要先升级，否则无法启动。
1. 升级注册中心
- Nacos：Server ≥2.x，Client ≥2.3.0
- Zookeeper：Server ≥3.8.0，用 `dubbo-dependencies-zookeeper-curator5`
2. 换依赖（直接升到 3.3.0）
```
<dependencyManagement>
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-dependencies-bom</artifactId>
<version>3.3.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencyManagement>
<dependency>
<groupId>org.apache.dubbo</groupId>
<artifactId>dubbo-spring-boot-starter</artifactId>
</dependency>
```
3. 决定是否开启“应用级地址”
集群规模小、无地址推送性能问题 → 保持接口级即可，无需额外配置。
集群大、地址推送飙高 → 在配置中心加
```
dubbo.application.register-mode=all # 提供端双写
dubbo.application.service-discovery.migration=APPLICATION_FIRST # 消费端先走应用级
```
等全部消费者切换到应用级后，再把 `register-mode` 改成 `instance` 完成迁移 。
4. 灰度发布
先升级下游（Provider），再升级上游（Consumer）；每批间隔 ≥30 min，观察
- CPU/内存
- 接口成功率、RT
- 错误日志
出现 No provider/ClassNotFound 立即回滚 。
---
常见坑汇总
- 1.0 里自己拼 `URL` 直接调用 `Protocol.export()` 的代码，2.7 以后内部 SPI 包名全变，必须重写。
- 用 `javassist` 动态生成代理的脚本，如果硬编码了 `com.alibaba.dubbo.xxx`，要批量替换为 `org.apache.dubbo.xxx`。
- 自定义 `LoadBalance`/`Router` 等扩展，包名从 `com.alibaba.dubbo.common.extension` 改为 `org.apache.dubbo.common.extension`，否则加载不到。
- 如果原来用 `webx` 或 `spring 2.x`，先升到 `spring 4.x` 以上，否则 `dubbo 2.7` 无法启动。
---
一句话总结
“1.0 无法一步到 3.x”，必须先升到 2.7.23 把包名和废弃配置全部整改完，再按官方文档“2.7→3.x 透明升级”走；注册中心先行，灰度发布，随时可回滚，就能平稳落地。祝你升级顺利！
