当前位置：首页 > news >正文

FastAPI配置管理避坑指南：从硬编码到 .env 与 pydantic_settings 类，连路由用法都给你捋清楚

news 2026/6/25 14:00:35

本文能帮你解决什么

✔️ 敏感信息泄漏风险，再也不会把密钥传到 GitHub
✔️ 快速切换开发/测试/生产环境，改一个变量就行
✔️ 用 pydantic_settings 自动校验配置，少写一堆 try-except

📌 主要内容脉络

咱们先从一个痛点说起，然后一步步把硬编码改成环境变量，再升级到pydantic_settings 的 BaseSettings，顺便说清 dotenv 和 pydantic_settings 到底怎么选。最后还会聊多环境配置覆盖和优先级那点事儿。

🚨 第一部分：硬编码的痛，你可能正在经历

很多项目一开始为了“快”，直接把数据库连接信息写成字符串。像这样：

DATABASE_URL = "postgresql://user:pass123@localhost/db"

看起来没毛病，直到你需要部署到服务器、要换一套数据库地址。

要么你手动改代码打包，要么写一堆 if-else 判断环境。更可怕的是，万一代码仓库公开，密码就等于贴在了公告栏上。

你可能会问：“那我加到 .gitignore 里不就行了？” 是的，但配置本身还是散落在各处，团队一多照样乱套。

🔧 第二部分：从环境变量到 Settings 类，步步为营

好，咱们先来第一步——把秘密藏进环境变量。

在终端 export 或者在系统里设置一个DATABASE_URL，然后代码里用os.getenv去取。这样至少不会把密码写在代码里了。

但是你很快会发现，每次重启机器环境变量就丢了，而且得挨个给队友配一遍，极其麻烦。这时候就该.env 文件出场了。

接下来重点来了——怎么把 .env 用起来？到底是选python-dotenv还是pydantic_settings？

这个工具的选择，好比选螺丝刀，不是最贵的就好，而是看你的场景。
如果你只是想要一个简单的 key-value 读取，dotenv 足够轻量；
但一旦你需要类型校验、字段默认值、多环境自动切换，pydantic_settings 的 BaseSettings 绝对是更聪明的选择。

再说个容易翻车的点：
.env 文件一定要立刻加到 .gitignore 里，并且提供一个.env.example模板文件给队友。我有次就是忘了这一步，差点把密钥推上去。

👩‍💻 第三部分：实战 —— 用 BaseSettings 管好你的配置

直接上代码，一看就懂：

from pydantic_settings import BaseSettings class Settings(BaseSettings): app_name: str = "MyFastAPI" database_url: str secret_key: str debug: bool = False class Config: env_file = ".env" env_file_encoding = "utf-8" settings = Settings()

然后你的 .env 文件长这样：

APP_NAME=FastAPI配置管理测试项目 DATABASE_URL=postgresql://user:pass@localhost/db SECRET_KEY=super-secret-key DEBUG=false

你注意到没，字段名大小写自动匹配，而且 debug 直接当布尔值用，不用自己 int("0") 转换。
pydantic 还会帮你做校验，万一环境变量里没设 database_url ，应用启动时直接抛错，避免带着空配置跑起来。

是不是以为这样就完了？还不够。生产环境的配置通常会覆盖某些默认值，这时你可以这么做：

class Settings(BaseSettings): app_name: str = "MyApp" debug: bool = False class Config: env_file = ".env" # 当存在 .env.prod 时优先加载 env_file = ".env.prod" if os.getenv("ENV") == "prod" else ".env"

官方文档虽然没强制，但根据我的经验，最好把不同环境的 .env 文件分开，再用环境变量ENV来决定加载哪个。

📂 .env 文件放哪里？不是无所谓，但也很灵活

既然 Settings 类已经在用了，那 .env 文件到底该扔在哪儿，绝对是个“说大不大，说小坑一堆”的问题。好，咱们把它掰扯清楚。

默认情况下，pydantic_settings 会在当前工作目录（CWD）下找你的 .env 文件。也就是说，你在哪个目录执行的 Python 命令，它就去哪个目录找。

举个例子，如果你的项目结构长这样：

my_project/ ├── app/ │ ├── main.py │ └── config.py ├── .env └── requirements.txt

你在 my_project 目录下执行python app/main.py或者uvicorn app.main:app，当前工作目录就是 my_project，所以它能找到同级的 .env，稳稳的。

但是！一旦你换个姿势，比如在别的地方执行，或者用 Docker、systemd 启动，工作目录往往就跑偏了。
我也曾经因为这个问题在服务器上排查了一下午，配置死活不生效，最后发现是 supervisor 把工作目录切到了 /root…… 😭

🎯 最佳实践：显式指定路径，不依赖 CWD

别再猜来猜去了，直接在 Settings 类的 Config 里把路径写清楚。这里有一个我屡试不爽的写法：

from pydantic_settings import BaseSettings import os class Settings(BaseSettings): database_url: str secret_key: str class Config: # 关键！用 file 定位到 config.py 同级目录下的 .env env_file = os.path.join(os.path.dirname(__file__), ".env") env_file_encoding = "utf-8"

这么一来，不管你在哪里执行，它永远去找 config.py 所在目录下的 .env 文件。
也就是说，把 .env 和 config.py 放在同一个文件夹里（通常是 app 目录下），就再也不会丢了。

你可能会问：“那多环境怎么办？比如 .env.prod 放哪儿？” 同样啊，也放 config.py 旁边，然后根据环境变量稍微改一下路径就行：

import os env = os.getenv("APP_ENV", "dev") env_file = os.path.join(os.path.dirname(__file__), f".env.{env}")

🧪 查找机制的底层逻辑（一句话版）

如果你不显式指定路径，pydantic_settings 内部其实调用的是 python-dotenv 的load_dotenv(env_file)，它就会基于当前工作目录去解析相对路径。所以这玩意儿就像“前台的快递”，你得站在正确的工位上才能收到。
而用__file__的方式则相当于你把收货地址写成了“我家”，无论快递员从哪个邮局出发，都能送到。