环境搭建：从零开始跑通第一个Prefect流程

说实话，很多人在学习工作流框架时，第一步就卡住了——不是装不上，就是装上了跑不起来。Prefect在这方面做得还算友好，但有些细节不注意，照样会踩坑。这一章，我带你把环境从头搭一遍，最后跑通一个Hello World。

Python环境准备

Prefect 2.x 要求 Python 3.8 以上。我个人习惯用 Python 3.10，兼容性最好，踩坑最少。

先检查你的Python版本：

python --version
# 或者
python3 --version

如果版本低于3.8，建议先升级。我推荐用 pyenv 管理多版本Python，尤其是你需要在不同项目间切换时。

创建虚拟环境：

python -m venv prefect-env
source prefect-env/bin/activate  # Linux/Mac
# 或者
prefect-env\Scripts\activate     # Windows

看到终端前面多了 (prefect-env) 前缀，说明环境激活成功。

安装Prefect

安装命令就一行：

pip install prefect

等等，别急着敲回车。先确认你的pip版本够新：

pip install --upgrade pip

然后安装Prefect。安装完成后，验证一下：

prefect version

你会看到类似这样的输出：

Version:     2.14.0
API version: 0.8.4
Python:      3.10.12

Prefect UI 启动

Prefect 2.x 自带一个Web UI，用来查看流程运行状态、日志、任务图。启动方式很简单：

prefect server start

第一次启动会自动下载依赖，稍等一会儿。看到类似下面的日志，说明启动成功：

Starting Prefect server...
...
Server started on http://127.0.0.1:4200

打开浏览器，访问 http://localhost:4200。你会看到一个清爽的仪表盘，左侧有导航菜单。

嗯，这里要注意：UI默认是空的，因为你还没跑过任何流程。别慌，接下来我们就让它有点东西。

第一个Hello World流程

现在写一个最简单的Prefect流程。新建一个Python文件，比如 hello_flow.py：

from prefect import flow, task

@task
def say_hello():
    print("Hello, Prefect!")
    return "Hello, Prefect!"

@flow
def hello_flow():
    result = say_hello()
    print(f"Flow completed with: {result}")

if __name__ == "__main__":
    hello_flow()

代码很简单：

• @task 装饰器把一个普通函数变成Prefect任务
• @flow 装饰器把函数变成工作流
• 在flow里调用task，Prefect会自动编排执行顺序

运行它：

python hello_flow.py

你会看到类似这样的输出：

17:32:15.123 | INFO    | prefect.engine - Created flow run 'fancy-koi' for flow 'hello-flow'
17:32:15.456 | INFO    | Task run 'say_hello-0' - Hello, Prefect!
17:32:15.789 | INFO    | Flow run 'fancy-koi' - Flow completed with: Hello, Prefect!

注意看，Prefect自动给流程和任务分配了运行ID（比如 fancy-koi），还带了时间戳和日志级别。这就是Prefect帮你做的第一件事——可观测性。

现在刷新一下UI页面，你会看到刚才的流程运行记录出现在仪表盘上。点进去，能看到任务图、日志、运行时长等信息。

知识体系总览

下面这张图概括了本章的核心逻辑：

常见问题与避坑

问题	原因	解决办法
prefect: command not found	虚拟环境未激活或pip安装路径不在PATH	检查 which prefect，重新激活虚拟环境
UI页面空白或报错	端口被占用或依赖未下载完成	换端口启动，或等首次启动的依赖下载完成
流程运行后UI看不到记录	Prefect Server未运行或API地址不匹配	确认 prefect server start 在运行中
安装时依赖冲突	全局Python包版本混乱	使用虚拟环境，从干净环境重新安装

验证环境是否就绪

跑完Hello World之后，我建议你做一次快速验证，确保后续章节不会因为环境问题卡住：

1. 终端能正常执行 prefect version
2. 浏览器能打开 http://localhost:4200
3. Hello World流程在UI中有运行记录
4. 虚拟环境里能正常导入 from prefect import flow, task

这四点都满足，环境搭建就算完成了。你想想看，从零到跑通第一个流程，其实就三步：装Python、装Prefect、写一个带装饰器的函数。Prefect把复杂的工作流抽象成了你熟悉的Python函数，这就是它优雅的地方。