Composer不解析软链接目标路径，只检查当前目录下真实存在的composer.json；若pwd显示软链接路径，需用pwd -P确认物理路径，或改用composer -d "$(pwd -P)"执行命令。
软链接下 composer.json 被识别为不存在
Composer 不解析软链接目标路径，它只检查当前工作目录下 composer.json 的真实文件系统路径。如果你用 ln -s /real/path/myproject ./myproject，然后在链接目录里执行 composer install，它实际读的是 ./myproject/composer.json（即符号链接本身），而该路径下没有真实文件，自然报 “Could not find a composer.json file”。
常见现象：ls -l 看得见 composer.json，cat composer.json 也能读，但 composer install 仍 404；pwd 输出是软链接路径，不是真实路径。
- 执行前先运行
pwd -P（注意是大写 P），它会输出解析后的物理路径，确认是否真含composer.json - 如果
pwd -P显示的是/home/user/project，但ls -l显示composer.json -> /other/path/composer.json，说明你依赖的是跨目录软链接——Composer 不支持这种间接映射 - 临时解决：cd 到
pwd -P输出的真实路径再执行命令；长期方案：改用-d参数显式指定，例如composer -d "$(pwd -P)" install
path 类型仓库因软链接导致包 404
当你在 repositories 中配置 "type": "path" 并指向一个软链接目录时，Composer 会尝试读取该路径下的 composer.json，但若该路径是软链接且未解析，它可能跳过校验或读取空内容，最终在安装时提示 “Package vendor/name could not be found”。
关键点：path 仓库要求路径必须是**可遍历的绝对路径**，且 composer.json 必须存在于该路径下（不能是软链接指向别处）。
- 修复方式：用
realpath替换软链接路径，例如composer config repositories.mypkg path "$(realpath ./local-pkg)" - 路径末尾不能带
/：写成/home/user/pkg/会被拒绝，必须是/home/user/pkg - 执行后验证：运行
composer config --list | grep mypkg，确认输出中"url"字段是完整绝对路径，且"type"为"path"
容器挂载 + 软链接引发的 404 连锁反应
在 Docker 或 CI 环境中，宿主机用软链接组织项目结构，再挂载进容器，容易触发双重路径失配：宿主机软链接未解析 + 容器内无对应路径权限或挂载点错位。
典型错误链：docker run -v $(pwd):/app … 中 $(pwd) 是软链接路径 → 容器内 /app 挂载的是符号链接本身 → composer install -d /app 查不到 /app/composer.json → 报 404。
- 构建前在宿主机运行
cd "$(realpath .)"，再启动容器，确保挂载的是真实路径 - CI 脚本中避免直接
cd到软链接目录后再执行 Composer；改用composer -d "$(realpath .)" install - 若必须保留软链接结构，可在容器启动时加一层初始化脚本：先
cp -rL /app/. /work/（-L强制解引用），再cd /work && composer install
autoload 映射不生效的隐藏原因
软链接本身不影响 autoload，但如果你把本地包放在软链接目录下、又没用 realpath 配置 path 仓库，那么 composer dump-autoload 生成的 classmap 会记录软链接路径（如 /var/www/myapp/local-pkg/src/Helper.php），而 PHP 实际加载时走的是真实路径（如 /home/user/pkg/src/Helper.php），opcode 缓存或 PSR-4 解析就会失败，表现像“类找不到”，底层却是路径不一致。
- 运行
composer show -p | grep your-class-name，看 classmap 中记录的路径是否为你预期的真实路径 - 只要用了 path 仓库，就必须确保
composer config repositories.xxx path设置的是realpath结果，而非原始软链接路径 - 修改完配置后，务必删掉
vendor/composer/autoload_*.php和composer.lock，再跑composer install，否则旧映射残留
