构建与环境配置分离是什么
构建与环境配置分离（12-Factor 的 build/release/run 分离）指：制品不携带环境配置，同一镜像部署到所有环境，环境差异在运行时注入。这样一次构建可以被验证、被晋级、被回滚——回滚的就是那个已经验证过的制品，而不是重新构建一个「应该一样」的新产物。构建期确实需要凭据的场景（私有包源令牌、签名密钥）用挂载临时注入而不是固化进层；运行期配置用环境变量、挂载文件或密钥管理注入，改配置不需要重新构建。
基本信息
| 原则 | 镜像/包与配置分离（12-Factor 基础） |
|---|---|
| 构建期凭据 | BuildKit secret 挂载、npm/pip 私有源令牌临时注入 |
| 运行期 | 环境变量/挂载文件/密钥管理注入，变更无需重构建 |
| 典型例外 | 前端构建期变量，需要运行时配置能力 |
典型使用场景
- 一次构建多环境：同一制品从测试一路晋级到生产，制品本身不变。
- 回滚一致性：回滚指向已验证的旧制品，不需要重建。
- 构建缓存复用：配置差异不影响构建缓存命中。
- 安全合规：镜像历史里没有密钥，构建日志也不出现明文。
- 前端运行时配置：搭一个 config.js 或配置接口，替代按环境重新构建。
反例与正例
反例与正例
# 反例：构建时把 API_URL 写进产物
# VITE_API_URL=https://prod.example.com npm run build
# 正例：同一产物，运行时注入（前端可通过运行时配置接口）
# 后端: 环境变量/挂载文件在启动时读取
# 构建期私有源: BuildKit secret 挂载（--mount=type=secret）阶段对照
| 阶段 | 输入 | 说明 |
|---|---|---|
| build | 源码+依赖 | 产出可复现制品 |
| release | 制品+配置模板 | 组合为发布单元 |
| run | 环境特定配置 | 进程启动时注入 |
前端构建期变量是常见例外：需要运行时配置能力（config.js/接口下发）才能保持一次构建，否则又退回到按环境重建。
构建期凭据不要用 build-arg：参数会留在镜像元数据里，用 BuildKit secret 挂载，仅指定层可见。