API Key 环境变量读不到？从应用进程、dotenv 到 Docker 排查

云岚API · 排错 · 更新于 2026-10-25

API Key 读不到，先查真正运行应用的进程，不要只看另一个终端是否设置过变量。再沿启动来源、dotenv 加载与容器注入逐层定位。本文限定 Bash、Python 和 Docker Compose 后端，资料核对日期为 2026-10-25；没有读取真实 Key、运行容器或调用云岚API。

先确认程序读的是哪个变量

变量名以实际代码或 SDK 文档为准。APP_API_KEY 是本文的自定义示意，不能替代所有 SDK 的默认名称；例如 LangChain 示例会显式读取它并传入客户端。

在应用入口、创建客户端之前检查，只输出非空状态：

import os
print("APP_API_KEY_nonempty:", bool(os.getenv("APP_API_KEY")))

应通过平时启动应用的同一入口运行，而不是另开一个环境不同的 Python。False 包括不存在或空字符串；True 也不证明内容正确、权限有效或请求发往正确站点。Python 环境变量接口

记录变量名、启动方式和状态即可，不打印值、前后缀或整份环境。环境读取已经通过而接口仍报鉴权错误时，转到认证与调用排查，不要反复改加载方式。

为什么终端有值，应用还是没有？

Bash 中普通赋值与导出不同：需要传给后启动子进程的变量，应标记为 export。这不是整台电脑的全局修改；另一个终端、已启动的 IDE 或后台服务不因此自动更新。先核对谁启动了应用，再按该入口重新启动需要更新的进程。Bash 环境继承

若 Python 又启动了子程序，检查是否传了 subprocess 的 env 参数：提供字典会替代默认继承的环境，不会自动补上漏掉的变量。不要为了修一个 Key 盲目复制全部环境，应按子程序所需字段配置。Python subprocess

.env 文件在，为什么没有进入进程？

文件存在不等于已加载。普通 Python 的 os.getenv 不负责寻找 .env；若项目使用 python-dotenv，应先加载，再读取配置和创建客户端。对普通脚本，可以明确指定脚本同目录文件：

import os
from pathlib import Path
from dotenv import load_dotenv

env_path = Path(__file__).resolve().parent / ".env"
print("dotenv_file_exists:", env_path.is_file())
load_dotenv(dotenv_path=env_path, override=False)
print("APP_API_KEY_nonempty:", bool(os.getenv("APP_API_KEY")))
# 随后再读取配置、创建客户端

这个路径约定不是所有项目的根目录；Notebook 等没有普通脚本 __file__ 的入口，应传入自己确认的路径。这里只展示已有 python-dotenv 项目的写法，未执行读取。自动查找的起点会受运行方式影响，排错时明确路径更容易核对。python-dotenv 用法

默认 override=False 会保留已有环境变量，包括已存在的空字符串。旧值来自启动器时，只改文件可能没有效果；先确认来源，不要把 override=True 当通用修复。如果客户端已把旧配置保存到对象里，后来加载文件也不会自动更新该对象。1.2.4 加载实现

Compose 的 .env 和容器环境是两件事

Compose 的 .env 常用于替换配置中的 ${变量}；它不会仅因文件存在就把所有变量放进容器。需要服务中的 environment 或 env_file 等明确注入。以下是加到已有 app 服务的配置片段，不是完整部署文件：

services:
  app:
    environment:
      APP_API_KEY: ${APP_API_KEY:?APP_API_KEY is required}

这里要求插值来源中的变量已设置且非空，否则报错；不会检查 Key 真伪。也可按项目选择服务级 env_file，路径按 Compose 文件位置核对。两种方式不是“文件复制进镜像”的同义词。容器变量注入、必填插值语法

优先级要分层看：Compose 插值时，启动 shell 的同名变量可覆盖文件来源；容器配置中，environment 又优先于 env_file。不要因为某个文件里有正确值，就断定实际进程采用了它。Compose 优先级

构建时设置过，运行时还要核对吗？

要。Docker ARG 不会自动成为运行容器的环境变量；也不要用构建参数或 Dockerfile ENV 固化真实 Key。运行时配置应走项目既定的注入或 secrets 机制。构建变量说明

修改 Compose 环境配置后，仅 docker compose restart 不会应用新配置；按部署流程重新创建受影响服务，再检查应用状态，不需要为此删除数据卷。restart 的范围

下载环境加载核对包，逐次记录“配置来源、加载前后、客户端初始化、容器配置应用和最终结论”。空白表不存 Key，未知项标待核；这些检查不能代替实际 API 认证或计费验收。

常见问题

变量非空就能证明 Key 配对正确吗？

不能。还要核对签发站点、接口地址与协议及权限。本文只定位配置怎样到达应用，不判断密钥有效性。

.env 中只有变量名，没有等号，会怎样？

python-dotenv 的 load_dotenv 会忽略这种无值项；APP_API_KEY= 则是空字符串。两者都不能当作可用凭证。文件格式

前端构建时读到了 Key，可以直接发请求吗？

不要把后端加载方案直接搬进浏览器。客户端可见变量可能进入构建产物；按前端与后端代理边界处理，另查浏览器跨源条件。

Codex、Claude Code 也照这个变量名设置吗？

不照搬。它们有各自的认证和配置约定，分别看 Codex、Claude Code 与 Gemini CLI教程。本页只提供进程与加载层的排查顺序。