Composer 处理软链接符号冲突导致的部署失败问题使用

先说结论：Composer 在软链接目录下报“Cannot create cache directory”的核心原因，是它基于 getcwd() 解析真实路径后，去拼接 ~/.composer/cache 作为缓存路径——结果这个路径要么压根不存在，要么权限受限。解决方案很简单：显式设置 COMPOSER_HOME 为一个真实可写的绝对路径，并确保属主正确。

为什么 composer install 在软链接目录下会报错 “Cannot create cache directory”？

原因在于 Composer 默认把缓存写到 ~/.composer/cache。但当项目路径本身是软链接时——比如 /var/www/current 指向 /var/www/releases/20241001——而 COMPOSER_HOME 又没有显式设置，Composer 就会基于 getcwd() 解析出真实路径，再拼接缓存路径。结果呢？很可能指向一个不存在的父目录，或者权限受限的挂载点。常见的错误信息是 Failed to write cache file 或 Permission denied: ~/.composer/cache/repo/https---packagist.org/provider-xxx.json。

解决办法也不复杂，记住这几点：

• 确保 COMPOSER_HOME 指向一个真实、可写的绝对路径，且不依赖当前工作目录的符号链接解析
• 千万别用 ~ 这种相对写法，必须用完整绝对路径，比如 /home/deploy/.composer
• 如果部署用户是 deploy，确认该路径的属主和权限正确：chown -R deploy:deploy /home/deploy/.composer
• 在 CI/CD 或部署脚本中，务必在 composer install 前导出变量：export COMPOSER_HOME="/home/deploy/.composer"

如何让 composer install 忽略 vendor 目录的软链接校验？

这里要厘清一个常见误解：Composer 本身并不会专门去校验 vendor 是否为软链接。但问题出在哪呢？当启用 --no-dev 或使用 COMPOSER_CACHE_DIR 时，如果缓存或 vendor 所在文件系统不一致（比如 tmpfs 和 NFS 混合），会因 inode 判断失败抛出 RecursiveDirectoryIterator 类错误。

更常见的场景是：你手动 ln -s vendor 到共享目录，但 Composer 检测到目标已存在且非空，直接拒绝覆盖。这其实是一个很自然的保护机制——Composer 不希望破坏你自己创建的目录结构。

那么正确的做法是什么？

• 不要在运行 composer install 之前提前创建 vendor 软链接；它只接受空白目录或完全由自己管理的 vendor
• 如果需要复用 vendor（比如多版本共用），改用 COMPOSER_VENDOR_DIR 环境变量指向真实路径：COMPOSER_VENDOR_DIR="/var/www/shared/vendor" composer install --no-dev
• 避免在 composer.json 中写 "vendor-dir": "path/to/symlink"——Composer 会尝试 mkdir，而软链接不是目录，直接报 mkdir(): File exists

部署时怎么安全地切换软链接而不触发 Composer 重装？

这是实际运维中最棘手的场景：你用 ln -sf releases/20241001 current 切换线上版本，但新 release 目录里没有 vendor，导致下次请求时 PHP 自动加载失败。关键不是 Composer 运行的时机，而是确保每次 release 构建阶段就完成 vendor 安装，而非线上运行时。

几个实操经验：

• 所有 composer install 必须在构建机（build server）或 release 目录内执行完毕，生成完整的 vendor 和 autoload.php
• 不要在 shared 目录里放 vendor 并软链接过去——不同 PHP 版本或扩展差异会导致 composer.lock 兼容性问题
• 如果必须共享部分包（比如大型二进制扩展），用 composer create-project 加上 --repository-url 指向私有镜像，而不是跨 release 共享 vendor
• 检查 autoload.php 中的路径是否硬编码了 release 路径——通过 composer dump-autoload --optimize 可以减少动态路径依赖

说到底，软链接本身不是问题，问题总出在路径解析与环境变量没对齐。最容易被忽略的是 COMPOSER_HOME 和 COMPOSER_VENDOR_DIR 没有在部署用户的 shell profile 或 systemd service 文件里持久化设置。把这个补上，绝大部分软链接相关的 Composer 报错就能迎刃而解。