📚 课程目录第2章环境搭建

环境搭建：从零开始跑起你的第一个Dagster项目

说实话，很多初学者在数据工程这条路上栽的第一个跟头，往往不是框架本身有多难，而是环境没搭好。我见过太多人花了一整天装包、冲突、卸载、再装……最后连个Hello World都没跑起来。

这一章，我们就来把这套流程走一遍。你跟着我做，大概十分钟就能看到一个活生生的Dagit界面出现在浏览器里。

2.1 Python虚拟环境：隔离是美德

为什么非要搞个虚拟环境？说白了，就是为了不让你电脑上的其他项目打架。我几年前接手过一个遗留项目，里面用的还是Dagster 0.9.x，而新项目已经到1.3了。如果没有虚拟环境，那画面太美我不敢看。

我个人习惯用 venv，Python自带的，轻量又干净。你也可以用conda或poetry，看个人喜好。这里我演示最通用的方式：

# 创建虚拟环境
python -m venv dagster-env

# 激活（Windows）
dagster-env\Scripts\activate

# 激活（macOS/Linux）
source dagster-env/bin/activate

激活成功后，你会看到命令行前面多了个 (dagster-env) 前缀。嗯，看到这个就说明环境隔离好了。

小技巧： 我习惯把虚拟环境建在项目根目录外面，比如 ~/venvs/dagster-env。这样即使你删了项目代码，虚拟环境还能留着复用，不用每次重装依赖。

2.2 安装Dagster库：一步到位还是按需取用？

Dagster的包设计得挺讲究。核心库很小，其他功能都是插件式的。你如果只是学基础，装下面三个就够了：

pip install dagster dagit dagster-pandas

解释一下这三个东西各自干什么：

包名	作用
`dagster`	核心框架，定义资产、作业、调度等
`dagit`	Web UI，可视化查看和调试管道
`dagster-pandas`	Pandas集成，方便处理DataFrame

我曾经踩过一个坑：直接 pip install dagster 就以为完事了，结果启动dagit时报错说找不到模块。后来才发现 dagit 是单独安装的。所以上面那行命令，三个包一起装，省心。

注意版本兼容性： Dagster的版本迭代很快，大版本之间API可能有变化。建议你安装时指定版本号，比如 dagster==1.3.0，这样教程里的代码不会因为版本差异跑不通。我写这章时用的是1.3.x系列。

2.3 项目脚手架初始化：别从零开始

手动创建文件夹、写配置文件？没必要。Dagster提供了一个脚手架命令，帮你把项目骨架搭好：

dagster project scaffold --name my_dagster_project

执行完，你会看到这样一个目录结构：

my_dagster_project/
├── my_dagster_project/
│   ├── __init__.py
│   ├── assets.py
│   ├── jobs.py
│   ├── schedules.py
│   └── sensors.py
├── my_dagster_project_tests/
│   └── test_assets.py
├── workspace.yaml
├── setup.py
└── README.md

这个结构很清晰：

assets.py：放你的数据资产定义，这是Dagster 1.x的核心概念
jobs.py：定义作业，把资产串成执行流程
schedules.py / sensors.py：定时调度和事件触发
workspace.yaml：告诉Dagit去哪里加载你的代码
setup.py：让你的项目可以被pip安装

我个人习惯拿到脚手架后，先把 assets.py 打开看一眼。里面有一个示例资产，你可以直接删掉换成自己的逻辑。别怕删错，脚手架就是给你改的。

2.4 启动Dagit UI：见证奇迹的时刻

环境搭好了，项目也初始化了，接下来就是最激动人心的一步——启动UI。

cd my_dagster_project
dagit -f my_dagster_project/assets.py

看到类似这样的输出，就说明成功了：

Dagit is running on http://127.0.0.1:3000

打开浏览器，输入 http://localhost:3000。你会看到一个漂亮的界面，左侧是资产列表，右侧是资产依赖图。如果脚手架里的示例资产还在，你应该能看到一个叫 my_asset 的节点。

  核心概念： Dagit不仅仅是一个展示面板。你可以在这里手动触发资产执行、查看运行日志、检查数据产出、甚至调试失败的任务。说白了，它就是Dagster的驾驶舱。

我第一次启动Dagit时，盯着那个空荡荡的资产图看了好久。虽然啥都没有，但那种「我的数据管道终于有了可视化界面」的感觉，真的很爽。

2.5 本章知识体系总览

下面这张图，把我们从创建虚拟环境到启动Dagit的完整流程串起来了。你可以把它当作一个检查清单：

2.6 常见问题与避坑指南

环境搭建这块，我见过的坑比代码还多。挑几个高频的说说：

端口被占用： 如果你本地3000端口已经被别的服务占了，dagit会报错。加个 -p 3001 参数换个端口就行。
Python版本太低： Dagster 1.x要求Python 3.8以上。我见过有人用Python 3.6装了半天装不上，最后发现是版本问题。
虚拟环境激活后pip还是全局的： 检查一下 which pip 指向的是不是虚拟环境里的路径。如果不是，说明激活没生效。

我的习惯： 每次新建项目，我都会在 requirements.txt 里固定版本号，比如 dagster==1.3.0。这样团队其他人拉代码后，pip install -r requirements.txt 一步到位，不会出现「我本地能跑你那边不行」的尴尬。

好了，环境搭好，项目初始化完成，Dagit也跑起来了。你现在可以打开浏览器，看看那个空白的资产图——很快，我们就会往里面填满真正有价值的数据资产。