必须用相对路径，且严格相对于项目根目录（即composer.json所在位置）；绝对路径在ci或换环境时必然失效，正确写法如"../my-local-package"或"packages/my-utils"，禁止使用"/home/user/..."、"$home/..."或"./..."。
path仓库必须用绝对路径还是相对路径？
相对路径是唯一安全选择，且必须相对于项目根目录（即 composer.json 所在位置）。Composer 会自动将其转为绝对路径解析，但如果你手写绝对路径（比如 /home/user/my-pkg），CI 环境或换机器后必然失效。
常见错误现象：Could not find package vendor/name at any version，尤其在 GitLab CI 或 Docker 构建中——因为路径根本不存在或用户权限不对。
- 正确写法：
"url": "../my-local-package"（上层目录）或"url": "packages/my-utils"（同级子目录） - 禁止写法：
"url": "/var/www/my-pkg"、"url": "$HOME/my-pkg"、"url": "./my-pkg"（./在某些 Composer 版本里不被识别） - 验证方式：运行
composer config repositories，看输出的url值是否已展开为完整路径（Composer 内部会做转换，但输入必须是相对的）
为什么加了path仓库还是找不到本地包？
最常被忽略的是包名不一致。Composer 不是“看到目录就加载”，而是严格按 name 字段匹配——你本地包的 composer.json 里写的 "name": "acme/utils"，主项目 require 的也必须是 "acme/utils": "*"，一个字母都不能错，大小写敏感。
- 检查点1：进入本地包目录，执行
composer validate，确认name格式合法（必须含/，不能是纯单词） - 检查点2：主项目
composer.json中repositories数组必须在require之前声明，顺序无关，但若用了packagist.org: false，它必须放在根层级，不能嵌套 - 检查点3：本地包目录下必须有有效的
composer.json，且不能是空文件或只有注释；没有autoload段不会报错，但类将无法自动加载
path仓库支持版本别名（如 dev-main）吗？
不支持。这是 path 类型仓库和 vcs 类型最本质的区别之一。当你写 "acme/utils": "dev-main"，Composer 会直接忽略 path 仓库，转而尝试去 packagist.org 或其他 vcs 源查找 —— 即使你本地包的 composer.json 里写了 "version": "dev-main"，也没用。
- 可用方案：用稳定版本号，比如
"acme/utils": "1.0.x-dev"，并在本地包composer.json中设"version": "1.0.x-dev" - 更灵活做法：用
"acme/utils": "@dev"，配合本地包中"minimum-stability": "dev"和"prefer-stable": true - 危险操作：不要在
repositories里混用type: "path"和type: "vcs"指向同一name，Composer 行为未定义，可能随机选一个
如何让path仓库生效后立即看到变更？
Composer 默认缓存包元数据，改了本地包的 composer.json 或代码后，composer update 可能仍拉旧版本。这不是 bug，是设计行为。
- 强制刷新方式：
composer update --with-dependencies acme/utils（指定包名） - 彻底清缓存：
composer clear-cache，但注意这会清掉所有 dist 包缓存，下次 install 变慢 - 开发友好技巧：在本地包目录执行
composer dump-autoload，确保新类能被自动加载；主项目则需composer dump-autoload或删掉vendor/autoload.php后重装 - 关键提醒：
composer install不会重新解析 path 仓库，它只认composer.lock；要测试变更，必须用update，不是install
composer update 这一步，或者误用了 @dev 别名导致 path 仓库被跳过。路径、包名、版本三者对齐，才是 path 仓库真正起效的前提。
