【技术笔记】AI Agent 项目 SUNA 部署：MSYS2 环境中 Python 版本从 3.12 降级至 3.11 的实操指南

【技术笔记】AI Agent 项目 SUNA 部署：MSYS2 环境中 Python 版本从 3.12 降级至 3.11 的实操指南

一、环境现状说明

当前时间：2025 年 6 月
MSYS2 默认只能安装的 Python 版本：Python 3.12
降级背景：因 AI Agent 项目 SUNA 的依赖组件需适配 Python 3.11 环境，需将 MSYS2 内置 Python 版本从 3.12 降级至 3.11。

二、Python 版本降级实施步骤

（一）核心思路与前置条件

降级原理：MSYS2 的 Python 版本与安装包版本强绑定，无法通过包管理工具直接降级，需通过重装旧版 MSYS2 安装包实现。
关键逻辑：选择未集成 Python 3.12 的 MSYS2 历史版本，确保其默认搭载 Python 3.11。

（二）操作流程详解

History for python - msys2/MSYS2-packages

• 1、查询 Python 3.11 适配的 MSYS2 版本区间

  • 查询依据：Python 官方支持周期显示，Python 3.11 的维护期为2023 年 2 月 13 日 —2024 年 4 月 24 日。
  • 适配版本范围：需下载此时间段内发布的 MSYS2 安装包，确保其默认支持的 Python 版本为 3.11。

---

• 2、获取旧版 MSYS2 旧版安装包

Index of /distrib/x86_64/

下载地址：访问 MSYS2 官方历史版本仓库（需替换为实际可访问的镜像站或官方地址）。

• 版本示例：选择2023 年 10 月 26 日发布的版本（文件命名格式通常为msys2-x86_64-<YYYYMMDD>.exe）。
• 下载验证：确认安装包大小、哈希值与官方记录一致，避免文件损坏或篡改。

---

• 3、安装旧版 MSYS2

  • 卸载现有环境（可选）：若需彻底清除旧配置，可先卸载当前 MSYS2（注意备份用户数据）。
  • 执行安装程序：
    • 双击下载的.exe文件，按向导提示完成安装（路径建议与原环境隔离，如C:\msys2-python311）。
    • 安装过程中取消勾选 “更新软件包” 选项，避免安装程序自动升级组件。
    • 比如以下载2023 年 10 月 26 日发布的版本为例：​​​​​​​

下载到本地之后安装： ​​​​​​​

这里是因为系统中已安装过新版的MSYS2 （适配python3.12）， 所以更改个根目录即可继续安装：

安装完保持默认则自动打开 UCRT64 终端窗口，表明已安装完成。 

关闭这个 UCRT64 终端。

• 4、安装python3.11和相关工具链

 

然后在开始菜单的快捷方式中打开 MSYS2 MINGW64 ：

在MSYS2 MINGW64终端 输入以下命令：

•  安装python

pacman -S mingw-w64-x86_64-python

我这里已经安装过了，所以再次运行命令会显示重装(--reinstalling)

 

 安装完成后输入“python”验证版本

python

• 预期输出：Python 3.11.x（x 为补丁版本号，如 3.11.6）。
• 若版本不符，需检查安装包是否在适配版本区间内，或尝试其他历史版本。

love@AI MINGW64 ~
$ python
Python 3.11.6 (main, Oct  3 2023, 09:12:56)  [GCC 13.2.0 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> 

从输出可以看到已经安装成python3.11.6版，目标基本达成。

但为了更好地搭建好开发环境，我们还需要安装一些工具链，以下是一些基础的，可以根据实际需要安装：

• 安装pip

pacman -S mingw-w64-x86_64-python-pip

安装 setuptools、wheel、virtualenv

• 配置基本开发环境

pacman -S --needed \mingw-w64-x86_64-toolchain \mingw-w64-x86_64-cmake \mingw-w64-x86_64-ninja \git wget unzip zip tar make

更多的工具链的安装请参考：

【笔记】MSYS2 的 MINGW64 环境 全面工具链-CSDN博客 
 

（三）环境迁移与依赖配置

• 手动迁移配置：如需复用原环境的软件包（如 MinGW 工具链、pip 依赖），可将原 MSYS2 目录下的usr文件夹部分文件复制到新环境（建议先通过pacman命令导出依赖列表后重新安装）。
• 更新包管理工具：在新环境终端执行：

  pacman -Syu --noconfirm  # 更新pacman仓库索引及基础组件
  

 

三、注意事项与风险提示

1. 兼容性限制：旧版 MSYS2 可能缺少部分新版系统组件，需根据项目依赖情况手动安装缺失的库（如 OpenSSL、libcurl 等）。
2. 数据备份：降级操作建议在空环境或备份后执行，避免覆盖重要项目文件。
3. 版本管理建议：可通过虚拟机或 Docker 容器隔离不同 Python 版本的 MSYS2 环境，便于多项目并行开发。

四、总结

通过重装历史版本 MSYS2 实现 Python 降级是当前最可靠的方案，核心在于精准匹配 Python 版本对应的安装包发布周期。操作时需严格验证安装包来源及版本信息，确保环境稳定适配项目需求。后续若需升级或降级 Python 版本，可重复此流程安装更高版本的 MSYS2 环境。