执行摘要

• 一句话：注册构建来源环境变量，消除启动警告
• 推荐动作：本 PR 值得精读，因为它展示了 vLLM 项目中 envs.py 的注册模式，以及如何在 Docker 构建和 Python 运行时之间同步环境变量默认值。对于维护者，应关注后续 Dockerfile 默认值变更时需同步此文件。

功能与动机

PR #40653 向 vllm-openai 镜像添加了构建来源元数据（VLLM_BUILD_COMMIT、VLLM_BUILD_PIPELINE、VLLM_BUILD_URL、VLLM_IMAGE_TAG）作为 ENV 变量，但未在 vllm/envs.py 的 environment_variables 字典中注册，导致每次启动都打印警告。Issue #45311 报告了此问题，本 PR 修复它，类似 #35007 对 VLLM_BATCH_INVARIANT 的修复。

实现拆解

1. 在类型注解类中添加字段：在 vllm/envs.py 的 _EnvironmentVariableTypeAnnotations 类（约第98-101行）中添加了四个字段，与 Dockerfile 中的默认值一致：VLLM_BUILD_COMMIT: str = "unknown"、VLLM_BUILD_PIPELINE: str = "local"、VLLM_BUILD_URL: str = ""、VLLM_IMAGE_TAG: str = ""。这些字段用于类型检查和默认值提示。
2. 在运行时注册表中添加条目：在 environment_variables 字典（约第626-631行）中添加了对应项，每个变量使用 lambda: os.environ.get(..., ...) 模式，默认值从环境变量中读取，若未设置则回退到硬编码默认值。这样既能读取 Docker 设置的值，又能在本地开发时提供合理的默认值。
3. Review 中调整默认值：初始提交中 VLLM_IMAGE_TAG 默认值为 "local/vllm-openai:dev"（与 Dockerfile 一致），但在 review 讨论后，作者将其改为空字符串，以覆盖容器外也有该变量的场景。最终默认值与 Dockerfile 中的 ENV 默认值保持一致（除了 VLLM_IMAGE_TAG 改为空字符串）。
4. 无测试配套变更：本 PR 仅修改了核心配置注册逻辑，未添加或修改测试文件；功能较为简单，通过手动验证和 CI 确认。

关键文件：

• vllm/envs.py（模块 配置；类别 source；类型 core-logic）: 核心变更文件：在类型注解类和运行时注册字典中添加了四个构建来源环境变量，消除未注册警告。

关键符号：未识别

关键源码片段

vllm/envs.py

核心变更文件：在类型注解类和运行时注册字典中添加了四个构建来源环境变量，消除未注册警告。

# In _EnvironmentVariableTypeAnnotations class (around line 98)
VLLM_BUILD_COMMIT: str = "unknown"
VLLM_BUILD_PIPELINE: str = "local"
VLLM_BUILD_URL: str = ""
VLLM_IMAGE_TAG: str = ""
# ...
​
# In environment_variables dict (around line 626)
# Build provenance metadata embedded in official vllm-openai images.
# Set via Docker ENV at image build time; informational only.
"VLLM_BUILD_COMMIT": lambda: os.environ.get("VLLM_BUILD_COMMIT", "unknown"),
"VLLM_BUILD_PIPELINE": lambda: os.environ.get("VLLM_BUILD_PIPELINE", "local"),
"VLLM_BUILD_URL": lambda: os.environ.get("VLLM_BUILD_URL", ""),
"VLLM_IMAGE_TAG": lambda: os.environ.get("VLLM_IMAGE_TAG", ""),

类型注解类中的字段提供类型提示和默认值，运行时注册表使用 lambda 延迟读取环境变量，确保 Docker 设置的值被正确识别，未设置时回退到硬编码默认值。

评论区精华

核心讨论围绕默认值的选取。Reviewer @AndreasKaratzas 建议将默认值设为 None 或空字符串，而作者 @nicklasfrahm 指出默认值应与 Dockerfile 保持一致以避免意外（Dockerfile 中 VLLM_BUILD_COMMIT 默认 unknown、VLLM_BUILD_PIPELINE 默认 local、VLLM_BUILD_URL 默认为空、VLLM_IMAGE_TAG 默认 local/vllm-openai:dev）。最终 VLLM_IMAGE_TAG 的默认值改为空字符串，因为该变量可能在容器外也存在。其他三个变量的默认值与 Dockerfile 保持一致。

• 环境变量默认值是否应与 Dockerfile 一致 (design): 采纳部分建议：VLLM_IMAGE_TAG 默认值改为空字符串（因为该变量可能在容器外也存在），其余三个变量保持与 Dockerfile 一致的默认值。

风险与影响

• 风险：无显著风险。变更仅为注册四个字符串环境变量，不改变任何核心逻辑，不会引入回归或性能问题。安全性方面，这些变量是只读的信息性元数据，无注入风险。兼容性方面，默认值与 Dockerfile 一致，容器内外行为一致。
• 影响：对用户：消除官方 Docker 镜像启动时的 4 行警告日志，改善运维体验。对系统：无行为改变，仅注册已知变量。对团队：维护成本低，未来若修改 Dockerfile 默认值需同步更新此处。影响范围：所有使用 vllm-openai 镜像的用户。影响程度：低。
• 风险标记：无

关联脉络

• PR #40653 Add build provenance metadata to Docker images: 此 PR 在 Dockerfile 中引入了这 4 个环境变量，但未在 envs.py 注册，导致了本 PR 修复的警告问题。
• PR #35007 Register VLLM_BATCH_INVARIANT env var to suppress warning: 本 PR 采用相同模式修复同类问题：将 Docker 内置但未注册的环境变量添加到 envs.py 的 environment_variables 字典中。
• PR #45311 Unknown vLLM environment variable detected for build provenance vars: 关联 Issue，描述了本 PR 修复的告警问题，是本次变更的直接动因。