Apache Airflow 开发环境 IDE 集成指南PyCharm / IntelliJ / VSCode 与云端开发环境快速上手【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflowApache Airflow 是一个用于以编程方式编写、调度和监控工作流的平台。本指南以仓库内 contributing-docs/quick-start-ide/ 下的 IDE 集成文档为骨架系统讲解如何在本地的 PyCharm、IntelliJ IDEA、VSCode 以及远程的 GitHub Codespaces、GitPod 环境中搭建 Airflow 开发环境。读完本文你将掌握一键生成 JetBrains 工程配置含单模块 / 多模块两种模式、为 provider 源码与测试配置 source/test root、配置数据库与 DAG 调试断点、以及在云端浏览器环境中启动 Breeze 并运行 Airflow 的完整实操流程。Airflow 3.0 起airflow-core、task-sdk、airflow-ctl、devel-common以及每一个 provider 都变成了独立的 distribution各自拥有独立的pyproject.toml。这一架构变化直接影响了 IDE 的配置方式——你需要为每个要开发的 provider 单独标记 source root 与 tests root。本文将结合 dev/ide_setup/setup_idea.py 等源码级证据把这一过程的底层原理讲清楚。一、IDE 集成方案总览官方文档 IDE integration 将开发环境分为两大类类型环境特点本地开发环境PyCharm / IntelliJ IDEA借助setup_idea.py脚本一键生成工程配置支持源码级调试本地开发环境VSCode借助 Pylance 的 Extra Paths 与launch.json调试配置远程开发环境GitHub Codespaces浏览器内基于 VS Code 的开发环境所有 GitHub 用户可用免费版有每月小时数限制远程开发环境GitPod浏览器内基于 GitPod 的开发环境付费服务两条本地路径的详细指南分别见 contributors_quick_start_pycharm_intellij.rst 与 contributors_quick_start_vscode.rst远程路径见 contributors_quick_start_codespaces.rst 与 contributors_quick_start_gitpod.rst。二、PyCharm / IntelliJ IDEA从克隆到一键工程配置1. 克隆仓库打开 PyCharm/IntelliJ选择克隆仓库Clone Repository选项在 URL 字段粘贴 fork 后的仓库链接并提交。2. 运行 setup_idea.py 自动配置项目克隆完成后在仓库根目录运行官方提供的工程配置脚本uv run dev/ide_setup/setup_idea.py该脚本会依次完成三件事对应 dev/ide_setup/setup_idea.py 中的run_uv_sync执行uv sync创建.venv虚拟环境检测 Python SDK生成.idea/airflow.iml、.idea/modules.xml、.idea/misc.xml等工程文件。脚本支持**单模块single-module与多模块multi-module**两种模式并根据检测到的 IDE自动选择检测到IntelliJ IDEA→ 默认使用多模块模式只检测到PyCharm或未检测到 IDE→ 默认使用单模块模式。也可以显式覆盖自动检测结果# 单模块模式所有 source root 注册在同一个 IntelliJ module 下PyCharm 与 IntelliJ 均可用 uv run dev/ide_setup/setup_idea.py --single-module # 多模块模式每个 distribution/package 拥有独立的 .iml 模块文件 uv run dev/ide_setup/setup_idea.py --multi-module多模块模式下的生成物每个模块如airflow-core、providers/amazon都会生成独立的.iml文件如airflow-core/airflow-core.iml、providers/amazon/providers-amazon.iml带来更好的模块级 SDK 控制与更清晰的项目视图。⚠️重要限制多模块模式必须使用 IntelliJ IDEA Ultimate在 PyCharm无论是 Community 还是 Professional中都不工作。PyCharm 不支持指向项目根目录子目录、且各自携带独立.iml模块文件的多个 content root——它会静默忽略或错误处理子模块。IntelliJ IDEA Ultimate 配合 Python 插件能正确处理是因为它完整支持 IntelliJ 多模块项目模型。使用 PyCharm 请坚持单模块模式。配置完成后重启 PyCharm/IntelliJ IDEA。3. 脚本的全部可选参数setup_idea.py提供了丰富的命令行选项官方文档逐一列出下表汇总参数作用示例--python VERSION为虚拟环境指定 Python 次版本如3.12透传给uv sync --python须与项目requires-python约束兼容省略时由uv选择默认版本uv run dev/ide_setup/setup_idea.py --python 3.12--multi-module/--single-module覆盖自动检测的模块模式。多模块模式还会通过第二次uv sync创建独立的dev/breeze虚拟环境其 Python SDK 命名为Python X.Y (breeze)其余子模块继承项目级 SDKuv run dev/ide_setup/setup_idea.py --multi-module--confirm对所有交互式确认提示关闭 IDE、终止进程、覆盖文件自动回答 yes适合非交互、脚本化或 Agent 驱动场景uv run dev/ide_setup/setup_idea.py --confirm--open-ide配置完成后在项目目录打开 IntelliJ IDEA 或 PyCharm。macOS 使用open -aLinux 优先查找 JetBrains Toolbox 启动脚本回退到PATH上的命令两个 IDE 都装时优先 IntelliJuv run dev/ide_setup/setup_idea.py --open-ide--no-kill不尝试检测并终止正在运行的 PyCharm/IntelliJ 进程。默认行为是先检测 IDE 进程、请求确认、发送SIGTERM5 秒未退出则回退SIGKILLuv run dev/ide_setup/setup_idea.py --no-kill--idea-path PATH指定要更新的 JetBrains 配置目录而非自动检测全部已安装 IDE。可指向 JetBrains 基础目录如~/Library/Application Support/JetBrains或具体产品目录如.../JetBrains/IntelliJIdea2025.1用于自动检测失败或只想针对特定安装的场景uv run dev/ide_setup/setup_idea.py --idea-path ~/Library/Application\ Support/JetBrains/IntelliJIdea2025.1--exclude MODULE_OR_GROUP从生成的工程配置中排除模块可多次指定。值为模块相对路径如providers/amazon、dev/breeze或分组名providers表示providers/下所有 provider、shared表示shared/下所有共享库、dev表示 dev 模块、tests表示测试专用模块如docker-tests、kubernetes-tests。适合只开发部分代码、想加速 IDE 索引的场景uv run dev/ide_setup/setup_idea.py --exclude providers --exclude shared所有选项可以自由组合例如创建排除全部 provider 的 Python 3.12 多模块工程uv run dev/ide_setup/setup_idea.py --multi-module --python 3.12 --exclude providers从源码看setup_idea.py模块发现逻辑会扫描STATIC_MODULES固定列表含airflow-core、airflow-ctl、task-sdk、devel-common、dev、dev/breeze、docker-tests、kubernetes-tests等再递归扫描providers/**/pyproject.toml与shared/*/pyproject.toml发现 provider 与共享库模块最后按--exclude过滤。这正是每个 distribution 独立模块这一架构在 IDE 配置层的落地实现。4. 脚本生成了什么文件脚本会生成/更新以下文件见 setup_idea.py.idea/airflow.iml— 根模块定义单模块模式包含所有 source root多模块模式仅包含排除项.idea/modules.xml— 模块注册表列出所有 IntelliJ 模块.idea/misc.xml— 项目级 Python SDK 引用从.venv推导.idea/.name— 将 PyCharm 项目名设为airflow-目录名使自动检测的 SDK 名称与配置匹配module/module.iml— 各模块的独立文件仅多模块模式。脚本还会做两件重要的全局配置注册 Python SDK 到全局 jdk.table.xml。SDK 采用uv (名称)的命名约定get_sdk_name与 PyCharm 自动检测的 uv 解释器命名一致因此打开项目时 SDK 立即可用无需手动配置解释器。若已存在 homePath 匹配的 SDK 会直接复用保留 IntelliJ 的 python_stubs、typeshed 等 classPath 条目仅必要时重命名register_sdk。配置项目级排除模式。脚本会写入大量排除规则避免 IntelliJ 索引生成物/构建产物——包括__pycache__、*.egg-info、.mypy_cache、.pytest_cache、.ruff_cache、node_modules、.vite、venv、.terraform、target等按模式递归匹配的目录EXCLUDE_PATTERNS以及.venv、dist、files、logs、generated、dev/breeze/.venv等按根路径精确排除的目录ROOT_EXCLUDE_FOLDERS。5. 手动配置项目替代脚本也可以不运行脚本手动配置。由于 Airflow 3.0 将airflow-core、task-sdk、airflow-ctl、devel-common及每个 provider 拆分为独立 distribution各自有独立pyproject.toml必须为airflow-core、task-sdk、airflow-ctl、devel-common配置 source root并且为每一个要开发的 provider分别设置 source 与 tests root这是极易遗漏的关键点。同样地还需将task-sdk源码以及类似方式的devel-common添加为 source root。6. 配置 Python 解释器手动配置第 5 节场景下需要将解释器指向uv sync创建的虚拟环境进入File → Settings → Project → Python Interpreter点击齿轮图标选择Add Interpreter → Existing指向.venv/bin/python。如果使用了setup_idea.py脚本第 2 节SDK 已全局注册只需重启 IDE 即可自动获得解释器。7. 清除缓存并重启建议在完成项目配置后执行Invalidate Caches and RestartFile → Invalidate Caches...让 IDE 以干净的索引状态加载新配置。8. PyCharm 中的调试设置调试 Airflow 需要本地预先配置好名为airflow-env的虚拟环境。第一步配置 Airflow 数据库连接Airflow 默认使用 SQLite可在本机~/airflow/airflow.cfg的sql_alchemy_conn查看配置在airflow-env中安装 MySQL 连接依赖pyenv activate airflow-env pip install PyMySQL修改~/airflow/airflow.cfgsql_alchemy_conn mysqlpymysql://root:127.0.0.1:23306/airflow?charsetutf8mb4第二步调试示例 DAG在 PyCharm 中为项目添加解释器指向~/.pyenv/versions/airflow-env/bin/python即 pyenv 创建的airflow-env虚拟环境。路径File → Setting → Project: airflow → Python Interpreter在 PyCharm 打开 Airflow 项目。本机/files/dags目录在 Breeze Airflow 启动时默认挂载到 Docker 机器因此该目录下任何 DAG 文件都会被 Docker 中的 scheduler 自动拾取可在http://127.0.0.1:28080上查看将/airflow/example_dags中的任意示例 DAG 复制到/files/dags/在 DAG 文件末尾添加__main__块使其可运行if __name__ __main__: dag.test()运行该文件。dag.test()会触发一次 backfill 式的本地运行可在 MySQL Workbench 中查看dag_run、xcom等表的内容。三、VSCode克隆、Extra Paths 与调试配置1. 克隆仓库打开 VSCode选择克隆仓库选项粘贴 fork 后的克隆链接到 URL 字段并提交。2. 为 provider 测试配置 Pylance Extra Paths使用官方 Python 插件时必须为每个要开发的 provider 的 tests 目录添加Extra Paths否则 provider 测试代码无法被 import 解析例如from unit.postgres.hooks.test_postgres import ...这在 Airflow 3.0 拆分 provider 为独立 distribution各自有独立pyproject.toml后尤为重要。操作步骤打开File → Preferences → Settings在Settings标签页切换到Workspace这样 Extra Paths 只对当前项目生效进入Extensions → Pylance区块在Python → Analysis: Extra Paths中添加要开发 provider 的 tests 目录路径。如果使用 pyright 作为其他编辑器的 LSP可以在pyrightconfig.json中以同样的方式配置extraPaths参见 pyright 官方配置文档。完成第 2 步后建议重启 VSCode。3. 设置调试数据库连接与 PyCharm 完全一致的思路Airflow 默认使用 SQLite配置可见于本机~/airflow/airflow.cfg的sql_alchemy_conn在airflow-env中安装 MySQL 依赖pyenv activate airflow-env pip install PyMySQL修改~/airflow/airflow.cfgsql_alchemy_conn mysqlpymysql://root:127.0.0.1:23306/airflow?charsetutf8mb44. 调试示例 DAG在 VSCode 中打开 Airflow 项目/files/dags挂载与http://127.0.0.1:28080查看方式同 PyCharm 一节将/airflow/example_dags中示例 DAG 复制到/files/dags/在 DAG 末尾添加__main__块会运行一个 backfill jobif __name__ __main__: dag.test()在 Debug 配置的env字段中添加AIRFLOW__CORE__EXECUTOR: LocalExecutor在Run视图点击Create a launch.json file修改program指向示例 DAG并添加env与python字段{ configurations: [ program: ${workspaceFolder}/files/dags/example_bash_operator.py, env: { PYTHONUNBUFFERED: 1, AIRFLOW__CORE__EXECUTOR: LocalExecutor }, python: ${env:HOME}/.pyenv/versions/airflow/bin/python ] }注意AIRFLOW__CORE__EXECUTOR: LocalExecutor至关重要——dag.test()需要本地执行器才能在当前进程中直接运行任务而不是提交给远程执行器。现在即可调试示例 DAG并在 MySQL Workbench 中查看dag_run、xcom等表。5. 进阶一键生成组件级调试配置仓库还提供了 dev/ide_setup/setup_vscode.py 脚本可为 Airflow 各核心组件生成调试配置attach 模式运行uv run dev/ide_setup/setup_vscode.py从源码看setup_vscode.py脚本内置了各组件的调试端口映射并生成.vscode/launch.json组件端口scheduler50231dag-processor50232triggerer50233api-server50234celery-worker50235edge-worker50236生成的每个配置create_debug_configuration使用 debugpy attach 模式包含request: attach、justMyCode: False并通过pathMappings将本地${workspaceFolder}映射到容器内的/opt/airflow。配合 Breeze 启动的容器即可远程调试各个 Airflow 组件更多细节可参见 contributing-docs/20_debugging_airflow_components.rst。四、云端开发环境一GitHub CodespacesCodespaces 是基于 GitHub Codespaces 的浏览器开发环境对所有 GitHub 用户开放免费版有每月小时数限制。Fork 项目访问 Apache Airflow 官方 GitHub 仓库https://github.com/apache/airflow/并 fork 项目创建 Codespace从 fork 的仓库页面点击Open in GitHub Codespaces按钮创建 Codespace进入 Breeze 环境Codespace 启动后终端已处于Breeze环境中可以直接在 VS Code 界面中编辑并运行测试使用 VSCode 指南由于 Codespaces 以 Visual Studio Code 作为界面详细操作可参照 contributors_quick_start_vscode.rst。Codespaces 中 Docker 故障排查如果运行 Breeze 命令时看到 Docker is not running 错误按以下顺序排查验证 Docker 是否可访问docker info命令失败时检查 Docker socket 是否存在ls -la /var/run/docker.sock检查当前用户是否有 Docker 访问权限groups $USER列表中应包含docker如果没有将用户加入 docker 组sudo usermod -aG docker $USER上述步骤无效时重建 devcontainer命令面板 →Codespaces: Rebuild Container或从 GitHub Codespaces 仪表盘重启 Codespace。五、云端开发环境二GitPodGitPod 是基于 GitPod 的浏览器开发环境为付费服务。Fork 项目并克隆进入 fork 后的仓库点击Code复制克隆链接用 GitPod 打开访问https://gitpod.io/#复制好的URL即会基于你的 fork 启动 GitPod 工作区。安装 BreezeGitPod 默认镜像已包含所需软件包。推荐使用shim 安装器安装 Breeze它在 GitPod 与本地机器上的工作方式一致pip install uv ./scripts/tools/setup_breeze该命令会在~/.local/bin/breeze安装一个小型 shim通过uv run --locked从当前 git worktree 的dev/breeze目录运行 Breeze依赖由dev/breeze/uv.lock锁定。这一设计遵循仓库内的 ADR 0017从当前 worktree 的锁定源码运行 breeze。从 ADR 0017 可以了解到该 shim 的底层机制每次调用breeze时shim 会执行git rev-parse --show-toplevel解析当前 worktree然后委托给uv run --project worktree/dev/breeze --locked breeze。这样每个 worktree包括并行 agentic 工作流创建的大量短期 worktree都有自己隔离的 Breeze 环境不会再出现多个 checkout 争夺同一个全局安装的问题shim 是PATH上的真实文件因此 pre-commit 钩子、CI 脚本等通过subprocess.run([breeze, ...])调用的场景也能正常解析。传统的全局安装方式uv tool install -e ./dev/breeze或pipx install -e ./dev/breeze仍然可用但已不再推荐。初始化数据库在运行 webserver 之前需要初始化数据库重置数据库airflow db reset创建管理员用户airflow users create \ --role Admin \ --username admin \ --password admin \ --email adminexample.com \ --firstname foo \ --lastname bar注airflow users命令仅在启用 FAB auth manager 时可用。启动 Airflow使用 Breeze 启动 Airflowbreeze start-airflow以开发模式启动breeze start-airflow --dev-mode注数据库初始化步骤仅在需要使用 webserver 时必需运行测试时数据库会在首次运行时自动初始化。六、创建分支与后续开发无论是 PyCharm、IntelliJ 还是 VSCode创建开发分支的流程一致点击状态栏中的分支符号输入分支名并 checkout。完成 IDE 环境搭建后典型的日常开发任务可参考 contributing-docs/03_contributors_quick_start.rst 快速上手指南也可以参考仓库根目录的 contributing-docs/03a_contributors_quick_start_beginners.rst面向初学者的版本。七、给 Agent 与自动化工作流的提示仓库为 AI Agent 场景专门提供了 dev/ide_setup/AGENTS.md当 Agent 需要在 IntelliJ IDEA 或 PyCharm 中打开项目如评审 PR、检查代码、修改代码时直接运行uv run dev/ide_setup/setup_idea.py --confirm --open-ide--confirm让脚本无需任何交互提示即可重新生成 IDE 配置--open-ide随后自动在项目目录打开 IDE。这套组合正是为无人工干预的脚本化、Agent 驱动场景设计的对应脚本参数说明中的--confirm与--open-ide条目。八、常见问题与要点回顾PyCharm 不支持多模块模式多模块模式--multi-module仅适用于 IntelliJ IDEA UltimatePyCharm 请使用默认的单模块模式--single-module。provider 的 tests root 必须手动添加由于 Airflow 3.0 的分布拆分PyCharm 需要为每个 provider 分别设置 source/test rootVSCode 需要为每个 provider 的 tests 目录配置 Pylance Extra Paths——这是新手最容易踩的坑。调试 DAG 的三个关键点dag.test()的__main__块、AIRFLOW__CORE__EXECUTORLocalExecutor环境变量、以及指向airflow-env虚拟环境的 Python 解释器。setup_idea.py是幂等的脚本会清理上一次运行生成的.idea/管理文件与散落的子模块.iml文件cleanup_previous_setup并跳过node_modules、.venv、.git等目录可放心重复执行。云端环境的差异Codespaces 免费版有每月小时数限制GitPod 为付费服务两者启动后都直接进入 Breeze 环境可参照本地 VSCode 指南继续操作。至此你已掌握 Airflow 在四种主流开发环境PyCharm/IntelliJ、VSCode、Codespaces、GitPod中的完整搭建与调试方法可以专注于 DAG 与 provider 的实际开发了。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考