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

原创已于 2025-06-01 09:29:15 修改 · 1k 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#笔记 #windows #人工智能 #开源 #前端 #python

于 2025-06-01 02:22:07 首次发布

GitHub等开源项目部署实战秘籍同时被 3 个专栏收录

82 篇文章

订阅专栏

Windows 部署 AI Agent - Suna

51 篇文章

订阅专栏

PyCharm

41 篇文章

订阅专栏

#工作记录

Suna - Open Source Generalist AI Agent

一、问题描述

在尝试于 Windows 系统 上部署一个基于 Python 的开源 AI Agent 项目（例如 SUNA）时，开发者常常会遇到 Frontend 前端无法正常安装或运行的问题。其中，最典型的错误是：

报错摘录：

第8步

Step 8/8: Installing dependencies
==================================================

ℹ️  Installing required dependencies...
ℹ️  Installing frontend dependencies...
npm warn cleanup Failed to remove some directories [
npm warn cleanup   [
npm warn cleanup     '\\\\?\\F:\\PythonProjects\\suna\\frontend\\node_modules\\next',
npm warn cleanup     [Error: EPERM: operation not permitted, rmdir 'F:\PythonProjects\suna\frontend\node_modules\next\dist\client'] {
npm warn cleanup       errno: -4048,
npm warn cleanup       code: 'EPERM',
npm warn cleanup       syscall: 'rmdir',
npm warn cleanup       path: 'F:\\PythonProjects\\suna\\frontend\\node_modules\\next\\dist\\client'                                                                                                                                                                                                             
npm warn cleanup     }
npm warn cleanup   ],
npm warn cleanup   [
npm warn cleanup     'F:\\PythonProjects\\suna\\frontend\\node_modules\\next',
npm warn cleanup     [Error: EPERM: operation not permitted, rmdir 'F:\PythonProjects\suna\frontend\node_modules\next\dist\esm\client\components\react-dev-overlay'] {
npm warn cleanup       errno: -4048,
npm warn cleanup       code: 'EPERM',
npm warn cleanup       syscall: 'rmdir',
npm warn cleanup       path: 'F:\\PythonProjects\\suna\\frontend\\node_modules\\next\\dist\\esm\\client\\components\\react-dev-overlay'                                                                                                                                                                         
npm warn cleanup     }
npm warn cleanup   ]
npm warn cleanup ]
npm error code 1                                                                                                                                                                                                                                                                                                
npm error path F:\PythonProjects\suna\frontend\node_modules\canvas
npm error command failed
npm error command C:\WINDOWS\system32\cmd.exe /d /s /c prebuild-install -r napi || node-gyp rebuild
npm error Warning: Missing input files:
npm error C:\GTK\bin\libgmodule-2.0-0.dll
npm error C:\GTK\bin\libpangowin32-1.0-0.dll
npm error C:\GTK\bin\libfreetype-6.dll
npm error C:\GTK\bin\libgobject-2.0-0.dll
npm error C:\GTK\bin\libpango-1.0-0.dll
npm error C:\GTK\bin\libpangoft2-1.0-0.dll
npm error C:\GTK\bin\libcairo-2.dll
npm error C:\GTK\bin\libglib-2.0-0.dll
npm error C:\GTK\bin\libintl-8.dll
npm error C:\GTK\bin\libpng14-14.dll
npm error C:\GTK\bin\libgthread-2.0-0.dll
npm error C:\GTK\bin\libfontconfig-1.dll
npm error C:\GTK\bin\libpangocairo-1.0-0.dll
npm error C:\GTK\bin\zlib1.dll
npm error C:\GTK\bin\libexpat-1.dll
npm error                                                                                                                                                                                                                                                                                                       
npm error   Backend.cc
npm error F:\PythonProjects\suna\frontend\node_modules\canvas\src\backend\Backend.h(3,10): error C1083: 无法打开包括文件: “cairo.h”: No such file or directory [F:\PythonProjects\suna\frontend\node_modules\canvas\build\canvas.vcxproj]
npm error   (编译源文件“../src/backend/Backend.cc”)
npm error prebuild-install warn install read ECONNRESET
npm error gyp info it worked if it ends with ok
npm error gyp info using node-gyp@11.0.0
npm error gyp info using node@22.16.0 | win32 | x64
npm error gyp info find Python using Python version 3.12.9 found at "C:\msys64\mingw64\bin\python3.exe"
npm error gyp info find VS using VS2022 (17.12.36106.13) found at:
npm error gyp info find VS "D:\Program Files\Microsoft Visual Studio\2022\Professional"
npm error gyp info find VS run with --verbose for detailed information
npm error gyp info spawn C:\msys64\mingw64\bin\python3.exe
npm error gyp info spawn args [
npm error gyp info spawn args 'C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp\\gyp\\gyp_main.py',
npm error gyp info spawn args 'binding.gyp',
npm error gyp info spawn args '-f',
npm error gyp info spawn args 'msvs',
npm error gyp info spawn args '-I',
npm error gyp info spawn args 'F:\\PythonProjects\\suna\\frontend\\node_modules\\canvas\\build\\config.gypi',
npm error gyp info spawn args '-I',
npm error gyp info spawn args 'C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp\\addon.gypi',
npm error gyp info spawn args '-I',
npm error gyp info spawn args 'C:\\Users\\love\\AppData\\Local\\node-gyp\\Cache\\22.16.0\\include\\node\\common.gypi',
npm error gyp info spawn args '-Dlibrary=shared_library',
npm error gyp info spawn args '-Dvisibility=default',
npm error gyp info spawn args '-Dnode_root_dir=C:\\Users\\love\\AppData\\Local\\node-gyp\\Cache\\22.16.0',
npm error gyp info spawn args '-Dnode_gyp_dir=C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp',
npm error gyp info spawn args '-Dnode_lib_file=C:\\\\Users\\\\love\\\\AppData\\\\Local\\\\node-gyp\\\\Cache\\\\22.16.0\\\\<(target_arch)\\\\node.lib',
npm error gyp info spawn args '-Dmodule_root_dir=F:\\PythonProjects\\suna\\frontend\\node_modules\\canvas',
npm error gyp info spawn args '-Dnode_engine=v8',
npm error gyp info spawn args '--depth=.',
npm error gyp info spawn args '--no-parallel',
npm error gyp info spawn args '--generator-output',
npm error gyp info spawn args 'F:\\PythonProjects\\suna\\frontend\\node_modules\\canvas\\build',
npm error gyp info spawn args '-Goutput_dir=.'
npm error gyp info spawn args ]
npm error gyp info spawn D:\Program Files\Microsoft Visual Studio\2022\Professional\MSBuild\Current\Bin\MSBuild.exe
npm error gyp info spawn args [
npm error gyp info spawn args 'build\\binding.sln',
npm error gyp info spawn args '/clp:Verbosity=minimal',
npm error gyp info spawn args '/nologo',
npm error gyp info spawn args '/p:Configuration=Release;Platform=x64'
npm error gyp info spawn args ]
npm error gyp ERR! build error
npm error gyp ERR! stack Error: `D:\Program Files\Microsoft Visual Studio\2022\Professional\MSBuild\Current\Bin\MSBuild.exe` failed with exit code: 1
npm error gyp ERR! stack at ChildProcess.<anonymous> (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\build.js:216:23)
npm error gyp ERR! stack at ChildProcess.emit (node:events:518:28)
npm error gyp ERR! stack at ChildProcess._handle.onexit (node:internal/child_process:293:12)
npm error gyp ERR! System Windows_NT 10.0.27868
npm error gyp ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild"
npm error gyp ERR! cwd F:\PythonProjects\suna\frontend\node_modules\canvas
npm error gyp ERR! node -v v22.16.0
npm error gyp ERR! node-gyp -v v11.0.0
npm error gyp ERR! not ok
npm error A complete log of this run can be found in: C:\Users\love\AppData\Local\npm-cache\_logs\2025-05-30T15_19_00_254Z-debug-0.log
❌  Failed to install dependencies: Command '['npm', 'install']' returned non-zero exit status 1.

npm error C:\GTK\bin\libgmodule-2.0-0.dll
npm error C:\GTK\bin\libpangowin32-1.0-0.dll
npm error C:\GTK\bin\libfreetype-6.dll
npm error C:\GTK\bin\libgobject-2.0-0.dll
npm error C:\GTK\bin\libpango-1.0-0.dll
npm error C:\GTK\bin\libpangoft2-1.0-0.dll
npm error C:\GTK\bin\libcairo-2.dll
npm error C:\GTK\bin\libglib-2.0-0.dll
npm error C:\GTK\bin\libintl-8.dll
npm error C:\GTK\bin\libpng14-14.dll
npm error C:\GTK\bin\libgthread-2.0-0.dll
npm error C:\GTK\bin\libfontconfig-1.dll
npm error C:\GTK\bin\libpangocairo-1.0-0.dll
npm error C:\GTK\bin\zlib1.dll
npm error C:\GTK\bin\libexpat-1.dll

这个错误通常出现在使用依赖于 GTK（GIMP Toolkit） 的库（如 PyGObject、PyCairo 等）时，尤其是在尝试运行前端 GUI 或某些渲染模块时。

由于 Windows 并不原生支持 GTK 库，且传统的 Python 安装方式（如通过 pip 和 venv）难以正确链接 GTK 相关 DLL 文件，导致很多开发者在此步骤卡住。

二、报错原因分析

1. GTK 库缺失

GTK 是一套用于图形界面开发的跨平台库，常见于 Linux 桌面环境。Windows 上默认没有安装这些库，而许多基于 Python 的 GUI 工具链（如 PyGObject、PyCairo、gi.repository 等）需要调用这些 C/C++ 编写的本地库。

2. 虚拟环境配置不当

当使用标准的 venv 或 pipenv 创建虚拟环境时，它们并不能自动将 GTK 的 DLLs 包含进去。即使手动复制了 DLL 文件，也可能因为路径配置错误或版本不匹配而导致程序崩溃。

3. Poetry + Windows 默认 Python 环境限制

Poetry 本身是一个优秀的 Python 依赖管理工具，但在 Windows 上如果使用的 Python 解释器不是通过 MSYS2 / MINGW64 构建的，就很难正确加载 GTK 相关库。这使得基于 GTK 的 Python 模块无法被正确识别和导入。

三、解决方案：使用 MSYS2（MINGW64）+ Poetry 虚拟环境绕过GTK库缺失问题

✅ 思路核心：

利用 MSYS2 环境下的 MINGW64 工具链 提供完整的 GTK 支持，并结合 Poetry 虚拟环境 来构建一个兼容性更强、能直接访问 GTK 库的 Python 开发环境。

四、详细操作步骤

第一步：安装 MSYS2 和 MINGW64

下载并安装 MSYS2。
启动 MSYS2 MINGW 64-bit 终端。
更新系统包：
```
pacman -Syu
```
（更新完成后可能需要重启终端）
```
pacman -Su
```

第二步：安装 Python 和 Poetry

安装 Python（MINGW64 版本）：

如果未安装，请运行以下命令安装python：

pacman -S mingw-w64-x86_64-python

安装 Poetry：

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

验证安装：
```
python --version
poetry --version
```

第三步：安装 GTK3 及相关依赖

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

这样就可以确保所有 GTK 相关的库都被正确安装到 MINGW64 环境中。

第四步：创建 Poetry 虚拟环境

第五步：安装并运行 SUNA 前端

安装前端依赖（进入frontend 文件夹下运行 npm install）：

npm install

或重新开始部署：

python setup.py '--admin'

输出摘录如下：

……

Step 8/8: Installing dependencies
==================================================

ℹ️  Installing required dependencies...
ℹ️  Installing frontend dependencies...

up to date in 4s

292 packages are looking for funding
  run `npm fund` for details
✅  Frontend dependencies installed successfully
ℹ️  Locking dependencies...
Resolving dependencies... (0.9s)
ℹ️  Installing backend dependencies...
Installing dependencies from lock file

Package operations: 126 installs, 0 updates, 0 removals

  - Installing attrs (25.3.0)
  - Installing certifi (2024.2.2)
  - Installing charset-normalizer (3.4.1)
  - Installing colorama (0.4.6)
  - Installing frozenlist (1.5.0)
  - Installing h11 (0.14.0)
  - Installing hpack (4.1.0)
  - Installing hyperframe (6.1.0)
  - Installing idna (3.10)
  - Installing iniconfig (2.1.0)
  - Installing multidict (6.4.3)
  - Installing packaging (24.1)
  - Installing pluggy (1.5.0)
  - Installing propcache (0.3.1)
  - Installing rpds-py (0.24.0)
  - Installing six (1.17.0)
  - Installing sniffio (1.3.1)
  - Installing typing-extensions (4.13.2)
  - Installing urllib3 (2.4.0)
  - Installing aiohappyeyeballs (2.6.1)
  - Installing aiosignal (1.3.2)
  - Installing annotated-types (0.7.0)
  - Installing anyio (4.9.0)
  - Installing filelock (3.18.0)
  - Installing fsspec (2025.3.2)
  - Installing h2 (4.2.0)
  - Installing httpcore (1.0.8)
  - Installing jmespath (1.0.1)
  - Installing pydantic-core (2.33.1)
  - Installing pytest (8.3.3)
  - Installing python-dateutil (2.9.0.post0)
  - Installing pyyaml (6.0.2)
  - Installing referencing (0.36.2)
  - Installing requests (2.32.3)
  - Installing setuptools (75.3.0)
  - Installing tqdm (4.67.1)
  - Installing typing-inspection (0.4.0)
  - Installing yarl (1.19.0)
  - Installing aiohttp (3.11.16)
  - Installing automat (24.8.1)
  - Installing botocore (1.37.34)
  - Installing click (8.1.7)
  - Installing constantly (23.10.4)
  - Installing deprecation (2.1.0)
  - Installing distro (1.9.0)
  - Installing httpx (0.28.1)
  - Installing huggingface-hub (0.30.2)
  - Installing hyperlink (21.0.0)
  - Installing incremental (24.7.2)
  - Installing jiter (0.9.0)
  - Installing jsonschema-specifications (2024.10.1)
  - Installing markupsafe (3.0.2)
  - Installing marshmallow (3.26.1)
  - Installing numpy (2.2.4)
  - Installing protobuf (5.29.4)
  - Installing pydantic (2.11.3)
  - Installing pyjwt (2.10.1)
  - Installing pytest-mock (3.14.0)
  - Installing python-dotenv (1.0.1)
  - Installing pytz (2025.2)
  - Installing regex (2024.11.6)
  - Installing starlette (0.36.3)
  - Installing strenum (0.4.15)
  - Installing tzdata (2025.2)
  - Installing wcwidth (0.2.13)
  - Installing websockets (14.2)
  - Installing wrapt (1.17.2)
  - Installing zipp (3.21.0)
  - Installing zope-interface (7.2)
  - Installing backoff (2.2.1)
  - Installing daytona-api-client (0.16.0)
  - Installing deprecated (1.2.18)
  - Installing e2b (1.3.4)
  - Installing entrypoints (0.4)
  - Installing environs (9.5.0)
  - Installing fastapi (0.110.0)
  - Installing gotrue (2.12.0)
  - Installing httpx-sse (0.4.0)
  - Installing importlib-metadata (8.6.1)
  - Installing jinja2 (3.1.6)
  - Installing jsonschema (4.23.0)
  - Installing nodeenv (1.9.1)
  - Installing openai (1.74.0)
  - Installing pandas (2.2.3)
  - Installing pillow (10.4.0)
  - Installing postgrest (1.0.1)
  - Installing prometheus-client (0.21.1)
  - Installing prompt-toolkit (3.0.36)
  - Installing pycryptodomex (3.22.0)
  - Installing pydantic-settings (2.9.1)
  - Installing python-multipart (0.0.20)
  - Installing realtime (2.4.2)
  - Installing s3transfer (0.11.4)
  - Installing sse-starlette (2.3.6)
  - Installing storage3 (0.11.3)
  - Installing supafunc (0.9.4)
  - Installing tiktoken (0.9.0)
  - Installing tokenizers (0.21.1)
  - Installing tomlkit (0.13.2)
  - Installing toolz (1.0.0)
  - Installing twisted (24.11.0)
  - Installing uvicorn (0.27.1)
  - Installing altair (4.2.2)
  - Installing asyncio (3.4.3)
  - Installing boto3 (1.37.34)
  - Installing daytona-sdk (0.14.0)
  - Installing dramatiq (1.17.1)
  - Installing e2b-code-interpreter (1.2.0)
  - Installing exa-py (1.12.0)
  - Installing langfuse (2.60.5)
  - Installing litellm (1.66.1)
  - Installing mcp (1.9.2)
  - Installing nest-asyncio (1.6.0)
  - Installing pika (1.3.2)
  - Installing prisma (0.15.0)
  - Installing pytesseract (0.3.13)
  - Installing pytest-asyncio (0.24.0)
  - Installing python-ripgrep (0.0.6)
  - Installing questionary (2.0.1)
  - Installing redis (5.2.1)
  - Installing sentry-sdk (2.29.1)
  - Installing stripe (12.0.1)
  - Installing supabase (2.15.0)
  - Installing tavily-python (0.5.4)
  - Installing upstash-redis (1.3.0)
  - Installing vncdotool (1.2.0)

Installing the current project: suna (1.0)
✅  Backend dependencies installed successfully
ℹ️  Configuring environment files...
✅  Backend .env file created at backend\.env
ℹ️  Redis host is set to: redis
ℹ️  RabbitMQ host is set to: rabbitmq
✅  Frontend .env.local file created at frontend\.env.local
ℹ️  Backend URL is set to: http://localhost:8000/api

Step 8/8: Starting Suna
==================================================

ℹ️  You can start Suna using either Docker Compose or by manually starting the frontend, backend and worker.

How would you like to start Suna?
[1] Docker Compose (recommended, starts all services)                                                                                                                                                                                                                                                           
[2] Manual startup (requires Redis, RabbitMQ & separate terminals)                                                                                                                                                                                                                                              

Enter your choice (1 or 2): 1
ℹ️  Starting Suna with Docker Compose...
ℹ️  Building images locally...
……

五、总结

步骤	关键点
使用 MSYS2 MINGW64	提供完整的 GTK 库支持
使用 Poetry 管理虚拟环境	实现依赖隔离与精准控制
指定 MINGW64 的 Python 解释器	确保能找到 GTK 动态库
测试 GTK 加载	快速验证环境是否配置成功

通过上述方法，我们成功地绕过了 Windows 系统下因 GTK 库找不到而导致的前端安装失败问题，为顺利部署 SUNA 类似的开源 AI Agent 项目提供了稳定可靠的解决方案。