configs 做什么
Compose 的 configs 把配置文件按名字声明并注入服务，写法与 secrets 类似：顶层声明来源（本地文件或已存在的配置对象），服务里按名引用，默认挂载到 /<配置名>，也可以用 target 指定完整路径。适合 nginx 配置、应用参数文件这类只读内容的分发。
基本信息
| 顶层声明 | configs: 名称: {file: 路径} |
|---|---|
| 服务引用 | configs: [名称] 或 {source:, target:} |
| 默认挂载路径 | /<配置名>，可用 target 覆盖 |
| 适用平台 | Compose V2；集群模式下对应集群配置对象 |
| 更新方式 | 内容随容器重建更新，热加载仍要走 reload |
典型使用场景
- 把 nginx、应用配置文件与镜像分离，改配置不动镜像
- 多服务共享同一份只读配置：一处声明，多处引用
- 配置需要在容器内固定路径出现，而不依赖外部挂载脚本
- 把配置纳入编排版本管理，与镜像版本对应发布
- 需要类似 secrets 机制分发非敏感只读文件的场景
Compose 写法示例
Compose 写法示例
services:
web:
image: nginx:1.27-alpine
configs:
- source: nginx_conf # 引用顶层声明的配置
target: /etc/nginx/nginx.conf # 容器内落地路径
configs:
nginx_conf:
file: ./nginx.conf # 来源：仓库里的配置文件核对挂载结果
核对挂载结果
docker compose config # 展开查看最终编排
docker compose exec web cat /etc/nginx/nginx.conf # 确认容器内内容
docker compose up -d --force-recreate web # 改配置后重建生效声明与引用要点
| 要素 | 含义 | 注意 |
|---|---|---|
| file | 配置来源为本地文件 | 路径相对编排文件所在目录 |
| external | 引用已存在的配置对象 | 集群环境中较常见 |
| 服务 configs | 服务侧引用声明 | 不写 target 时用默认路径 |
| target | 容器内落地路径 | 指向已有文件时会被覆盖 |
配置文件挂载后内容随容器重建更新；需要不重启就生效的流程，仍要走应用自身的 reload 机制。
target 指向镜像内已存在的路径时会覆盖该文件，覆盖行为要事先验证，避免静默改掉镜像内文件造成意外。
目录级的复杂内容用 configs 逐个声明会很啰嗦，这类场景更适合绑定挂载；configs 的优势在于单文件与版本对应清晰。