2. dbt项目初始化与测试环境搭建
在正式编写测试之前，需要先把 dbt 的运行环境搭起来。这一节的目标很明确：让 dbt 能够连上数据仓库，跑通第一个模型，并执行第一条测试。整个过程可以拆成五件事——安装 dbt、配置连接、初始化项目、验证连接、运行模型与测试。下面按实际操作顺序展开。
一、选择 dbt Core 还是 dbt Cloud
dbt 有两种使用形态。dbt Core 是开源命令行工具，通过 pip 安装，适合本地开发、CI 集成和完全自定义的工作流；dbt Cloud 是托管服务，提供网页 IDE、调度器和作业管理，适合团队协作和不想维护本地环境的场景。两者使用同一套项目结构和 Jinja 语法，模型与测试代码可以互通，区别主要在运行方式和调度能力上。
本课程以 dbt Core 为主线，因为它更贴近工程实践，也便于观察每一步的输入输出。如果你使用 dbt Cloud，命令行的 dbt run、dbt test 对应网页上的 Run 和 Test 按钮，配置部分则由 Cloud 界面管理，逻辑一致。
二、安装 dbt Core 与适配器
dbt Core 本身不直接连接数据库，需要配合对应仓库的适配器。安装时通常一起装：
# 建议使用虚拟环境
python -m venv dbt-env
source dbt-env/bin/activate # Windows: dbt-env\Scripts\activate
# 以 PostgreSQL 为例
pip install dbt-core dbt-postgres
# 验证安装
dbt --version输出中会列出 dbt-core 版本和已安装的适配器。常见适配器还有 dbt-snowflake、dbt-bigquery、dbt-databricks 等，按你实际使用的仓库选择。安装完成后，dbt --version 能正常打印版本号，说明环境就绪。
三、配置 profiles.yml
dbt 通过 profiles.yml 知道“连哪个仓库、用什么账号”。它默认放在 ~/.dbt/ 目录下，与项目代码分离，避免把凭据提交到 Git。一个 PostgreSQL 的配置示例如下：
my_project:
target: dev
outputs:
dev:
type: postgres
host: localhost
port: 5432
user: dbt_user
password: "{{ env_var('DBT_PASSWORD') }}"
dbname: analytics
schema: dbt_dev
threads: 4几个关键点：target 指定当前使用哪个输出环境；outputs 下可以定义 dev、prod 等多套环境；schema 是 dbt 写入模型的目标 schema，建议 dev 与 prod 分开；threads 控制并行度，本地开发 4 左右即可。密码用 env_var() 从环境变量读取，是避免明文凭据的常见做法。
dbt debug 验证连接。它会检查 profiles.yml 是否存在、凭据是否有效、能否连上仓库。全部通过会显示 “All checks passed!”，这是进入下一步的前提。四、初始化示例项目
用 dbt init 创建项目骨架：
dbt init my_project
cd my_project生成的结构包含几个核心目录：models/ 放模型，tests/ 放自定义测试，dbt_project.yml 是项目主配置，seeds/ 用于加载 CSV 种子数据。打开 dbt_project.yml，确认 name 与 profiles.yml 中的顶层键一致，profile 字段指向正确的 profile 名。这一步对不上，后续命令会直接报 “Could not find profile”。
dbt 自带的示例项目通常包含 my_first_dbt_model.sql 和 my_second_dbt_model.sql，以及对应的 schema.yml。它们足够用来跑通第一条链路。
五、运行首个模型与测试
先跑模型：
dbt rundbt 会编译模型中的 Jinja 与 SQL，按依赖顺序在仓库中创建视图或表。成功时日志显示 Completed successfully，并列出每个模型的执行状态。此时去仓库里查看 dbt_dev schema，应该能看到刚生成的模型对象。
再跑测试：
dbt testdbt 会执行 schema.yml 中声明的测试，例如 unique、not_null、accepted_values、relationships。每条测试返回通过或失败，失败会给出具体行数和示例值。示例项目中通常已包含对主键的 unique 和 not_null 测试，跑通即说明测试链路可用。
如果想一次完成“加载种子数据 + 运行模型 + 执行测试”，可以用：
dbt builddbt build 会按 DAG 顺序执行 seed、run、test，是日常开发中最常用的命令。它把模型和测试放在同一条依赖链里，某个模型测试失败时，下游依赖它的模型不会继续执行，这能尽早暴露数据问题。
六、如何判断环境搭建成功
把上面几步串起来，判断标准可以归纳为三条：dbt debug 输出 “All checks passed!”；dbt run 日志中每个模型状态为 OK，且仓库里能看到对应对象；dbt test 所有测试返回 PASS。三条都满足，说明从本地到仓库的链路已经打通，可以开始写自己的模型和测试。
如果某一步失败，排查顺序建议是：先看 dbt debug 的连接报错（多半是 host、端口、密码或 schema 权限问题），再看 dbt run 的编译错误（SQL 语法或 ref 引用错误），最后看 dbt test 的失败详情（数据本身不满足约束）。把这三层分开定位，比一次性盯着日志找问题要高效得多。