根本原因是docker层缓存被错误的copy顺序打断；必须先单独copy composer.json和composer.lock ./，再run composer install --no-dev --prefer-dist --optimize-autoloader，最后copy . .，确保lock文件稳定且路径正确，才能使vendor层真正复用。
根本原因不是 Composer 慢，而是 Docker 层缓存被你亲手打断了。 只要 composer.lock 没变，vendor/ 就不该重装——但现实中它总在重装，说明你的 Dockerfile 顺序或参数踩了坑。
为什么 COPY . /app 后再 RUN composer install 总是重装？
这是最典型的缓存断链写法。Docker 构建时从上到下逐层计算哈希，一旦 COPY . /app 出现在 RUN composer install 之前，哪怕只改了一个 README.md，前面所有层（包括依赖安装）都会失效。
-
COPY . /app把整个项目目录（含频繁变更的 PHP 文件、.env、日志等）一次性塞进镜像，导致该层哈希永远不一致 -
RUN composer install被迫跟着重新执行，所有包重新下载、解压、生成 autoload - 即使你本地有
~/.composer/cache，容器里默认也用不上——它压根没挂载进来
怎么让 vendor 层真正可复用？
核心就一条：让 composer install 这一层只依赖极少数稳定文件，并且尽可能早地执行。
-
COPY composer.json composer.lock ./—— 注意结尾是./，不是/app或漏掉斜杠，路径错会导致文件没落对位置 -
RUN composer install --no-dev --prefer-dist --optimize-autoloader --no-scripts——--no-scripts防止某些包的 post-install-cmd 触发额外逻辑，破坏可重现性 -
COPY . .放在这之后，确保源码变更完全不影响前面的 vendor 层 - 必须保证
composer.lock提交进 Git，且换行符统一（git config core.autocrlf input），否则 CRLF/LF 差异会让哈希不一致
BuildKit 下怎么复用 Composer 包缓存？
光靠 Docker 层缓存只能避免重复安装，但不能跳过下载。BuildKit 的 --mount=type=cache 才能真正复用已下载的 dist 包。
- 先确认启用 BuildKit：
export DOCKER_BUILDKIT=1或在docker build命令加--progress=plain RUN --mount=type=cache,id=composer-cache,target=/tmp/composer-cache COMPOSER_CACHE_DIR=/tmp/composer-cache composer install --no-dev --prefer-dist-
id=composer-cache是关键，不同构建间靠这个 ID 共享缓存；不写id等于每次新建一个空缓存 -
target必须和COMPOSER_CACHE_DIR一致，可通过composer config cache-dir查实际路径，默认是/root/.composer/cache，但容器内常映射到临时路径更稳
多阶段构建中 vendor 怎么安全传递？
别直接 COPY --from=builder /app/vendor /app/vendor 就完事——如果 builder 阶段用了 --no-dev，而 final 阶段又漏了某些扩展（比如 ext-pdo），运行时可能报错“Class not found”或“extension missing”。
- final 镜像的基础镜像（如
php:8.3-cli）必须提前装好composer.json中声明的所有必需扩展 - 检查
composer.lock顶部的platform字段，若缺失 PHP 版本或扩展约束，CI 中应加composer update --lock --with-all-dependencies校验并提交 - 避免在 final 阶段再次运行
composer install—— 它会覆盖 builder 阶段的优化结果，且无法复用 layer cache - 如果要用
autoload.php的 classmap 权威模式，构建时就得加--classmap-authoritative，运行时不能再动态扫描
最容易被忽略的其实是 composer.lock 的稳定性本身：它不是“有就行”，而是必须和构建环境的 PHP 版本、扩展、甚至 composer 自身版本对齐。一次 composer update 后没提交 lock 文件，或者 CI 中用了 --ignore-platform-reqs，缓存再完美也白搭。
