GitHub Actions Runner 镜像升级导致 .NET 工作流兼容性问题分析

GitHub Actions 作为主流的 CI/CD 平台，其预构建的 Runner 镜像为开发者提供了开箱即用的开发环境。然而，近期 Ubuntu 基础镜像从 22.04 升级到 24.04 版本后，部分 .NET 开发者的工作流出现了兼容性问题，这值得广大开发者关注。

问题背景

当 GitHub Actions 的 ubuntu-latest 标签指向 24.04 版本后，主要出现了两类典型问题：

1. SDK 版本不匹配：Ubuntu 24.04 预装的 .NET SDK 版本（8.0.112）与项目 global.json 中指定的版本不一致，导致构建失败。而 Ubuntu 22.04 预装的 8.0.405 版本则能正常工作。

2. 基础工具缺失：sqlcmd 等常用数据库工具在 24.04 镜像中未被包含，影响了数据库相关操作。

技术原理分析

1. .NET SDK 版本管理机制

global.json 文件是 .NET 项目的版本控制文件，它会锁定项目所需的 SDK 版本。当运行环境中的 SDK 版本与 global.json 不匹配时，.NET CLI 会拒绝执行构建命令，这是设计上的安全机制。

Ubuntu 不同版本通过不同的软件源提供 .NET 包：

• 22.04 使用较旧的软件源，提供 8.0.405 版本
• 24.04 使用更新的软件源，但只提供 8.0.112 版本

这种差异源于 Ubuntu 各版本维护周期的不同，新版本往往会包含更新的软件包。

2. 基础工具集变化

Ubuntu 24.04 作为新版本，对预装软件进行了调整：

• 移除了部分旧版工具
• 改变了某些工具的安装方式
• 可能使用了不同的软件包管理器配置

解决方案建议

临时解决方案

明确指定 Runner 镜像版本：

runs-on: ubuntu-22.04

长期解决方案

1. 使用 setup-dotnet 动作：

- uses: actions/setup-dotnet@v3
  with:
    dotnet-version: '8.0.x'

2. 显式安装缺失工具： 对于 sqlcmd 等工具，可以在工作流中添加安装步骤：

- run: sudo apt-get update && sudo apt-get install -y mssql-tools

3. 更新项目配置： 如果项目允许，可以更新 global.json 文件以匹配新环境中的 SDK 版本。

最佳实践

1. 固定基础镜像版本：生产环境工作流应明确指定 Runner 镜像版本，避免自动升级带来的意外。

2. 使用版本管理工具：对于 .NET 项目，推荐使用 setup-dotnet 动作而非依赖预装版本。

3. 完整声明依赖：将所有工具依赖明确写入工作流文件，不要依赖 Runner 镜像的预装内容。

4. 建立兼容性测试：在 CI 流水线中添加基础环境检查步骤，提前发现问题。

总结

Runner 镜像升级是持续交付过程中的常见挑战。开发者应当：

• 了解不同镜像版本间的差异
• 明确声明所有环境依赖
• 建立完善的版本控制机制
• 定期更新和测试工作流配置

通过采取这些措施，可以确保 CI/CD 流程的稳定性和可靠性，避免因基础环境变化导致的构建失败。