必须启用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 用它：

OpenClaw Docker Setup

在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...

下载

• 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 操作本身变慢

实际生效的关键不在“挂了没”，而在挂的位置、告诉 Composer 用哪、以及是否让这一层真正独立于业务代码变更。BuildKit 缓存能省下载时间，但层顺序错了，连缓存机会都没有。