必须启用BuildKit，否则--mount=type=cache被忽略；target路径须与COMPOSER_CACHE_DIR一致且容器内真实存在；id需按项目唯一命名；COPY composer.json和lock文件必须在RUN挂载前，避免业务代码变更破坏缓存层。
挂载 --mount=type=cache 必须启用 BuildKit
没开 BuildKit，--mount=type=cache 直接被忽略，命令照常执行但不生效。构建前必须设环境变量：DOCKER_BUILDKIT=1（Linux/macOS）或 set DOCKER_BUILDKIT=1（Windows cmd）。CI 环境还要确认 runner 已全局启用 BuildKit，否则白配。
target 路径要和 COMPOSER_CACHE_DIR 一致
Composer 不会自动读取任意挂载路径，必须显式指定缓存目录。常见错误是只挂载 /tmp/cache 却没告诉 Composer 用它：
RUN --mount=type=cache,id=composer-cache,target=/tmp/cache COMPOSER_CACHE_DIR=/tmp/cache composer install --no-dev -o- 不能写成
target=/root/.composer/cache—— 容器内该路径通常不存在或权限不足 - 避免用
~或$HOME，Docker 构建阶段不展开 shell 变量
缓存 ID 复用需注意作用域
id=composer-cache 是全局唯一的缓存键。同一 ID 在不同项目或不同分支间共享缓存可能引发冲突（比如 A 项目下载的包被 B 项目误用），尤其在 CI 中：
- 推荐按项目名或哈希生成 ID：
id=php-app-composer-cache - 若用远程构建器（如 Docker Hub 或 GitHub Actions 自托管 runner），确保缓存存储后端支持多租户隔离
- 本地开发可忽略，但 CI 流水线里别偷懒共用一个 ID
单阶段下仍需保证 composer.json 和 composer.lock 先拷贝
挂载缓存加速的是包下载，不是层缓存逻辑。如果 COPY . . 放在 composer install 前面，哪怕用了 --mount，每次代码变更仍会破坏整个安装层：
- 正确顺序：先
COPY composer.json composer.lock ./，再RUN --mount=...，最后COPY . . - 注意
COPY . .不能覆盖已安装的vendor/—— 否则挂载缓存白忙一场 - 若项目根目录有大量无关文件，记得用
.dockerignore排除，否则 COPY 操作本身变慢
