根本原因是DNS解析失败或超时，不是网络慢——packagist.org域名未被正确解析，导致Composer卡在初始化阶段；宿主机能上网不代表容器内DNS可用，常见于Docker Desktop、内网无DNS转发的Linux及云厂商定制镜像。
为什么 composer install 在容器里卡在 “Loading composer repositories”
根本原因是 DNS 解析失败或超时，不是网络慢——packagist.org 域名根本没被正确解析，导致 Composer 卡在初始化阶段。宿主机能上外网，不代表容器内 DNS 可用。常见于 macOS/Windows 的 Docker Desktop、内网无 DNS 转发的 Linux 环境，以及某些云厂商定制镜像。
验证方式：进容器执行 nslookup packagist.org 或 ping -c 1 packagist.org，若报 server can't find packagist.org: NXDOMAIN 或直接超时，就坐实了 DNS 问题。
- 启动容器时加
--dns 114.114.114.114或--dns 8.8.8.8是最快验证手段 - Docker Desktop 用户可在 GUI 设置 → Docker Engine 中追加
"dns": ["114.114.114.114"] - Linux 宿主机若改过
/etc/resolv.conf，需确认dockerd是否继承该配置（检查systemctl show docker | grep DNS）
如何让 composer config -g 生效但不污染构建缓存
在 Dockerfile 中写 RUN composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/ 看似合理，但会导致整个 Composer 全局配置层无法被缓存复用——只要这一行上游层变动，后续所有依赖安装都得重来。
更稳妥的做法是把镜像源配置“下沉”到构建阶段最前端，且与依赖文件分离：
- 先
COPY composer.json composer.lock ./（触发缓存起点） - 紧接着
RUN composer config --global repos.packagist composer https://mirrors.aliyun.com/composer/ && composer install --no-dev --prefer-dist --no-progress，合并为单条RUN指令 - 避免单独执行
composer config，防止它生成一个无意义的中间层
注意：--global 配置写入的是 /root/.composer/config.json，对非 root 用户无效；若容器以 www-data 运行，应改用 --auth 或在 composer.json 中声明 repositories 字段。
挂载 vendor 目录时为什么反而变慢甚至报 permission denied
直接 docker run -v $(pwd):/app -v $(pwd)/vendor:/app/vendor 是典型误区：既没解决性能问题，又引入权限和一致性风险。
- macOS/Windows 下，宿主机目录挂载走 gRPC-FUSE，
vendor里成千上万的小文件反复 stat/read/write，I/O 延迟飙升 - 宿主机
vendor权限常为 root，而容器内 PHP 进程以非 root 用户运行，导致composer dump-autoload失败 - 本地
vendor和容器内 PHP 版本/扩展不一致，autoload_classmap.php可能失效
正确做法是：只挂载代码目录，vendor 完全交给容器管理。开发调试需要热更新？用命名卷 + composer install 显式重建：
docker run -v $(pwd):/app -v composer-vendor:/app/vendor php:8.3-cli sh -c "cd /app && composer install --no-dev"
其中 composer-vendor 是通过 docker volume create composer-vendor 创建的命名卷，由 Docker 管理 I/O，不经过宿主机文件系统。
BuildKit 缓存挂载后 composer install 仍重复下载包
启用 --mount=type=cache,id=composer-cache,target=/tmp/cache/composer 后仍无效果，大概率是 COMPOSER_CACHE_DIR 没对齐。
Composer 默认缓存路径是 ~/.composer/cache，而 BuildKit 挂载的是 /tmp/cache/composer，两者不一致，缓存完全不命中。
- 必须显式设置环境变量：
COMPOSER_CACHE_DIR=/tmp/cache/composer - 确保
composer install命令在同一个RUN层中执行，不能拆成多条指令（否则挂载上下文丢失） - 检查是否误用了
--no-cache或COMPOSER_CACHE_DIR=/dev/null类覆盖配置
一个可靠写法：
RUN --mount=type=cache,id=composer-cache,target=/tmp/cache/composer \
COMPOSER_CACHE_DIR=/tmp/cache/composer \
composer install --no-dev --prefer-dist --no-progress
这个组合能稳定复用已下载的 .zip 包，跳过 90% 以上的网络请求——但前提是你的 CI/CD 或本地构建也开启 BuildKit（export DOCKER_BUILDKIT=1）。
真正难调的从来不是某一行配置，而是 DNS、缓存路径、用户权限这三者在不同环境下的隐式耦合。比如 macOS 上 DNS 正常但挂载慢，Linux 上挂载快但 DNS 不通，同一份 docker-compose.yml 在两台机器上表现迥异——这时候别猜，先 docker exec -it xxx cat /etc/resolv.conf && ls -l /app/vendor，看事实，不动手永远绕不出循环。
