我用fastapi-scaff搭了个项目，两天工期缩到两小时，老板以为我开挂了

是不是每次开新项目，光是搭那个目录结构、配数据库、写那个重复了八百遍的 settings.py 就想摔键盘？🎯

反正我当年是。记得有一次，我信心满满地准备花两天搞定一个Demo的后端骨架，结果第一天晚上十一点了，我还在纠结是应该把路由单独拆一个文件，还是把所有的 Pydantic 模型放一块儿。那种感觉就像盖房子，地基还没挖好，人已经累趴了。

直到我遇见了它——fastapi-scaff 。一个能让你直接从“搬砖模式”切换到“创作模式”的脚手架。这不是什么官方钦定，而是社区里一位实在老哥写的好东西，专门治咱们这种“项目初始化PTSD”。

📦 这玩意儿到底能帮你省多少事？

一句话，它把 FastAPI 项目的 “最佳实践”固化成了代码模板 。

你不用再去网上搜“FastAPI项目结构推荐”，也不用拷贝上一个项目里乱七八糟的配置文件。它能给你直接生成一套包括异步SQLAlchemy数据库连接、Alembic数据库迁移、JWT/API Key认证、Docker部署支持、环境变量管理在内的完整骨架，甚至连Celery异步任务都集成好了。

本文能帮你解决：

  ⚡ 5分钟跑起来一个结构清晰、可直接开发的FastAPI项目。

  ⚡ 理解 fastapi-scaff 的核心目录作用，别在里面迷路。

  ⚡ 解决新手最容易碰到的环境变量加载失败、数据库连接不上的问题。

🛠️ 上手第一步：别怂，就是几条命令的事

好，咱们先来把它装上。这工具用起来和咱们熟悉的 create-react-app 或者 vue-cli 差不多，全程无痛。

1. 确保你有 Python 3.11+ 的环境。然后直接 uv 虚拟环境下安装它（如果你喜欢，也可以全局安装，这样后面就不用每个命令前都加上 uv run 了，但我更喜欢干净的环境，干净的项目，各玩各的，各取所需！！！）：

uv add fastapi-scaff

2. 装完之后，先看看帮助文档确认装对了：

uv run fastapi-scaff -h

3. 接下来重点来了，在你想要创建项目的目录下，敲入这行命令：

uv run fastapi-scaff new my_awesome_project

看着屏幕上一堆文件刷刷地创建出来，是不是有种莫名的舒适感？

Starting new project...
Done. Now run:
> 1. cd my_awesome_project
> 2. modify config, eg: db
> 3. pip install -r requirements.txt
> 4. python runserver.py

😌 控制台里输出以上内容，到这里，架子就搭好了。是不是以为这样就完了？别急着跑，直接 uvicorn main:app --reload 绝对行不通！ 这个脚手架有自己的启动方式。

另外再说个好用的，脚手架支持四种项目模板，按需选择：

  - 标准模板（默认，不写 -t 就行）

  - 轻量模板： fastapi-scaff new <项目名> -t light

  - 微型模板： fastapi-scaff new <项目名> -t tiny

  - 单文件模板： fastapi-scaff new <项目名> -t single

如果你需要集成 Celery 做异步任务，创建项目时直接加参数： fastapi-scaff new myproject --celery 。

💣 最容易翻车的三个点（我全替你们趟过了）

你可能会问，不就是个脚手架吗，能有多坑？这里就是我当初头撞南墙的地方。

坑一：Python版本不对，安装直接失败

这个脚手架明确要求 Python >= 3.11 ，如果你还在用3.8、3.9，建议先升级。我当初在公司的老服务器上部署，Python 3.9直接报错，查了半天才发现是版本问题。

坑二：启动命令不是 uvicorn

这个脚手架有自己的入口脚本。进入项目目录后，先安装依赖：

uv add -r requirements.txt

然后运行项目用的是项目根目录下的 runserver.py ：

uv run runserver.py

官方文档虽然说了，但很多人都习惯性敲 uvicorn ，结果自然是一头雾水。

坑三：数据库迁移命令也变了

这个脚手架内置了Alembic迁移，但执行方式不是直接敲 alembic upgrade head ，而是通过项目里的脚本：

# 生成迁移文件
uv run runmigration.py generate init

# 执行迁移
uv run runmigration.py upgrade

再说个容易翻车的点：你需要在运行项目之前，先去 config/ 目录下把数据库配置改好，默认的数据库URL如果不改，启动照样报错。

.env 定义了环境变量的类型，app_xxx 是不同环境的具体配置信息，APP信息、数据库连接等就在这里面修改！！！

🚀 实战演示：跑起来，然后看看里面都有啥

填完上面的坑，现在进入项目目录，用你喜欢的IDE打开。

先把数据库迁移跑一下（前提是你已经配好了数据库连接）：

uv run runmigration.py generate init
uv run runmigration.py upgrade

然后，启动服务：

uv run runserver.py

访问 http://127.0.0.1:8000/docs ，看到那个熟悉的 Swagger UI 界面没？恭喜你，骨架跑通了！

使用 create 接口创建一个 admin 角色的用户，然后使用 login 接口登录，拿到 token 后，输入到上面的 Authorize 中，然后就可以访问 list 用户列表了，否则会报权限错误！
这一套下来，妥妥的用户认证也有了！！！

这个脚手架的精髓在于模块化。它把项目比作一个精装房，架构是ASM（API-Services-Models）：

  - app/api/ 目录就是你的客厅和卧室，所有接口路由都放这里。

  - app/services/ 目录是工具箱，业务逻辑往里塞。

  - app/models/ 是房子的承重墙（数据库表结构）。

  - app/initializer/ 是水电煤气总闸，配置、数据库连接、日志都在这里。

  - config/ 是项目级的配置文件目录。

  - app_celery/ 如果你加了 --celery 参数，这个目录就出现了。

这个脚手架还有个很实用的功能——给现有项目添加API：

# 进入项目根目录
uv run fastapi-scaff add user

它会自动生成对应API的CRUD代码骨架，连增删改查的路由都给你搭好了。

💡 最后一个忠告

这个脚手架就像一套趁手的螺丝刀，不是最贵的，但是开箱即用，尺寸正好。它极大地降低了我们从一个想法到一行代码之间的摩擦成本。

最后啰嗦一句，不要被脚手架限制死。当你项目复杂到一定程度，完全可以对它动刀，把默认的 SQLAlchemy 换成你喜欢的 Tortoise-ORM 或者 Peewee 。它的使命是帮你开个好头，而不是绑住你的手脚。

好了，今天就先聊到这儿。希望下次你再开新项目时，不再是愁眉苦脸地搭环境，而是泡杯咖啡，优雅地敲下 fastapi-scaff new  ，然后像个艺术家一样，开始雕琢你的代码。

---

👩‍💻 觉得这篇踩坑记录对你有帮助？

点个 「赞」和「关注」，让我知道你在看。

转发给你那个还在手动搭项目目录的倒霉蛋同事，救救他！

👇 评论区聊聊，你搭项目最烦哪一步？