根本原因是--mount=type=cache仅加速包下载和解压，不改变docker层缓存判断逻辑；vendor/复用只取决于copy composer.json composer.lock ./与run composer install是否命中缓存，而这由文件哈希和指令顺序决定。
为什么--mount=type=cache挂载后vendor层还是不命中？
根本原因不是挂载没生效，而是它只加速包下载和解压，不影响 Docker 层缓存判断逻辑。vendor/目录是否复用，只取决于COPY composer.json composer.lock ./和RUN composer install这两步是否被缓存——而这完全由文件内容哈希与指令顺序决定。
常见错误现象：RUN --mount=type=cache,target=/root/.composer composer install执行很快，但每次改src/文件，后续构建仍重跑整个composer install。
-
--mount=type=cache必须配合 BuildKit 启用（DOCKER_BUILDKIT=1或docker build --buildkit），否则直接忽略 - 挂载路径必须与 Composer 实际缓存路径一致：Alpine 镜像中通常是
/root/.composer/cache，Debian/Ubuntu 是/home/www-data/.composer/cache（若切换非 root 用户） - 不能替代分层顺序优化：即使挂载了 cache，如果
COPY . .出现在composer install之前，vendor 层照样失效
composer install该在哪个阶段运行？
必须在独立的 builder 阶段运行，且该阶段只包含依赖声明文件和安装命令。最终镜像里不该有composer二进制、composer.lock或任何 dev-only 包。
典型错误：在 final 阶段FROM php:8.3-apache里直接RUN composer install——这会让生产镜像带上 zip、git、curl 等构建工具，体积膨胀 100MB+，还可能因缺少扩展报错。
- builder 阶段推荐用
FROM php:8.3-cli AS builder，而非composer:2：前者能统一 PHP 版本和扩展（如 mbstring、json），避免“本地装得上、CI 装不上” - final 阶段用
FROM php:8.3-apache-slim或php:8.3-fpm-alpine，然后COPY --from=builder /app/vendor /app/vendor - builder 阶段不要
COPY . .，除非你真需要执行post-install-cmd（比如生成 config 或 dump-autoload）
私有包认证怎么安全传入 builder 阶段？
硬编码 token、挂载宿主机~/.composer/auth.json到镜像层、或用 ARG 传参，都会导致凭据泄露到镜像历史或 CI 日志里。唯一安全方式是 BuildKit 的 secret 挂载。
错误写法：RUN echo '{"http-basic": {"repo.example.com": {"username": "xxx", "password": "yyy"}}}' > /root/.composer/auth.json——凭据明文留在某一层里，docker history全可见。
- 在 docker build 命令中加
--secret id=composer_auth,src=$HOME/.composer/auth.json - 在 builder 阶段写
RUN --mount=type=secret,id=composer_auth,target=/tmp/auth.json composer config --global --auth http-basic.repo.example.com $(jq -r '.http-basic."repo.example.com".username' /tmp/auth.json) $(jq -r '.http-basic."repo.example.com".password' /tmp/auth.json) - 确保
auth.json文件权限为600，且不在 Git 中提交
多阶段构建里vendor/复制后权限不对怎么办？
builder 阶段默认以 root 运行，COPY --from=builder过来的vendor/目录属主仍是 root，而 final 阶段若用非 root 用户（如 www-data）运行 PHP-FPM，就会遇到Permission denied或 autoload 失败。
这不是 chmod 一下就能解决的临时补丁，而是构建流程设计缺陷。
- final 阶段起始就
USER www-data，但COPY --from=builder本身不支持指定属主，必须在 builder 阶段提前 chown - builder 阶段末尾加
RUN chown -R www-data:www-data /app/vendor && chmod -R u+rw /app/vendor（注意：先 chown 再 chmod，顺序反了会失败） - 更稳妥的做法是在 final 阶段
COPY --from=builder后立即RUN chown -R www-data:www-data /app/vendor，哪怕多一层也比权限错误强
真正容易被忽略的是：chown 必须在所有COPY完成后做，否则后续COPY . .覆盖的文件又变回 root 权限。
