手把手教你用Python 3.11和Node.js 18在Windows 11上搭建Dify开发环境

最新推荐文章于 2026-08-24 16:28:45 发布

原创

最新推荐文章于 2026-08-24 16:28:45 发布 · 625 阅读

在Windows 11上构建Dify本地开发环境：从零到一的实战指南

最近有不少朋友在尝试搭建Dify的本地开发环境时，遇到了各种依赖冲突和环境配置的“拦路虎”。作为一个长期在Windows平台上折腾各类AI应用栈的开发者，我深知在非Docker环境下，要让Python后端、Node.js前端以及PostgreSQL、Redis这些服务和谐共处，确实需要一些细致的配置和避坑经验。这篇文章，我将结合自己多次搭建和调试的经验，为你呈现一份详尽的、可操作的Windows 11本地Dify环境搭建手册。我们不仅会一步步安装必要的软件，更会深入探讨配置背后的原理，以及遇到常见问题时如何高效排查，目标是让你能拥有一个稳定、可调试的Dify开发环境，而不仅仅是完成一次性的安装。

1. 环境基石：核心组件的精准安装与配置

搭建任何复杂的应用栈，第一步永远是打好地基。对于Dify而言，这个地基由Python运行时、Node.js环境以及两个关键的数据库服务（PostgreSQL和Redis）构成。在Windows上，我们需要特别注意版本兼容性和环境变量的设置。

1.1 Python 3.11：版本锁定与虚拟环境管理

Dify的后端重度依赖特定版本的Python包，因此使用官方指定的Python 3.11版本至关重要，这能最大程度避免因Python版本差异导致的依赖解析失败。

获取安装包：请务必访问Python官网的发布页面，找到Python 3.11.x的Windows安装程序。直接使用最新版的Python（如3.12+）可能会在后续安装某些二进制包（如psycopg2、PyTorch）时遇到兼容性问题。
安装时的关键操作：运行安装程序时，在第一个界面最下方，务必勾选“Add python.exe to PATH”。这个操作会将Python和pip命令添加到系统环境变量，让你能在任何命令行窗口直接调用它们。

安装完成后，我们需要验证安装并建立一个独立的虚拟环境。打开PowerShell或命令提示符，执行以下命令：

# 验证Python版本
python --version
# 应输出：Python 3.11.x

# 验证pip版本
pip --version

# 升级pip至最新版（使用国内镜像加速）
python -m pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：很多教程会建议使用py或python3命令，但在Windows上，安装器添加的通常是python和pip。如果遇到“命令未找到”的错误，请检查环境变量，或尝试重启终端。

虚拟环境是Python项目的“隔离舱”。我们将为Dify API创建一个：

# 假设你的工作目录是 D:\dev\dify
cd D:\dev\dify
# 克隆Dify代码库（使用Gitee镜像，速度更快）
git clone https://gitee.com/dify_ai/dify.git
cd dify\api

# 创建名为 venv 的虚拟环境
python -m venv venv

# 激活虚拟环境
.\venv\Scripts\activate

激活后，你的命令行提示符前会出现(venv)标识，这意味着后续所有pip安装的包都会被隔离在这个环境中，不会影响系统级的Python。