OAuth2PasswordBearer 实例化必须传入与登录接口完全一致的 tokenUrl（如"/api/v1/token"），且应作为模块级常量声明；密码流需手动验证用户、用python-jose签发JWT，密钥须从环境变量读取。
OAuth2PasswordBearer 实例化时必须传入 tokenUrl
FastAPI 的
不是认证逻辑本身，只是一个依赖项工具，用于从请求头中提取
。它必须明确知道令牌的获取地址（
），否则后续 Swagger UI 的“Authorize”按钮无法自动填充表单，调试时会卡在 401 且无提示。
常见错误是写成
却没定义对应路由；或路径写成
，但实际接口注册在
—— 这会导致文档里点击 Authorize 后跳转失败，返回 404。
必须与你后续实现的登录接口路径完全一致（包括前缀、大小写、斜杠）
建议统一用绝对路径，如
，避免前端代理或部署子路径时出错
如果使用 APIRouter 前缀，
应与最终暴露的 URL 匹配，而非 router 的 prefix
密码流登录接口必须手动验证用户并调用 create_access_token
FastAPI 不提供内置的用户校验或 JWT 签发函数。
只负责解析
和
字段（来自表单编码，不是 JSON），其余全部需自行实现：查库、比对密码、生成 token。
JWT 签发推荐用
（FastAPI 官方示例所用），而非
，因前者默认启用更严格的签名算法和过期检查。
立即学习
“
Python免费学习笔记（深入）
”；
务必用
或
验证密码，禁止明文比对
函数应接收
（如
）、
，并使用
密钥（
）必须存为环境变量，绝不可硬编码；长度建议 ≥32 字节（如用
生成）
示例片段：
Python 3.14.3
微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
下载
依赖项中嵌套调用 OAuth2PasswordBearer 会破坏依赖注入链
不要在自定义依赖函数内部再实例化
。例如下面这种写法是错的：
正确做法是：全局只定义一次
，然后所有需要鉴权的地方都直接
。否则 FastAPI 无法统一管理依赖生命周期，Swagger 文档会丢失认证配置，且每次调用都新建对象，影响性能。
把
实例作为模块级常量声明，而不是函数内局部变量
若需多套认证方案（如 admin/user 分开 tokenUrl），才分别定义多个 scheme，但每个仍应是常量
依赖项函数（如
）只接收已提取的
，不负责提取
JWT 解析失败时要区分 InvalidTokenError 和 ExpiredSignatureError
用
验证 token 时，不同异常代表不同问题：
是过期，
（或其子类如
）可能是签名无效、格式错误、issuer 不匹配等。统一捕获
并返回 401 是合理的，但日志中应保留具体类型，方便排查。
不要忽略
的
，这是标准响应头，客户端（如 Axios）靠它识别认证失败
避免在 decode 时设置
，这等于关闭过期检查，存在安全风险
若使用
或
，确保签发和验证时参数严格一致，字符串比较区分大小写
JWT 签发和校验的密钥、算法、有效期、payload 结构这些点，一旦上线就很难变更，尤其当 token 已下发到客户端。初始化时多花两分钟核对
来源和
路径，能省掉后续半天的日志排查。
OAuth2PasswordBearerAuthorization: Bearer tokenUrlOAuth2PasswordBearer(tokenUrl="token")/auth/token/api/v1/logintokenUrltokenUrl="/api/v1/token"tokenUrlOAuth2PasswordRequestFormusernamepasswordpython-josePyJWTbcryptpasslibcreate_access_tokendata: dict{"sub": "user123"}expires_delta: timedeltajwt.encode(..., algorithm="HS256")SECRET_KEYsecrets.token_urlsafe(32)from jose import jwt
from datetime import timedelta
SECRET_KEY = "your-super-secret-key-here"
ALGORITHM = "HS256"
def create_access_token(data: dict, expires_delta: timedelta):
to_encode = data.copy()
expire = datetime.utcnow() + expires_delta
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
OAuth2PasswordBearerdef get_current_user(token: str = Depends(OAuth2PasswordBearer(tokenUrl="/token"))): # ❌ 错误：重复实例化
...
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/token")Depends(oauth2_scheme)OAuth2PasswordBearerget_current_usertoken: strjwt.decode()ExpiredSignatureErrorInvalidTokenErrorJWTErrorJWTErrorcredentials_exception = HTTPException(status_code=401, ...)headers={"WWW-Authenticate": "Bearer"}options={"verify_exp": False}audienceissuerSECRET_KEYtokenUrl