文档中心

火山引擎SDK

SDK 更新政策

一、版本管理规范

1.1 版本号规则

火山引擎 SDK（Go SDK 除外）遵循语义化版本（Semantic Versioning, SemVer）规范，版本号格式为 X.Y.Z：

主版本号 X：引入不兼容的 API 变更（Breaking Changes）或底层架构重大调整时递增

次版本号 Y：引入向后兼容的新功能（如支持新的云服务或新特性）时递增

修订号 Z：进行向后兼容的缺陷修复或安全补丁时递增

示例：从版本 1.3.2 升级到 1.4.0 表示新增了向后兼容的功能；而从 1.x 升级到 2.0.0 则表示存在不兼容的变更，需参考迁移指南进行适配。

1.2 主版本生命周期

每个 SDK 主版本都有明确的生命周期阶段，确保开发者能合理规划版本切换：

阶段	持续时间	说明
开发者预览	不定	早期开发 / Beta 测试状态，不提供正式技术支持，可能引入不兼容变更。严禁用于生产环境。
正式可用（GA）	≥ 24 个月	SDK 达到稳定状态。提供全量功能更新，包括新服务支持、API 增强、Bug 修复与安全补丁。
维护公告	≥ 6 个月	在进入维护模式前发布正式公告。此阶段 SDK 仍处于全量支持状态。
维护阶段	默认 12 个月	仅修复严重 Bug 和高危安全漏洞。不再提供新服务支持或新 Region 上线。
终止支持（EoS）	—	该主版本正式退役，不再接收任何更新。历史版本仍保留在公共包管理器中。

二、更新与升级政策

2.1 更新频率

功能更新：随云产品 API 发布节奏持续更新，通常每周至每两周发布一个新版本

安全补丁：发现高危漏洞后 72 小时内发布紧急修复

Bug 修复：根据严重程度在 1-4 周内修复并发布

2.2 兼容性承诺

核心承诺：在同一主版本内，我们确保向后兼容。次版本和修订版本的升级不会破坏现有业务代码。

以下变更被视为兼容性变更（不提升主版本号）：

新增可选参数

新增响应字段

新增服务 API 方法

修复文档中未承诺的行为差异

性能优化

以下变更被视为不兼容变更（需提升主版本号）：

删除或重命名公开 API 方法

修改参数类型或必填性

修改方法签名

删除响应字段

修改错误码含义

2.3 升级建议

我们强烈建议用户始终将 SDK 保持在最新稳定版本，以获得：

最新的云服务 API 支持

安全漏洞修复

性能优化和稳定性提升

新功能特性

三、运行时支持基线

SDK 运行在特定的底层环境之上，包括语言运行时、操作系统及第三方库。我们的基本政策是：在底层依赖社区宣布 EOL 后，继续提供至少 6 个月的支持缓冲期。

3.1 各语言运行时最低版本

语言	最低支持版本	推荐版本	废弃缓冲原则
Go	开发者当前使用的主流版本中较老的一个（当前是：1.18）。	最新 Go GA 版本（如 Go 1.24+）	社区 EOL 后保留 6-12 个月缓冲
Java	Java 8 (LTS)	Java 17 或 Java 21 LTS	LTS EoL 后继续支持至少 12 个月
Python	Python 3.10（仅支持 PSF 维护窗口内版本）	Python 3.12 或 3.13+	EoL 后继续支持至少 12 个月
PHP	PHP 8.1+	PHP 8.2 或 8.3+	官方安全支持结束后继续支持 12 个月
Node.js	Node.js 20+（Active LTS）	Node.js 22 或 24 LTS	LTS EoL 后保留 8-12 个月缓冲

3.2 运行时版本提升决策原则

我们在决定提升最低运行时版本时，会综合评估以下因素：

社区状态：底层运行时距离 EOL 的时间

用户占比：仍在使用旧版本的用户比例

安全与合规：是否存在无法修复的安全漏洞

维护成本：维护旧版本兼容性的技术成本

四、废弃与迁移

4.1 废弃流程

当 SDK 功能、参数或版本需要废弃时，我们遵循以下标准流程：

发布公告：通过官方文档、SDK中心通知受影响的开发者。

缓冲期：至少保留 6 个月的废弃缓冲期，确保开发者有充足时间迁移。

正式移除：在下一个主版本中移除废弃的功能。

4.2 迁移支持

对于主版本升级，我们提供：

迁移指南文档：详细说明不兼容变更及迁移步骤

代码示例：新版本的完整代码示例

迁移工具：部分语言提供自动化迁移脚本

技术支持：通过工单提供迁移咨询

五、沟通与通知渠道

我们通过以下渠道向开发者传递 SDK 生命周期变更信息：

官方文档：在火山引擎 SDK 官方文档和 GitHub README 中更新版本支持信息。

SDK中心：在火山引擎 SDK中心站点的公告中更新版本支持信息。

最近更新时间：2026.06.10 14:14:35

这个页面对您有帮助吗？

有用

无用