# 仓库里的 SQL 模型变更还对不齐，Dbt 官方怎么在本地跑起来？

**URL:** <https://www.shiqidu.com/t/topic/2111>\
**Category:** 开发调优\
**Tags:** 编程, 问与答, 开源软件, 数据库, Python\
**Created:** [2026 年11 月 16 日 08:08 UTC](https://www.shiqidu.com/t/topic/2111 "2026-11-16T08:08:07Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

作者： ![shiqidu\_editor](https://www.shiqidu.com/user_avatar/www.shiqidu.com/shiqidu_editor/32/528_2.png) [@shiqidu\_editor](https://www.shiqidu.com/u/shiqidu_editor)\
发布日期： [2026 年11 月 16 日 08:08 UTC](https://www.shiqidu.com/t/topic/2111/1 "2026-11-16T08:08:07Z")

</div>

分析用的 SQL 模型放在仓库里，版本和变更还对不齐。想按官方文档在本机把 dbt 跑起来，不要把云端向导当成唯一路径。这和给数据库做结构迁移不是同一件事，那种可以看站内这篇 [Flyway](https://www.shiqidu.com/t/topic/2080)。这里谈的是分析用的 SQL 模型怎么在本机编译、跑通。

[What is dbt?](https://docs.getdbt.com/docs/introduction) 把 dbt 写成：把仓库里的原始数据，转成可信任的数据产品。你写的是普通的 SQL `select`，物化成表或视图，模型之间的依赖也交给它处理。介绍页还说，使用时的主要工作就是写反映业务逻辑的模型（也就是 `select` 查询），不必再手写创建表、视图的样板代码，也不必自己规定模型谁先谁后，这些由它来做。页里把用法分成两种：一种走 dbt platform（浏览器里的 Studio IDE，或本地工具连到平台帐户），另一种是在本机命令行或编辑器里安装、运行。官方写 platform 适合大多数人，但本机这条路是单独写出来的，并不是只能跟着云端向导走。

本机安装看 [Install dbt](https://docs.getdbt.com/docs/local/install-dbt)。页头标明适用于 dbt v2.0 及以后。装上之后，默认得到的就是当前这一代的 dbt v2。安装方式按平台选即可：

- pip：`python -m pip install dbt`
- macOS 的 Homebrew：先 `brew tap dbt-labs/dbt`，再 `brew install dbt-labs/dbt/dbt`
- macOS / Linux 的 curl 脚本：`curl -fsSL https://public.cdn.getdbt.com/fs/install/install.sh | sh -s -- --update`，二进制会落到 `~/.local/bin/dbt`
- Windows 可用 `winget install --id dbtLabs.dbt --exact`，或在 PowerShell 里执行 `irm https://public.cdn.getdbt.com/fs/install/install.ps1 | iex`

装完后跑 `dbt --version` 确认命令已经在 PATH 里。若提示找不到命令，安装页让你把安装目录加进 `$PATH`。curl 和 PowerShell 那两种方式，还提醒先关掉再打开终端，或执行 `exec $SHELL` / `Start-Process powershell`，让新的 PATH 生效。v2 指南里给出的示例输出长得像 `dbt 2.0.0`，用来对照命令能不能用。排障一节还提到版本冲突：检查机器上是不是同时还激活着其它自托管的 dbt，或 dbt platform CLI。页里也写了 `dbt login`，用来登录免费的平台帐户、打开完整 LSP 和部分平台能力，这不是本机跑模型的必需步骤。如果组织有硬性要求必须用开源运行时，同一页指向 Install dbt OSS，并注明 `dbt-oss` 和 `dbt` 不能共用一个 Python 环境。安装页的后续步骤则指向配置 `profiles.yml`、配置数据平台连接，以及用 `dbt init` 创建第一个项目。

入门索引在 [dbt Quickstarts](https://docs.getdbt.com/docs/get-started-dbt)。页上能看到按数仓走的 platform 向导，同时也有 Self-hosted 这一段：可以在 Windows、macOS 或 Linux 上安装，搭配或不搭配平台帐户都行。不登录的话，就是完全在自己的环境里跑。要核对的是入口指向。「install dbt」仍链到上面的安装页。「Self-hosted dbt v2 from a manual install」现在指向 [Quickstart for dbt v2](https://docs.getdbt.com/guides/dbt)，而 [Quickstart for dbt from a manual install](https://docs.getdbt.com/guides/manual-install) 在索引里的标签已经是 Self-hosted dbt v1。本机默认装到的是 v2，跟着 v2 这份指南走更合适，不要把 v1 那篇当成当前默认路径。

v2 指南里，本机命令行可以单独使用，不必先装 VS Code 扩展。常用顺序是先在目标目录执行 `dbt init`。它会搭一个示例项目，并带你配置连接。已有 profile 时可以用 `dbt init --skip-profile-setup`。接下来 `cd jaffle_shop`，再执行 `dbt build`。指南写明，`dbt build` 会载入示例数据、创建并测试模型，用来确认这套环境已经能工作。若是在交互提示里新建了凭据，`init` 结束时还会自动跑一次 `dbt debug`，确认新写的 profile 能连上数据库。若机器上同时还装着 dbt v1 或 dbt platform CLI，官方建议继续用 `dbt` 作为默认命令，并可用 `dbtf` 作为 v2 的明确别名，免得两条命令搅在一起。

连接用的凭据不要写进项目仓库。v1 那份手工安装指南把这一点写得很清楚：`profiles.yml` 放在项目外面，就是为了避免把数据库凭据提交进版本库。v2 的 `init` 也会引导你配置 profile，同样不要把口令或密钥文件路径提交到 Git 里。

仓库里的模型改完，你们是先在本机跑通 `dbt build`，还是直接丢到托管环境里看结果？

---

<div class="post-metadata">

作者： ![caojie](https://www.shiqidu.com/user_avatar/www.shiqidu.com/caojie/32/465_2.png) [@caojie](https://www.shiqidu.com/u/caojie)\
发布日期： [2026 年11 月 17 日 12:28 UTC](https://www.shiqidu.com/t/topic/2111/2 "2026-11-17T12:28:02Z")

</div>

dbt init 建项目，profiles.yml 里配连接。

dbt run 跑模型，dbt test 跑校验，两个分开跑看得清。

第一次最容易卡在 profiles.yml 的路径上，它在 ~/.dbt/ 下，不在项目目录里。
