根本原因是Docker构建层缓存被破坏：只要composer.json或composer.lock变动，后续composer install就无法命中缓存，导致vendor/重建；错误挂载volume或COPY . .会覆盖已安装依赖。
为什么 composer install 在 Docker 里每次都要重装所有包？
根本原因不是 Composer 本身的问题，而是 Docker 构建层缓存被破坏：只要 composer.json 或 composer.lock 有变动（哪怕只改一行注释），后续的 composer install 就无法命中缓存，导致整个 vendor/ 目录重建。更糟的是，如果把 vendor/ 挂载为 volume 或用 COPY . . 覆盖，还会覆盖掉已安装的依赖。
- 典型错误写法：
COPY . .→ 覆盖了上一层缓存生成的vendor/ - 没锁定
composer.lock文件，或提交时漏掉了它 → 导致每次解析依赖树不一致 - 在容器运行时执行
composer install（而非构建时）→ 容器启动变慢，且无法复用构建缓存
如何让 Docker 构建真正复用 Composer 缓存？
关键在于分层 COPY：先只拷贝 composer.json 和 composer.lock，运行 composer install --no-dev --prefer-dist，再拷贝其余源码。这样只要锁文件不变，Docker 就能复用该层缓存。
minimax-mcp-docker版（适配极空间）
下载
MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。
- 必须使用
--prefer-dist：避免下载完整 Git 仓库，加快安装且更稳定 - 务必加
--no-dev（除非需要 dev 依赖）：减小镜像体积、避免误将测试工具打入生产镜像 -
composer.lock必须存在且和composer.json版本匹配，否则 Composer 会报错Your lock file does not contain a compatible set of packages - 推荐在
Dockerfile中显式指定 PHP 和 Composer 版本，例如：RUN php -v && composer --version，避免因基础镜像升级导致行为突变
增量更新依赖时怎么避免全量重装？
所谓“增量更新”，本质是只更新变更部分——这只有在 composer.lock 精确记录差异的前提下才成立。直接改 composer.json 后运行 composer update foo/bar 是安全的；但若用 composer update 不带参数，就可能连带升级其他未声明变更的包，破坏可重现性。
- 更新单个包：先在宿主机运行
composer update foo/bar --with-all-dependencies，再提交更新后的composer.lock，最后重建 Docker 镜像 - 禁止在容器内运行
composer update：容易因环境差异（如 PHP 扩展缺失）导致锁文件生成不一致 - 若需调试依赖冲突，可在构建阶段临时加
--verbose，但不要保留在生产Dockerfile中 - 注意
platform配置：如果composer.json里写了"platform": {"php": "8.2"}，而容器中实际是 PHP 8.3，Composer 可能降级安装旧版扩展
中文环境下常见陷阱：镜像源、字符编码、路径权限
国内用户常配阿里云或腾讯云镜像源，但要注意镜像源地址是否支持 HTTPS、是否要求 User-Agent，以及是否与 Composer 版本兼容。另外，vendor/ 写入失败往往不是网络问题，而是权限或挂载方式不对。
- 设置镜像源要写进
composer.json的repositories字段，或通过COMPOSER_REPO_PACKAGIST=https://mirrors.aliyun.com/composer环境变量传入，别用composer config命令——该命令会写入全局配置，在 Docker 构建中不可控 - 确保
WORKDIR存在且可写，尤其当用非 root 用户运行时：RUN mkdir -p /app && chown www-data:www-data /app - Windows 宿主机 + WSL2 构建时，注意行尾符（CRLF vs LF）可能导致
composer.lock被 Git 标记为修改，干扰缓存命中 - 中文路径名本身不影响 Composer，但某些旧版 Composer 在解析含 Unicode 的
autoload规则时可能出错，建议类名和命名空间保持 ASCII
composer.lock 当作“临时文件”而没纳入版本管理，或者在 CI/CD 流水线中跳过 composer install 的校验步骤——这两点会让“增量更新”变成不可控的全量漂移。 
