airflow 的普通任务函数默认运行在同步上下文中，无法直接执行 await 或返回协程对象的异步函数；若强行调用 async 函数（如 parse_pdf），会导致任务状态异常、静默崩溃或出现“executor reports task finished although task says queued”等错误。
airflow 的普通任务函数默认运行在同步上下文中，无法直接执行 await 或返回协程对象的异步函数；若强行调用 async 函数（如 parse_pdf），会导致任务状态异常、静默崩溃或出现“executor reports task finished although task says queued”等错误。
在 Apache Airflow 中，所有使用 @task() 装饰器定义的函数均以同步方式执行——即由 Airflow 的 Executor（如 LocalExecutor）在标准 Python 线程中调用，不支持原生事件循环上下文。当你调用一个返回 coroutine 对象的异步函数（例如基于 httpx.AsyncClient 或 aiohttp 封装的 parse_pdf），而未显式驱动其执行时，该函数仅返回一个未被 await 的协程对象，不会真正发起网络请求或执行逻辑。这不仅导致业务逻辑失效，更可能引发底层调度器状态不一致，表现为：
- 任务卡在 queued 或 running 状态后无响应；
- 日志中出现类似 Executor reports task instance ... finished (failed) although the task says it's queued 的警告；
- MySQL 数据库中 task_instance 状态字段与实际执行流脱节。
✅ 正确做法：在同步任务内安全启动异步函数
Airflow 本身不提供 asyncio 运行时集成，因此需借助 asyncio.run() 在任务函数内部显式创建并运行一个新的事件循环：
import asyncio
from airflow.decorators import task
@task()
def pdf_to_text_task() -> None:
file_storage_instance = get_file_storage_instance_from_task()
pdf_fpath = get_pdf_fpath(file_storage_instance)
# ✅ 正确：使用 asyncio.run 驱动异步函数执行
pages = asyncio.run(parse_pdf(pdf_fpath))
# 后续处理保持同步
pages = re.split(r"(?<p>⚠️ 注意事项：</p>
asyncio.run() 每次调用都会新建一个事件循环，适用于短生命周期的单次异步调用，不建议在循环内高频重复调用；
不可嵌套调用 asyncio.run()（如在已由 asyncio.run() 启动的协程中再次调用），否则会抛出 RuntimeError: asyncio.run() cannot be called from a running event loop；
Python 3.14.2下载Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
-
若需并发执行多个异步操作（如批量解析多个 PDF），应改用 asyncio.gather() 并仍由单次 asyncio.run() 包裹：
async def batch_parse(fpaths): return await asyncio.gather(*[parse_pdf(f) for f in fpaths]) pages_list = asyncio.run(batch_parse([f1, f2, f3])) 避免在 DAG 定义阶段（模块导入时）或全局作用域中使用 asyncio.run()，仅限于 @task 函数体内调用。
总结：Airflow 任务本质是同步入口点，异步逻辑必须主动“降级”为同步调用。asyncio.run() 是当前最简洁、兼容性最佳的解决方案。未来 Airflow 2.10+ 已开始实验性支持 @task(allow_async=True)（需配合 AsyncOperator 和专用 executor），但在稳定生产环境中，显式 asyncio.run() 仍是首选实践。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
