DeerFlow环境配置详解：Python3.12+Node.js22+环境搭建

让多智能体研究框架DeerFlow在你的机器上快速运行起来

1. 环境准备：选择适合你的工具链

在开始配置DeerFlow之前，我们先来了解下推荐的开发工具。这些工具能让环境管理变得简单高效，特别是当你需要同时处理多个项目时。

uv - Python环境管理的现代选择 如果你习惯用pip和virtualenv，uv会让你眼前一亮。它不只是包管理器，还能帮你管理Python版本和虚拟环境，速度比传统工具快很多。

nvm - Node.js版本管理利器 做前端开发的朋友对nvm应该不陌生。它能让你在同一台机器上安装和切换多个Node.js版本，完全不用担心版本冲突。

pnpm - 更高效的npm替代品 比npm更快、更节省磁盘空间，特别适合像DeerFlow这样依赖较多的项目。

当然，如果你习惯用传统的pip+virtualenv或者npm，也是完全可以的。不过我还是建议试试这些新工具，体验会好很多。

2. 系统要求检查

在开始安装前，先确认你的系统满足这些要求：

操作系统

• macOS 10.15+
• Windows 10/11
• Ubuntu 18.04+ 或其他主流Linux发行版

硬件要求

• 内存：至少8GB，推荐16GB
• 磁盘空间：至少10GB可用空间
• 网络：稳定的互联网连接（下载依赖包需要）

软件版本

• Python: 3.12或更高版本
• Node.js: 22.x或更高版本

检查当前版本的命令：

# 检查Python版本
python --version

# 检查Node.js版本
node --version

如果版本不符合要求，别着急，接下来我会带你一步步安装正确的版本。

3. Python 3.12安装指南

Windows系统安装

1. 访问Python官网下载页面
2. 选择Python 3.12.x的Windows安装包
3. 运行安装程序，重要：勾选"Add Python to PATH"选项
4. 选择自定义安装，确保安装pip和所有可选功能

安装完成后验证：

python --version
# 应该显示: Python 3.12.x

macOS系统安装

推荐使用Homebrew安装：

# 安装Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Python 3.12
brew install python@3.12

# 验证安装
python3.12 --version

Linux系统安装

Ubuntu/Debian系统：

# 添加dead snakes PPA（提供较新的Python版本）
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update

# 安装Python 3.12
sudo apt install python3.12 python3.12-venv python3.12-dev

# 设置默认Python版本（可选）
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1

4. Node.js 22安装步骤

使用nvm安装（推荐）

nvm让你可以轻松管理多个Node.js版本：

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重启终端或运行：
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 安装Node.js 22
nvm install 22
nvm use 22

# 设置默认版本
nvm alias default 22

直接安装包方式

如果你不想用nvm，也可以直接从Node.js官网下载安装包：

1. 访问Node.js官网下载页面
2. 选择22.x版本的安装包
3. 按照提示完成安装

验证安装：

node --version
npm --version
# 应该显示v22.x.x和对应的npm版本

5. DeerFlow项目环境搭建

现在开始真正的DeerFlow环境配置：

# 克隆项目代码
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 使用uv安装Python依赖（推荐方式）
uv sync

# 或者使用传统方式
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或者 .venv\Scripts\activate  # Windows
pip install -e .

配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑.env文件，配置你的API密钥
# 需要配置的API包括：
# - Tavily搜索API（或其他搜索引擎）
# - 大模型API（OpenAI、DeepSeek等）
# - 其他可选服务API

配置模型参数

# 复制配置文件
cp conf.yaml.example conf.yaml

# 根据你使用的模型编辑conf.yaml
# 支持多种模型：Doubao、Qwen、DeepSeek、Gemini等

6. Web UI依赖安装

DeerFlow提供了漂亮的Web界面，需要单独安装前端依赖：

# 进入web目录
cd deer-flow/web

# 使用pnpm安装依赖（推荐）
pnpm install

# 或者使用npm
npm install

7. 常见问题解决

Python版本冲突

如果你系统中有多个Python版本，确保使用正确的版本：

# 明确指定Python 3.12
python3.12 -m venv .venv
source .venv/bin/activate

Node.js版本问题

如果遇到Node.js版本错误：

# 使用nvm切换版本
nvm use 22

# 或者重新安装指定版本
nvm install 22 --reinstall-packages-from=current

依赖安装失败

如果uv安装失败，可以回退到传统方式：

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate

# 手动安装依赖
pip install -r requirements.txt

权限问题（Linux/macOS）

如果遇到权限错误，可以尝试：

# 为当前用户安装
pip install --user package-name

# 或者使用虚拟环境
python -m venv ~/.venvs/deerflow
source ~/.venvs/deerflow/bin/activate

8. 验证安装结果

完成所有安装后，进行最终验证：

# 检查Python环境
python --version
pip list  # 查看已安装的包

# 检查Node.js环境
node --version
npm list  # 查看前端依赖

# 尝试运行DeerFlow
cd deer-flow
uv run main.py

如果一切正常，你应该能看到DeerFlow启动成功的提示信息。

9. 环境配置总结

走完这一套流程，你的DeerFlow环境应该已经准备就绪了。整个过程其实不难，主要是确保Python和Node.js的版本正确，然后按照步骤安装依赖就行。

实际配置中可能会遇到一些小问题，比如网络原因导致依赖下载慢，或者系统环境变量没配置好。大多数问题都能通过仔细检查版本和重新安装来解决。

建议第一次使用时先跑个简单的例子，看看整体流程是否通畅。确认基础功能没问题后，再逐步配置各种API密钥和高级功能。这样能避免一次性配置太多东西，出了问题不好排查。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。