根本原因是macos docker desktop的grpc-fuse/virtiofs桥接机制对vendor目录数千个小文件的bind mount触发高频元数据同步，必须改用命名卷或:cached挂载规避。
Mac 上 docker-compose 挂载 vendor/ 目录导致 composer install 极慢、autoload.php 找不到、甚至框架启动卡死——这不是配置写错了，是 macOS 文件系统桥接机制的硬伤，必须绕开，不能硬扛。
为什么 macOS 挂载 vendor 会变慢甚至失败
macOS 的 Docker Desktop 底层用的是 gRPC-FUSE（旧版）或 VirtioFS（新版），但无论哪种，对 vendor 这种含数千个 PHP 小文件的目录做 bind mount，都会触发大量跨系统元数据同步和权限检查。结果就是：composer dump-autoload 耗时翻倍，require 'vendor/autoload.php' 报错，或者容器内 PHP 进程直接 hang 住。
- 典型现象：
Class not found、Failed opening required 'vendor/autoload.php'、composer install卡在 “Installing dependencies” 10 分钟不动 - 不是镜像问题：Linux 主机上同一镜像 + 同一
docker-compose.yml完全正常 - 不是网络问题：即使已配阿里云镜像源、挂了缓存，只要 vendor 被挂载，性能就崩
彻底规避 vendor 挂载：用命名卷 + 只读映射
别再用 ./vendor:/var/www/html/vendor。改用命名卷（named volume），让 Docker 管理 vendor 的存储位置，彻底脱离宿主机文件系统瓶颈。
- 在
docker-compose.yml的volumes顶层声明命名卷：volumes: vendor:
- 在 service 中挂载为只读：
volumes: - ./src:/var/www/html/src:ro - vendor:/var/www/html/vendor:ro
- 构建镜像时确保 vendor 已预装：
RUN composer install --no-dev --optimize-autoloader，否则卷为空，PHP 仍报错 - 首次启动前可手动初始化卷：
docker volume create myapp-vendor（非必需，compose 会自动创建）
开发阶段必须挂代码？用 :cached 提升 I/O 效率
如果项目结构强制要求整目录挂载（比如 legacy 项目），至少得告诉 Docker Desktop：“这个目录我不需要实时一致性，只读+缓存就行”。
- 对 macOS，必须加
:cached后缀：volumes: - ./:/var/www/html:cached
-
:delegated在某些 Docker Desktop 版本下效果不稳定，优先选:cached - ⚠️ 注意：
:cached不适用于需要监听文件变更的场景（如某些 watch 模式），但对 composer 运行完全安全 - 不要对
vendor/单独加:cached—— 它没用，因为挂载点本身已是瓶颈源头
Alpine 镜像 + UID/GID 不匹配会导致缓存失效
很多 PHP 镜像用 Alpine，而 Alpine 默认以 root 或 www-data 用户运行。若宿主机 ~/.composer/cache 属于 UID 1001，但容器里用 UID 0 写缓存，就会权限拒绝，缓存不生效，每次重下包。
- 查宿主机 UID：
id -u，GID：id -g - 在 service 中显式指定用户：
user: "1001:1001"
（替换为你自己的 UID/GID） - 或改挂 cache 子目录（更稳妥）：
volumes: - ${COMPOSER_CACHE_DIR:-$HOME/.composer/cache}:/root/.composer/cache - Alpine 下避免用
/root/.composer，建议统一切到www-data用户并chown -R www-data:www-data /var/www/.composer
真正关键的不是“怎么调参数”，而是接受一个事实：macOS 上的 bind mount 本质不适合 vendor 这类高密度小文件目录。所有试图在挂载基础上“优化”的方案，最终都比不上换用命名卷 + 多阶段构建来得干净。一旦跨过这个认知门槛，问题就从“调参”变成了“重构挂载逻辑”。
