Prefect2.0工作流实战教程

Prefect 2.0 彻底重构了工作流的执行模型，将定义、运行与部署严格分离——@flow和@task装饰的函数仅在导入时注册对象，绝不会自动执行；必须显式调用my_flow()调试、用my_flow.serve()启动本地服务，或通过prefect deploy ./script.py:flow_name提交部署，而Docker镜像需确保Prefect版本一致、依赖完整、tag唯一且路径引用精准，稍有疏忽（如漏掉调用、嵌套定义、相对导入、镜像版本错配）就会静默失败或报错，真正踩坑点不在语法而在对“显式即安全”这一核心设计哲学的理解与落实。

Prefect 2.0 的 flow 和 task 必须显式调用才能执行

很多人写完 @flow 和 @task 装饰的函数，直接运行脚本却没任何输出——不是代码错了，是 Prefect 2.0 不再自动触发执行。它把“定义”和“运行”彻底分开。

• 定义阶段：只注册对象（Flow、Task），不执行任何逻辑
• 运行阶段：必须显式调用 my_flow() 或 my_flow.serve()，或通过 prefect deploy 提交到服务器
• 本地调试时最简方式就是直接加一行 my_flow() 在文件末尾；漏掉这行，等于写了张菜谱但从不下锅
• 注意：在 Jupyter 中多次运行同一 cell 可能导致 Flow 重复注册报错 ValueError: Flow with name 'xxx' already exists，建议每次重载模块或重启 kernel

部署时 prefect deploy 找不到 flow 的常见原因

prefect deploy 命令依赖 Python 模块路径和函数全名，不是靠当前工作目录或文件名猜的。

• 确保目标 flow 函数在模块顶层（不能嵌套在 if/else 或函数内部）
• 命令格式必须是 prefect deploy ./my_script.py:my_flow，中间用英文冒号分隔路径和函数名
• 如果脚本依赖相对导入（比如 from .utils import helper），prefect deploy 会失败——它用的是模块加载机制，不是直接 exec，所以推荐改用绝对导入或把共用代码打成包
• Windows 下路径斜杠方向不影响，但文件扩展名 .py 不能省略

State 类型和 return 值的关系容易被误解

Prefect 2.0 的 task 返回值默认包装成 State 对象，但你写的 return "done" 不会变成失败态，也不会自动重试——除非你主动 raise 异常或调用 raise FAILED("reason")。

• 正常返回任意 Python 对象（str、dict、None）都会被转为 Completed 状态，下游 task 收到的是解包后的值，不是 State
• 想让 task 显式失败，得 raise Exception("boom") 或 raise prefect.exceptions.Abort("stop now")，而不是 return Failed(...)
• 使用 return_state=True 参数调用 task（如 my_task.submit(return_state=True)）才会真正拿到 State 实例，日常链式调用不用管它
• 日志里看到 Finished in state Completed(message="All states completed.", type=COMPLETED) 是正常收尾，不是 warning

Docker 部署时 prefect.yaml 的 image 和 pull_policy 配置陷阱

本地测试通过的 flow，一上 Docker 就报 ModuleNotFoundError，大概率是镜像里没装你的包，或者装了但版本不对。

• image 字段填的是构建后的镜像名+tag，比如 myorg/myflow:1.2，不是 Dockerfile 路径
• pull_policy 默认是 IfNotPresent，CI/CD 流水线里如果复用 tag（如 always use :latest），旧镜像可能被跳过拉取——建议用 commit hash 或日期戳做 tag
• 镜像构建时，requirements.txt 必须包含 prefect>=2.0，且版本要和本地开发一致；否则 flow 定义语法可能不兼容（例如 2.11+ 的 log_prints=True 在 2.9 会报错）
• 别在 Dockerfile 里用 COPY . /opt/prefect 然后期望 prefect deploy 自动识别——部署命令不管容器里怎么组织文件，只认你传给它的 Python 模块路径

Prefect 2.0 的 flow 注册、运行、部署三步之间边界很清晰，但每步的触发条件和隐含依赖比 1.x 更多。最容易卡住的地方不是语法，而是“以为它该自动做某事”，结果发现得手动补调用、补路径、补镜像 tag。

今天关于《Prefect2.0工作流实战教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！