AI Agents · 课时

.env 文件与 python-dotenv

Q: 「.env 文件与 python-dotenv」这节课中我会学到什么？

加载 .env 文件、配置 .gitignore 规则和遵循 dotenv 最佳实践。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

加载 .env 文件、配置 .gitignore 规则和遵循 dotenv 最佳实践。

.env 文件与 python-dotenv 是 CoddyKit 上的免费 AI Agents 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

Shell 导出存在的问题

在 Shell 中使用 export 设置环境变量虽然可行，但每次打开新的终端会话时都必须重新设置。以这种方式管理大量变量容易出错，也无法方便地与团队成员共享。

.env 文件通过将所有项目变量存储在一个会自动加载的文件中解决了这个问题。

.env 文件格式

.env 文件由 KEY=VALUE 对组成，每行一个。以 # 开头的行是注释。值可以选择是否使用引号括起来。这种简单的格式受到数十种工具和框架的支持。

# .env file (NEVER commit this file to git)

# Required API keys
OPENAI_API_KEY=sk-proj-your-real-key-here
SEARCH_API_KEY=tvly-your-tavily-key-here

# Optional settings with defaults
AGENT_MODEL=gpt-4o-mini
AGENT_MAX_STEPS=20
LOG_LEVEL=DEBUG

# Database (optional — disables memory storage if not set)
# DATABASE_URL=postgresql://user:pass@localhost/agentdb

# Environment identifier
ENV=development

使用 python-dotenv 加载 .env

使用 pip install python-dotenv 安装 python-dotenv。在入口点的最顶部、任何读取 os.environ 的操作之前调用 load_dotenv()。它会加载 .env 文件并填充环境。

# pip install python-dotenv
from dotenv import load_dotenv
import os

# Load .env file — call this BEFORE reading any env vars
load_dotenv()

# Now all variables from .env are available via os.environ
openai_key = os.environ['OPENAI_API_KEY']
model = os.getenv('AGENT_MODEL', 'gpt-4o-mini')
max_steps = int(os.getenv('AGENT_MAX_STEPS', '20'))

print(f'Model: {model}, Max steps: {max_steps}')

load_dotenv() 选项

load_dotenv() 有几个实用选项：使用 dotenv_path= 指定自定义路径，使用 override=True 覆盖已有的环境变量（默认会跳过已有变量），使用 verbose=True 记录加载了哪个文件。

from dotenv import load_dotenv
import os

# Load from a specific path
load_dotenv(dotenv_path='/path/to/custom/.env')

# Override existing environment variables
# (by default, existing vars are NOT overridden)
load_dotenv(override=True)

# Load a specific environment file
env_file = os.getenv('ENV_FILE', '.env')
load_dotenv(dotenv_path=env_file, verbose=True)

# Find .env automatically (searches up the directory tree)
from dotenv import find_dotenv
load_dotenv(find_dotenv())

使用 dotenv_values() 获取显式配置字典

dotenv_values() 会将 .env 文件内容作为 Python 字典返回，而不会修改环境。当您希望检查或使用配置、又不想污染进程环境时，这非常有用。

from dotenv import dotenv_values

# Read .env into a dict without touching os.environ
config = dotenv_values('.env')

print(config.get('AGENT_MODEL'))   # 'gpt-4o-mini'
print(config.get('LOG_LEVEL'))     # 'DEBUG'

# Merge .env with actual environment (env vars take priority)
import os
combined = {**dotenv_values('.env'), **os.environ}

# This means actual environment variables override .env values
# Useful for CI where env vars are injected by the pipeline

.env.example 文件

创建一个 .env.example 文件，使用占位值记录所有必需变量。此文件可以提交到 Git——它用于向团队成员和新开发者说明需要配置哪些内容。

# .env.example — commit this file to git
# Copy to .env and fill in real values:
# cp .env.example .env

# Required API keys (get from respective providers)
OPENAI_API_KEY=sk-proj-your-openai-key-here
SEARCH_API_KEY=tvly-your-tavily-key-here

# Optional settings
AGENT_MODEL=gpt-4o-mini
AGENT_MAX_STEPS=20
LOG_LEVEL=INFO
ENV=development

# Database (optional)
# DATABASE_URL=postgresql://user:password@localhost:5432/agentdb

将 .env 添加到 .gitignore

.env 文件绝不能提交到 Git。在创建项目时立即将其添加到 .gitignore。在首次提交前确认它已被忽略。

# .gitignore — add these lines

# Environment files with real secrets
.env
.env.local
.env.production
.env.staging

# But DO commit these:
# .env.example  (placeholder values, safe to share)

# Verify .env is ignored before committing:
# git check-ignore -v .env
# .gitignore:1:.env   .env    <-- means it IS ignored (good)

# If .env was already tracked:
# git rm --cached .env
# git commit -m 'Remove .env from tracking'
# echo '.env' >> .gitignore

阻止提交 .env 的提交前钩子

添加一个提交前钩子，阻止任何包含 .env 文件的提交。如果有人忘记检查 .gitignore，这可以提供自动安全防护。

# .git/hooks/pre-commit (make executable: chmod +x .git/hooks/pre-commit)

#!/bin/sh
# Block commits that include .env files with real content
if git diff --cached --name-only | grep -qE '^\.env$';
then
  echo 'ERROR: .env file is staged for commit!'
  echo 'This file contains secrets and must NOT be committed.'
  echo 'Run: git reset HEAD .env'
  exit 1
fi

# Also check for common secret patterns in any staged file
if git diff --cached | grep -qE '(sk-proj-|tvly-|xai-)';
then
  echo 'WARNING: Possible API key detected in staged changes!'
  echo 'Review carefully before committing.'
fi

exit 0

在不同框架中加载 .env

许多框架会自动加载 .env 文件。FastAPI（通过 pydantic-settings）、Django（通过 django-environ）和 Docker Compose 都原生支持 .env。了解这些模式可以避免重复加载。

# FastAPI with pydantic-settings (auto-loads .env):
# pip install pydantic-settings
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    openai_api_key: str
    agent_model: str = 'gpt-4o-mini'
    log_level: str = 'INFO'

    class Config:
        env_file = '.env'

# settings = Settings()  # auto-reads .env and validates types
# print(settings.agent_model)  # 'gpt-4o-mini'

# FastAPI is also fine with plain load_dotenv() at the top of main.py
# No need to use pydantic-settings for simple agents

为不同环境使用多个 .env 文件

为不同环境使用单独的 .env 文件：.env.development、.env.staging、.env.production。根据 ENV 变量加载正确的文件。

import os
from dotenv import load_dotenv

# Determine which environment to load
env = os.getenv('ENV', 'development')

# Try environment-specific file first, fall back to base .env
env_file = f'.env.{env}'
if os.path.exists(env_file):
    load_dotenv(env_file)
    print(f'Loaded {env_file}')
else:
    load_dotenv('.env')
    print('Loaded .env')

# Usage:
# ENV=staging python agent.py     -> loads .env.staging
# ENV=production python agent.py  -> loads .env.production
# python agent.py                 -> loads .env (default development)

完整设置检查清单

新代理项目的完整 .env 设置检查清单：

创建包含真实密钥的 .env（绝不提交）
创建包含占位值的 .env.example（提交此文件）
将 .env 添加到 .gitignore
在入口点顶部添加 load_dotenv()
在启动时验证必需变量
将 cp .env.example .env 添加到 README 的设置说明中

知识检查：.env 文件和 python-dotenv

测试您对 .env 文件和 python-dotenv 库的理解。

回顾：.env 文件和 python-dotenv

现在，您已经为代理项目建立了完整的 .env 工作流：

创建包含真实值的 .env 文件——绝不提交
创建包含占位值的 .env.example——始终提交
将 .env*（.env.example 除外）添加到 .gitignore
在入口点的最顶部调用 load_dotenv()
使用 dotenv_values() 访问字典，而不接触 os.environ
为每个环境使用单独的文件（.env.staging、.env.production）

这种工作流可以将机密信息排除在 Git 之外，同时让本地开发更加轻松。

常见问题解答

「.env 文件与 python-dotenv」课时是免费的吗？

是的 — 「.env 文件与 python-dotenv」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「.env 文件与 python-dotenv」这节课中我会学到什么？

加载 .env 文件、配置 .gitignore 规则和遵循 dotenv 最佳实践。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「.env 文件与 python-dotenv」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents