path仓库是重构老旧项目时控制依赖可见性与加载路径的精确开关，配错字段会导致composer install静默跳过、Class not found却无提示；常见问题包括repositories位置错误、url用绝对路径或file://前缀、本地包缺composer.json或name不匹配、autoload映射错误、未隔离环境导致CI失败，以及version字段缺失。

path仓库不是“让本地包跑起来”的快捷方式，而是重构老旧项目时控制依赖可见性与加载路径的精确开关——配错一个字段，composer install 就静默跳过，Class not found 报错却查不到源头。

为什么composer install完全无视你写的repositories

常见现象：加了 "type": "path" 配置，执行 composer install 后 vendor/ 里没出现对应目录，也不报错。

• 配置不在根级 repositories 数组里（比如误塞进 require 或 config 字段）
• url 是绝对路径（/home/user/packages/foo）或带 file:// 前缀——Composer 会直接忽略，不警告
• 本地包目录下没有 composer.json，或该文件语法错误、缺 name 字段（哪怕只写 {"name": "myorg/legacy-auth"} 也行）
• 主项目 composer.json 中 require 的包名（如 "myorg/legacy-auth": "*"）和本地包 composer.json 里的 name 不完全一致（大小写、vendor 名、斜杠方向都算）

autoload 映射错一个字符，Class not found 就甩锅给 Composer

老旧项目常把类文件散放在 lib/、classes/ 或无命名空间的 include/ 下。用 path 仓库接入时，自动加载必须显式对齐，否则 composer dump-autoload 无效。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• 子包 composer.json 的 autoload.psr-4 必须写成 "MyOrg\LegacyAuth\": "src/"（末尾不加 /），写成 "src/\" 或 "src" 会导致路径拼接多出双斜杠，文件找不到
• 如果旧代码没命名空间，改用 autoload.files：例如 "autoload": {"files": ["lib/functions.php", "include/config.php"]}
• 别指望 use-include-path —— 它在 Composer 2.0+ 已被移除，且仅影响 require_once，不解决类自动加载

开发改代码生效了，上线就崩？path 仓库必须环境隔离

CI/CD 构建失败的典型原因：生产服务器上根本不存在 ../packages/legacy-auth 这个路径，而 Composer 不会自动 fallback 到 Packagist 或私有源，而是直接报错退出。

• 永远不要把 path 配置提交到主干分支；开发时用 git stash 或分支隔离
• CI 脚本中第一步必须清理 repositories：可用 jq 删除 type=path 条目，或用 composer config --unset repositories（需 Composer ≥2.5）
• 更稳妥的做法：用环境变量驱动配置，例如 "url": "${PATH_REPO_LEGACY_AUTH:-./packages/legacy-auth}"，CI 中设空值即可跳过

最易被忽略的一点：path 仓库的 version 字段不是可选的。即使写 "dev-main" 或 "1.0.x-dev"，也必须存在——否则 Composer 解析时会认为包元数据不完整，拒绝加载，且不提示具体原因。