Pulumi Python SDK 处理预发布版本包下载问题的技术解析

在Pulumi项目中，当使用Git源插件时，开发者可能会遇到预发布版本包下载异常的问题。这个问题主要出现在版本号包含Git提交哈希的特殊情况下。

问题背景

Pulumi Python SDK在处理Git源插件时，会生成包含特定版本号的setup.py文件。当版本号采用0.0.0-x7d758cbba9f1d8d55438d7de39a84e276222a46a这样的格式时（其中x7d...是Git提交哈希），系统会将其转换为PEP440兼容的格式0.0.0+x7d758cbba9f1d8d55438d7de39a84e276222a46a。

问题本质

问题的核心在于版本号的转换过程中出现了不对称性：

1. 从semver到PEP440的转换是正确的，将预发布标识符（-x...）转换为本地版本标识符（+x...）
2. 但反向转换缺失，导致引擎接收到的版本号丢失了关键的提交哈希信息

这种不对称性导致引擎尝试加载0.0.0版本而非完整的带有哈希的版本，最终导致插件加载失败。

技术影响

这个问题会影响所有使用Git源插件并指定特定提交哈希的Python项目。例如，当开发者运行类似命令时：

pulumi package add github.com/mikhailshilkov/comp-as-comp/go@7d758cbba9f1d8d55438d7de39a84e276222a46a

系统无法正确识别和加载指定提交版本的插件。

解决方案

修复方案需要确保版本号转换的双向一致性：

1. 在将版本号发送给引擎前，需要将PEP440本地版本标识符（+x...）转换回semver预发布标识符（-x...）
2. 保持版本号转换的对称性，确保引擎能获取完整的版本信息

最佳实践

对于使用Pulumi Python SDK的开发者，建议：

1. 确保使用最新版本的Pulumi工具链
2. 对于Git源插件，明确指定完整的版本标识
3. 在遇到插件加载问题时，检查版本号转换是否正确

这个问题已在Pulumi v3.148.0版本中得到修复，开发者升级后即可解决相关问题。