AI Agent 项目 SUNA 部署环境搭建 - 基于 MSYS2 的 Poetry+Python3.11 虚拟环境

#工作记录

一、环境约束

1. 核心限制：使用 旧版 MSYS2 的 MINGW64 环境，禁止升级 MSYS2（否则 Python 会自动升级到 3.12，导致项目依赖安装失败）。
2. 目标 Python 版本：Python 3.11

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

二、工具链与依赖安装（MSYS2 终端执行）

1. 基础 Python 环境

安装 Python 本体和 pip：

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

验证：运行 python 进入交互环境，确认版本为 3.11.6：

python

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.
>>> exit()

2. 基础开发工具链

安装编译、构建工具（toolchain、CMake、Ninja）和基础命令行工具（git、wget 等）：

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

3. Python 依赖库

安装 Wheel（包构建）、图像编解码依赖（libjpeg-turbo、freetype）：

pacman -S mingw-w64-x86_64-python-wheel \  mingw-w64-x86_64-libjpeg-turbo  \  mingw-w64-x86_64-freetype  

4. Poetry 包管理器

安装 Poetry：

pacman -S mingw-w64-x86_64-python-poetry  

5. GTK 相关依赖

pacman -S mingw-w64-x86_64-gtk3  
pacman -S mingw-w64-x86_64-python-pycairo  
pacman -S mingw-w64-x86_64-python-gobject  

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

 

三、创建Poetry+Python3.11 虚拟环境

【笔记】离个大谱！彻底解决Windows系统部署开源AI Agent项目SUNA的Frontend前端安装GTK库的问题_windows安装gtk-CSDN博客

1. 用PyCharm打开项目创建Poetry虚拟环境

路径选择 MSYS2 的安装路径。请参照上图。

2. 打开终端激活虚拟环境

打开IDE的终端自动激活并进入Poetry虚拟环境：

# 终端前缀显示虚拟环境名（如：(test2-py3.11)）

3. 版本与路径验证

• Python 版本：

  

  python  
  # 预期：Python 3.11.6 (main, Oct  3 2023, 09:12:56)  [GCC 13.2.0 64 bit (AMD64)] on win32  
  

• Poetry 版本：

  

  poetry -V  
  # 预期：Poetry (version 1.6.1)  
  

• 虚拟环境路径：

  

  which python  
  # 预期：/f/PythonProjects/test2/.venv/bin/python （虚拟环境内的Python）  
  

四、IDE 配置参考（以 PyCharm 为例）

添加解释器时，指定：

• 基础 Python：D:\msys64\mingw64\bin\python.exe（MSYS2 内的 Python 3.11）
• Poetry 路径：D:\msys64\mingw64\bin\poetry.exe
  （参考截图配置，确保 IDE 识别 MSYS2 环境的工具链）

关键注意事项

1. 终端环境：所有命令需在 MSYS2 的 MINGW64 终端 执行，避免系统 CMD/PowerShell 的环境冲突。
2. 版本锁死：若误升级 MSYS2 导致 Python 版本变化，需重新安装 Python 3.11 并修复依赖，建议严格遵循环境约束。

以上步骤确保基于 MSYS2 的 Poetry+Python3.11 虚拟环境稳定运行，支撑 SUNA 项目部署。

关于 SUNA 部署的其他问题排查，请移步往期笔记。