项目名决定什么
项目名决定 Compose 创建的容器、网络与卷的名称前缀。默认取当前目录名，可以用 -p 参数、COMPOSE_PROJECT_NAME 环境变量或文件顶层的 name 字段覆盖，优先级依次递减。同一台机器上跑多套环境就是靠项目名隔离，避免容器、网络与卷互相撞名。
基本信息
| 优先级 | -p 参数 > COMPOSE_PROJECT_NAME > 顶层 name 字段 > 目录名 |
|---|---|
| 影响范围 | 容器、网络、卷的命名前缀 |
| 查看方式 | docker compose ls 与 docker ps 的 label 过滤 |
| 常见用途 | 同机多环境隔离、CI 每条流水线独立命名 |
| 生效特点 | 项目名变化相当于创建一套新资源 |
典型使用场景
- 同机区分开发与测试环境，避免资源撞名
- CI 里为每条流水线指定独立项目名
- 排查容器名前缀看不懂的问题
- 迁移目录后名称变化导致的资源重建
- 清理某个项目下的全部资源
指定与核对
指定与核对
docker compose -p shop up -d # 显式指定项目名
COMPOSE_PROJECT_NAME=shop docker compose up -d # 环境变量方式
docker compose ls # 列出当前项目
docker ps --filter label=com.docker.compose.project=shop # 查该项目下的容器
docker compose -p shop down # 清理时留意卷的处理来源与优先级
| 来源 | 优先级 | 说明 |
|---|---|---|
| -p 参数 | 最高 | 单次命令生效，适合脚本 |
| COMPOSE_PROJECT_NAME | 次高 | 环境变量，适合 CI 统一注入 |
| 顶层 name 字段 | 再次 | 写进文件，团队共享 |
| 目录名 | 默认 | 改目录名会连带改变项目名 |
同一机器上的多套环境靠项目名隔离，容器、网络与卷各有一套独立的命名空间，互不干扰。
项目名参与资源命名并影响卷名，改名相当于换了一套资源，动手前先确认原有数据卷的处理方式。
使用建议
- 多套环境共用一台宿主时，用不同项目名把资源彻底隔开
- 流水线里为每次运行注入唯一项目名，结束后按同名清理，避免资源残留
- 改名之前先列出旧项目下的容器、网络与卷，确定处理方案
- 把项目名写进部署文档与脚本默认值，减少人为差异